cf.read

cf.read(files, read_data=False, verbose=False, index=None, ignore_ioerror=False, close=False, aggregate=True, calendar=None, long_name=None, standard_name=None, units=None, extract={})

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

By default, all data arrays from all field components are not read from disk but are stored in the returned fields as file pointers. This behaviour may be changed with the read_data parameter.

NetCDF dimension names are stored in the nc_dimensions attribute of a field’s space and netCDF variable names are stored in the private attribute ncvar of the field and each of its space components.

Fields referenced by formula_terms transforms are not included in the returned list of fields. A field may be referenced in the transforms of multiple output fields, so in-place changes to that field in one transform will be seen in the other fields which reference it.

Parameters:

• files (str or sequence) – 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 glob module.
• read_data – Optional. If True then read the data of each field, including the data of its space components into memory Otherwise all data are stored as file pointers.
• index (None or int) – Optional. If None then return all possible fields from the input files. If a non-negative integer then only return the field with this index in the otherwise full list of fields.
• verbose (bool) – Optional. If True then print information to stdout.
• close (bool) – Optional. If True then close each file after it has been read.
• exact (bool) – Optional. If True then field selection cirteria names are considered exact, as opposed to abbreviations.
• ignore_ioerror (bool) – Optional. If True then ignore files which produce IO errors (such as empty files, for example).
• aggregate (bool) – Optional. If True then aggregate the fields read in from all input files into as few fields as possible using the CF aggregation rules. (Note that this code has not yet been optimsed for speed or memory usage.)
• calendar (str) – Optional. Equivalent to setting ‘calendar’ in the extract keyword dictionary. Forces the exact keyword to be True.
• long_name (str) – Optional. Equivalent to setting ‘long_name’ in the extract keyword dictionary. Forces the exact keyword to be True.
• standard_name (str) – Optional. Equivalent to setting ‘standard_name’ in the extract keyword dictionary. Forces the exact keyword to be True.
• units (str) – Optional. Equivalent to setting ‘units’ in the extract keyword dictionary. Forces the exact keyword to be True.
• extract (dict) – Optional. A dictionary of field selection criteria. Only fields which match the criteria are returned. Refer to match (if exact is True) or ematch (if exact is False) for details.

Returns:

A list of fields in a FieldList object.

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', extract={'units': 'K'})
[<CF Field: temperature(17, 30, 24)>,
 <CF Field: temperature_wind(17, 29, 24)>]

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