cf.read

cf.read(files, data=False, verbose=False, index=None, exact=False, **kwargs)

Read spaces from netCDF files from disk or from an OPeNDAP server.

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

The netCDF dimension names are stored in the nc_dimensions attribute of a space’s grid and the netCDF variable names are stored in the ncvar attributes of the space and its grid components (coordinates, coordinate bounds, cell measures and transformations).

Note that if a single space has been requested by setting the index parameter and that space contains other spaces as part of a coordinate transformation or in a list ancillary variables, then the file in which the returned space resides will be scanned in its entirety so that these supplementary spaces may be located stored in the returned space.

Parameters:

• files (str or sequence) – A string or sequence of strings giving the netCDF file names or OPenDAP URLs from which to read spaces. For files on disk, the file names may contain shell-style wild cards (as understood by the glob module).
• data (bool) – Optional. If True then store the data of each space, including the data of its grid components, as numpy arrays. Otherwise store the data as file pointers. Note that ancillary and transform spaces within a space are always returned with file pointers to their data.
• exact (bool) – Optional. If True then interpret the keywords from **kwargs as exact phenomenon names. Refer to cf.Space.extract() for details.
• index (None or int) – Optional. If None then return all possible spaces from the input files. If a non-negative integer then only return the space with this index in the otherwise full list of spaces. The index position applies to those spaces which have been selected with the **kwargs criteria.
• verbose (bool) – Optional. If True then print information to stdout.
• **kwargs –

  Optional. Other keyword arguments defining space selection based on phenomena criteria. If none are set then all spaces are selected. Keywords and their arguments are set as for cf.Space.extract(). If the data are being read from disk (the data parameter is True), then applying selection criteria as arguments to cf.read(), as opposed to the functionally equivalent method of using the cf.SpaceList.extract() method on the returned list of spaces, may be more memory efficient.

Returns:

A list of spaces (a SpaceList object) or, if and only if the index parameter is set to a non-negative integer, a space (a Space object).

See also

read1()

Examples

>>> s = cf.read('file.nc')
>>> type(s)
<class 'cf.space.SpaceList'>
>>> s
[<CF Space: pmsl(30, 24)>,
 <CF Space: z-squared(17, 30, 24)>,
 <CF Space: temperature(17, 30, 24)>,
 <CF Space: temperature_wind(17, 29, 24)>]

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

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

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

Note

cf.read('file.nc', index=1) returns a list of spaces with one element whilst cf.read('file.nc')[1] returns a space.

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

>>> cf.read('file.nc')[0]
<CF Space: pmsl(30, 24)>

>>> cf.read1('file.nc')
<CF Space: pmsl(30, 24)>

>>> cf.read('file.nc').units
['Pa', 'm2', 'K', 'K']   

See also

cf.Space.extract() for more examples of space selection by phenomena criteria.