cf.read

cf.read(files, verbose=False, index=None, ignore_ioerror=False, aggregate=True, umversion=4.5, squeeze=False, unsqueeze=False, format=None, prop={}, attr={}, coord={}, cellsize={})

Read fields from files from disk or from an OPeNDAP server.

Any amount of any combination of CF-netCDF, CFA-netCDF and Met Office (UK) PP format files be input for reading.

CF-netCDF files

• Each field contains its file name in its file attribute.
• The netCDF variable names of the field and its components are stored in the ncvar attributes.
• Note that fields may be selected by netCDF variable name by setting a value (or values) of 'ncvar' via the attr parameter.
• Fields referenced within CF-netCDF formula_terms or ancillary variables are not included in the returned list of fields.

PP files

• Each field contains its file name in the file attribute.
• It may be necessary to specify the Unified Model (UM) version. See the umversion parameter for details.
• If any PP files are read then the aggregate option 'no_strict_units' is set to True for all input files.

Files on an OPeNDAP server

• All files on OPeNDAP servers are assumed to be CF-netCDF or CFA-netCDF files.

CFA-netCDF files

• See the notes for CF-netCDF files.

Parameters :

files : (arbitrarily nested sequence of) str

A string or arbitrarily nested sequence of strings giving the file names or OPenDAP URLs from which to read fields. When on disk, the file names may contain UNIX file name metacharacters as understood by the python glob module.

index : int, optional

Only return the field with this non-negative index in the otherwise returned full list of fields. By default return all (otherwise selected) fields from the input files.

verbose : bool, optional

If True then print information to stdout.

umversion : int or float, optional

For PP format files only, the Unified Model (UM) version to be used when decoding the PP header. Valid versions are, for example, 4.2, '6.6.3' and '8.2'. The default version is 4.5. The version is ignored if it can be inferred from the PP headers, which will generally be the case for files created at versions 5.3 and later. Note that the PP header can not encode tertiary version elements (such as the 3 in '6.6.3'), so it may be necessary to provide a UM version in such cases.

Ignored for any non-PP input files.

ignore_ioerror : bool, optional

If True then ignore any file which raises an IOError whilst being read, as would be the case for an empty file, unknown file format, etc. By default the IOError is raised.

format : str, optional

Only read files of the given format, ignoring all other files. Valid formats are 'NETCDF' for CF-netCDF files, 'CFA' for CFA-netCDF files and 'PP' for PP files. By default files of any of these formats are read.

aggregate : bool or dict, optional

If True or a dictionary then aggregate the fields read in from all input files into as few fields as possible using the CF aggregation rules. If a dictionary then it is passed as keyword arguments to the aggregate function. If False then the fields are not aggregated.

squeeze : bool, optional

If True then remove size 1 dimensions from each field’s data array.

unsqueeze : bool, optional

If True then insert size 1 dimensions from each field’s domain into its data array.

prop : dict, optional

Only read fields matching the given conditions on their CF properties. Refer to the field’s match method for details.

attr : dict, optional

Only read fields matching the given conditions on their attributes. Refer to the field’s match method for details.

coord : dict, optional

Only read fields matching the given conditions on their coordinates. Refer to the field’s match method for details.

cellsize : dict, optional

Only read fields matching the given conditions on their coordinates’ cellsizes. Refer to the field’s match method for details.

Returns :

out : FieldList

A list of fields.

Raises :

IOError :

Raised if ignore_ioerror is False and there was an I/0 related failure, including unknown file format.

Examples

>>> f = cf.read('file*.nc')
>>> type(f)
<class 'cf.field.FieldList'>
>>> f
[<CF Field: pmsl(30, 24)>,
 <CF Field: z-squared(17, 30, 24)>,
 <CF Field: temperature(17, 30, 24)>,
 <CF Field: temperature_wind(17, 29, 24)>]

>>> cf.read('file*.nc')[0:2]
[<CF Field: pmsl(30, 24)>,
 <CF Field: z-squared(17, 30, 24)>]

>>> cf.read('file*.nc', index=0)
[<CF Field: pmsl(30, 24)>]

>>> cf.read('file*.nc')[-1]
<CF Field: temperature_wind(17, 29, 24)>

>>> cf.read('file*.nc', prop={'units': 'K'})
[<CF Field: temperature(17, 30, 24)>,
 <CF Field: temperature_wind(17, 29, 24)>]

>>> cf.read('file*.nc', attr={'ncvar': 'ta'})
[<CF Field: temperature(17, 30, 24)>]

>>> cf.read('file*.nc', prop={'standard_name': '.*pmsl*', 'units':'K|Pa'})[0]
<CF Field: pmsl(30, 24)>

>>> cf.read('file*.nc', prop={'units':['K, 'Pa']})
[<CF Field: pmsl(30, 24)>,
 <CF Field: temperature(17, 30, 24)>,
 <CF Field: temperature_wind(17, 29, 24)>]