cf.read

cf.read(files, verbose=False, index=None, ignore_ioerror=False, close=False, aggregate=True, squeeze=1, prop={}, attr={}, coord={}, cellsize={})

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

Currently supports netCDF and PP formats.

Each field contains it’s file name in its file attribute and, where appropriate, its netCDF variable name in its ncvar attribute. Note that fields may be selected by netCDF variable name by setting a value (or values) of ‘ncvar’ via the attr keyword.

Fields referenced by formula_terms transforms within other fields are not included in the returned list of fields.

Parameters :

files : str or sequence of strs

A string or sequence of strings giving the file names or OPenDAP URLs from which to read fields. For files on disk, the file names may contain wild cards 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.

close : bool, optional

If True then close each file after it has been read.

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.

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 provide these parameters to the aggregate function.

prop : dict, optional

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

attr : dict, optional

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

coord : dict, optional

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

cellsize : dict, optional

Only return 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)>]