cf.read

cf.read(files, verbose=False, ignore_read_error=False, aggregate=True, umversion=4.5, nfields=None, squeeze=False, unsqueeze=False, fmt=None, select=None, select_options={}, top_level=None, height_at_top_of_model=None, recursive=False, follow_symlinks=False)[source]

Read fields from files into cf.Field objects.

A file may be on disk or on a OPeNDAP server.

Any amount of any combination of CF-netCDF and CFA-netCDF files (or URLs if DAP access is enabled), Met Office (UK) PP files and Met Office (UK) fields files format files may be read.

netCDF files
  • The netCDF variable names of the field and its components are stored in their ncvar attributes.
  • Fields referenced within coordinate reference or ancillary variables objects are not included in the returned list of fields.
PP files
  • If any PP files are read then the aggregate option 'relaxed_units' is set to True for all input files.
  • STASH code to standard conversion uses the table in cf/etc/STASH_to_CF.txt.
Files on OPeNDAP servers
  • All files on OPeNDAP servers are assumed to be netCDF files.

See also

cf.write

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. Various type of expansion are applied to the file names:

Expansion Description
Tilde An initial component of ~ or ~user is replaced by that user‘s home directory.
Environment variable Substrings of the form $name or ${name} are replaced by the value of environment variable name.
Pathname A string containing UNIX file name metacharacters as understood by the glob module is replaced by the list of matching file names. This type of expansion is ignored for OPenDAP URLs.

Where more than one type of expansion is used in the same string, they are applied in the order given in the above table.

Example: If the environment variable MYSELF has been set to the “david”, then '~$MYSELF/*.nc' is equivalent to '~david/*.nc', which will read all netCDF files in the user david’s home directory.

verbose : bool, optional

If True then print information to stdout.

umversion : int or float, optional

Met Office (UK) PP files and Met Office (UK) fields files only, the Unified Model (UM) version to be used when decoding the PP header. Valid versions are, for example, 402 or 4.2 (v4.2), 606.3 (v6.6.3) and 1001 or 10.1 (v10.1). The default version is 4.5 (v4.5). The version is ignored if it can be inferred from the PP headers, which will generally be the case for files created at v5.3 and later. Note that the PP header can not encode tertiary version elements (such as the 3 in 606.3), so it may be necessary to provide a UM version in such cases.

Ignored for any other type of input files.

ignore_read_error : 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.

fmt : 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 and ‘FF’ for UM fields files. By default files of any of these formats are read. default files of any of these formats are read.

aggregate : bool or dict, optional

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

squeeze : bool, optional

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

unsqueeze : bool, optional

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

select, select_options : optional

Only return fields which satisfy the given conditions on their property values. Only fields which, prior to any aggregation, satisfy f.match(select, **select_options) == True are returned. See cf.Field.match for details.

top_level : (sequence of) str, optional

Promote field components to independent top-level fields. The top_level parameter may be or, or a sequence, of:

top_level Extra top-level fields
'reference' Fields in coordinate reference objects
'ancillary' Ancillary data fields
'field' Fields in coordinate references and ancillary data fields
'auxiliary' Auxiliary coordinate objects
'measure' Cell measure objects
'all' All of the above
Example:

To promote fields in coordinate reference objects: top_level='reference' or top_level=['reference'].

Example:

To promote ancillary data fields and cell measure objects: top_level=['ancillary', 'measure'].

New in version 1.0.4.

recursive : bool, optional

If True then allow directories to be specified by the files parameter and recursively search the directories for files to read.

New in version 1.1.9.

follow_symlinks : bool, optional

If True, and recursive is True, then also search for files in directories which resolve to symbolic links. By default directories which resolve to symbolic links are ignored. Ignored of recursive is False. Files which are symbolic links are always followed.

Note that setting recursive=True, follow_symlinks=True can lead to infinite recursion if a symbolic link points to a parent directory of itself.

New in version 1.1.9.
Returns:
out : cf.FieldList or cf.Field

A list of fields, or if there is only one field, the individual field.
Examples: 
>>> f = cf.read('file*.nc')
>>> 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')[-1]
<CF Field: temperature_wind(17, 29, 24)>

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

>>> cf.read('file*.nc', select='ncvar%ta')
<CF Field: temperature(17, 30, 24)>

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

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