# cf.read

`cf.``read`(files, verbose=False, ignore_read_error=False, aggregate=True, nfields=None, squeeze=False, unsqueeze=False, fmt=None, select=None, select_options={}, field=None, height_at_top_of_model=None, recursive=False, follow_symlinks=False, um=None, chunk=True, _debug=False)

  Read fields from netCDF, PP or UM fields files.

  Files 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.

  Notes for PP and UM fields files
    - 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`.
  Notes for files on OPeNDAP servers
    - All files on OPeNDAP servers are assumed to be netCDF files.

  See also

  `cf.read_field`, `cf.write`

  Examples 1: |

      >>> f = cf.read('file.nc')

  > > 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: Deprecated. Use the um parameter instead. 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(description=select, **select_options) == True` are returned. See `cf.Field.match` for details. field: (sequence of) `str`, optional Create independent fields from field components. The field parameter may be one, or a sequence, of:
    > field | Field components
    > --- | ---
    > `'field_ancillary'` | Field ancillary objects
    > `'domain_ancillary'` | Domain ancillary objects
    > `'dimension'` | Dimension coordinate objects
    > `'auxiliary'` | Auxiliary coordinate objects
    > `'measure'` | Cell measure objects
    > `'all'` | All of the above
    > Example: To create fields from auxiliary coordinate objects: `field='auxiliary'` or `field=['auxiliary']`. Example: To create fields from domain ancillary and cell measure objects: `field=['domain_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. um: `dict`, optional For Met Office (UK) PP files and Met Office (UK) fields files only, provide extra decoding instructions. This option is ignored for input files which are not PP or fields files. In most cases, how to decode a file is inferrable from the file’s contents, but if not then each key/value pair in the dictionary sets a decoding option as follows:
    > Key | Value
    > --- | ---
    > `'fmt'` | The file format (`'PP'` or `'FF'`)
    > `'word_size'` | The word size in bytes (`4` or `8`)
    > `'endian'` | The byte order (`'big'` or `'little'`)
    > `'version'` | The Unified Model version to be used when decoding the header. Valid versions are, for example, `4.2`, `'6.6.3'` and `'8.2'`. The default version is `4.5`. In general, a given version is ignored if it can be inferred from the header (which is usually the case for files created by the UM at versions 5.3 and later). The exception to this is when the given version has a third element (such as the 3 in 6.6.3), in which case any version in the header is ignored.
  If format is specified as PP then the word size and byte order default to `4` and `'big'` repsectively. Example: To specify that the input files are 32-bit, big-endian PP files: `um={'fmt': 'PP'}` Example: To specify that the input files are 32-bit, little-endian PP files from version 5.1 of the Unified Model: `um={'fmt': 'PP', 'endian': 'little', 'version': 5.1}` New in version 1.5.
  Returns: | out: `cf.FieldList` A list of the fields found in the input file(s). The list may be empty.
  Examples 2: |

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