cf.DomainTopology¶
- class cf.DomainTopology(*args, **kwargs)[source]¶
A domain topology construct of the CF data model.
A domain topology construct defines the geospatial topology of cells arranged in two or three dimensions in real space but indexed by a single (discrete) domain axis construct, and at most one domain topology construct may be associated with any such domain axis. The topology describes topological relationships between the cells - spatial relationships which do not depend on the cell locations - and is represented by an undirected graph, i.e. a mesh in which pairs of nodes are connected by links. Each node has a unique arbitrary identity that is independent of its spatial location, and different nodes may be spatially co-located.
The topology may only describe cells that have a common spatial dimensionality, one of:
Point: A point is zero-dimensional and has no boundary vertices.
- Edge: An edge is one-dimensional and corresponds to a line
connecting two boundary vertices.
- Face: A face is two-dimensional and corresponds to a surface
enclosed by a set of edges.
Each type of cell implies a restricted topology for which only some kinds of mesh are allowed. For point cells, every node corresponds to exactly one cell; and two cells have a topological relationship if and only if their nodes are connected by a mesh link. For edge and face cells, every node corresponds to a boundary vertex of a cell; the same node can represent vertices in multiple cells; every link in the mesh connects two cell boundary vertices; and two cells have a topological relationship if and only if they share at least one node.
A domain topology construct contains an array defining the mesh, and properties to describe it. There must be a property indicating the spatial dimensionality of the cells. The array values comprise the node identities, and all array elements that refer to the same node must contain the same value, which must differ from any other value in the array. The array spans the domain axis construct and also has a ragged dimension, whose function depends on the spatial dimensionality of the cells.
For each point cell, the first element along the ragged dimension contains the node identity of the cell, and the following elements contain in arbitrary order the identities of all the cells to which it is connected by a mesh link.
For each edge or face cell, the elements along the ragged dimension contain the node identities of the boundary vertices of the cell, in the same order that the boundary vertices are stored by the auxiliary coordinate constructs. Each boundary vertex except the last is connected by a mesh link to the next vertex along the ragged dimension, and the last vertex is connected to the first.
When a domain topology construct is present it is considered to be definitive and must be used in preference to the topology implied by inspection of any other constructs, which is not guaranteed to be the same.
In CF-netCDF a domain topology construct can only be provided for a UGRID mesh topology variable. The information in the construct array is supplied by the UGRID “edge_nodes_connectivity” variable (for edge cells) or “face_nodes_connectivity” variable (for face cells). The topology for node cells may be provided by any of these three UGRID variables. The integer indices contained in the UGRID variable may be used as the mesh node identities, although the CF data model attaches no significance to the values other than the fact that some values are the same as others. The spatial dimensionality property is provided by the “location” attribute of a variable that references the UGRID mesh topology variable, i.e. a data variable or a UGRID location index set variable.
A single UGRID mesh topology defines multiple domain constructs and defines how they relate to each other. For instance, when “face_node_connectivity” and “edge_node_connectivity” variables are both present there are three implied domain constructs - one each for face, edge and point cells - all of which have the same mesh and so are explicitly linked (e.g. it is known which edge cells define each face cell). The CF data model has no mechanism for explicitly recording such relationships between multiple domain constructs, however whether or not two domains have the same mesh may be reliably determined by inspection, thereby allowing the creation of netCDF datasets containing UGRID mesh topology variables.
The restrictions on the type of mesh that may be used with a given cell spatial dimensionality excludes some meshes which can be described by an undirected graph, but is consistent with UGRID encoding within CF-netCDF. UGRID also describes meshes for three-dimensional volume cells that correspond to a volume enclosed by a set of faces, but how the nodes relate to volume boundary vertices is undefined and so volume cells are currently omitted from the CF data model.
See CF Appendix I “The CF Data Model”.
NetCDF interface
The netCDF variable name of the UGRID mesh topology variable may be accessed with the
nc_set_variable
,nc_get_variable
,nc_del_variable
, andnc_has_variable
methods.Added in version 3.16.0.
Initialisation
- Parameters:
- cell:
str
, optional The cell type that indicates the spatial dimensionality of the cells, one of
'point'
(a 0-d point with no boundary vertices),'edge'
(a 1-d line connecting two boundary vertices), or'face'
(a 2-d surface enclosed by a set of edges).- properties:
dict
, optional Set descriptive properties. The dictionary keys are property names, with corresponding values.
Properties may also be set after initialisation with the
set_properties
andset_property
methods.- Parameter example:
properties={'long_name': 'face to node mapping'}
- data: data_like, optional
Set the data.
A data_like object is any object that can be converted to a
Data
object, i.e.numpy
array_like objects,Data
objects, and cf instances that containData
objects.The data also may be set after initialisation with the
set_data
method.- source: optional
Convert source, which can be any type of object, to a
DomainTopology
instance.All other parameters, apart from copy, are ignored and their values are instead inferred from source by assuming that it has the
DomainTopology
API. Any parameters that can not be retrieved from source in this way are assumed to have their default value.Note that if
x
is also aDomainTopology
instance thencf.DomainTopology(source=x)
is equivalent tox.copy()
.- copy:
bool
, optional If True (the default) then deep copy the input parameters prior to initialisation. By default the parameters are not deep copied.
- cell:
Inspection¶
Methods
A full description of the domain topology construct. |
|
Return the canonical identity. |
|
Return all possible identities. |
|
Inspect the object for debugging. |
Attributes
Return a description of the construct type. |
|
An identity for the DomainTopology object. |
Topology¶
Methods
Remove the cell type. |
|
Return the cell type. |
|
Whether the cell type has been set. |
|
Set the cell type. |
|
Normalise the data values. |
Attributes
The cell type. |
Selection¶
Methods
Whether or not the construct identity satisfies conditions. |
|
Whether or not the data has a given dimensionality. |
|
Whether or not the netCDF variable name satisfies conditions. |
|
Whether or not properties satisfy conditions. |
|
Whether or not the construct has given units. |
Properties¶
Methods
Remove a property. |
|
Get a CF property. |
|
Whether a property has been set. |
|
Set a property. |
|
Return all properties. |
|
Remove all properties. |
|
Remove properties. |
|
Set properties. |
Attributes
The add_offset CF property. |
|
The calendar CF property. |
|
The comment CF property. |
|
The _FillValue CF property. |
|
The history CF property. |
|
The leap_month CF property. |
|
The leap_year CF property. |
|
The long_name CF property. |
|
The missing_value CF property. |
|
The month_lengths CF property. |
|
The scale_factor CF property. |
|
The standard_name CF property. |
|
The units CF property. |
|
The valid_max CF property. |
|
The valid_min CF property. |
|
The valid_range CF property. |
Units¶
Methods
|
Change the data array units. |
Override the units. |
|
Override the calendar of date-time units. |
Attributes
The |
Data¶
Attributes
A numpy array deep copy of the data. |
|
Deprecated at version 3.0.0, use |
|
The |
|
An independent numpy array of date-time objects. |
|
Return an element of the data array as a standard Python scalar. |
|
The |
|
True if the data array is scalar. |
|
The number of data dimensions. |
|
A tuple of the data array's dimension sizes. |
|
The number elements in the data. |
|
A numpy array view of the data. |
Methods
Convert the data to a |
|
Return a subspace defined by indices. |
|
Remove the data. |
|
Return the data. |
|
Whether or not the construct has data. |
|
Set the data. |
Rearranging elements
Flatten axes of the data. |
|
Flip (reverse the direction of) data dimensions. |
|
Expand the shape of the data array. |
|
Roll the data along one or more axes. |
|
Remove size one axes from the data array. |
|
Interchange two axes of an array. |
|
Permute the axes of the data array. |
Expanding the data
Expand the data by adding a halo. |
|
Pad an axis with missing data. |
Data array mask
Apply masking as defined by the CF conventions. |
|
Count the non-masked elements of the data. |
|
Count the masked elements of the data. |
|
Return the data array missing data value. |
|
Replace masked elements with a fill value. |
|
Mask the array where invalid values occur (NaN or inf). |
A binary (0 and 1) missing data mask of the data array. |
|
Whether the mask is hard (True) or soft (False). |
|
The mask of the data array. |
Changing data values
Called to implement assignment to x[indices] |
|
Mask the array where invalid values occur (NaN or inf). |
|
Return a new variable whose data is subspaced. |
|
Set data array elements depending on a condition. |
Miscellaneous
Change the chunk structure of the data. |
|
Close all files referenced by the construct. |
|
Convert reference time data values to have new units. |
|
Get or set the cyclicity of an axis. |
|
Return or set the period of the data. |
|
Whether or not a given axis is cyclic. |
|
True if a given axis is periodic. |
|
The names of files containing the original data and metadata. |
|
Whether or not there are cell bounds. |
|
Persist data into memory. |
Quantization¶
Methods
Get quantization metadata. |
|
Get a quantize-on-write instruction. |
Miscellaneous¶
Methods
Join a together sequence of |
|
Return a deep copy. |
|
Returns the commands to create the domain topology construct. |
|
Whether two instances are the same. |
|
Bring data on disk into memory. |
|
Uncompress the construct. |
Attributes
|
|
Always False. |
|
Always False. |
|
Always False. |
|
An identity for the DomainTopology object. |
Mathematical operations¶
Methods
Trigonometrical and hyperbolic functions
Take the trigonometric inverse cosine of the data element- wise. |
|
Take the inverse hyperbolic cosine of the data element-wise. |
|
Take the trigonometric inverse sine of the data element-wise. |
|
Take the inverse hyperbolic sine of the data element-wise. |
|
Take the trigonometric inverse tangent of the data element- wise. |
|
Take the inverse hyperbolic tangent of the data element-wise. |
|
Take the trigonometric cosine of the data element-wise. |
|
Take the hyperbolic cosine of the data element-wise. |
|
Take the trigonometric sine of the data element-wise. |
|
Take the hyperbolic sine of the data element-wise. |
|
Take the trigonometric tangent of the data element-wise. |
|
Take the hyperbolic tangent of the data array. |
Rounding and truncation
The ceiling of the data, element-wise. |
|
Limit the values in the data. |
|
Floor the data array, element-wise. |
|
Round the data to the nearest integer, element-wise. |
|
Round the data to the given number of decimals. |
|
Truncate the data, element-wise. |
Statistical collapses
Alias for |
|
The unweighted mean the data array. |
|
The unweighted average of the maximum and minimum of the data array. |
|
Alias for |
|
The absolute difference between the maximum and minimum of the data array. |
|
The number of non-missing data elements in the data array. |
|
The sum of the data array. |
|
Alias for |
|
Alias for |
|
The unweighted sample standard deviation of the data array. |
|
The unweighted sample variance of the data array. |
|
The maximum of the data array. |
|
The minimum of the data array. |
Exponential and logarithmic functions
The exponential of the data, element-wise. |
|
The logarithm of the data array. |
Date-time operations¶
Attributes
The day of each date-time data array element. |
|
An independent numpy array of date-time objects. |
|
The hour of each date-time data array element. |
|
The minute of each date-time data array element. |
|
The month of each date-time data array element. |
|
The reference date-time of units of elapsed time. |
|
The second of each date-time data array element. |
|
The year of each date-time data array element. |
Logic functions¶
Truth value testing
Test whether all data elements evaluate to True. |
|
Test whether any data elements evaluate to True. |
Comparison
Test whether all data are element-wise equal to other, broadcastable data. |
|
Whether two instances are the same. |
|
True if two constructs are equal, False otherwise. |
Set operations
The unique elements of the data. |
NetCDF¶
Methods
Remove the netCDF variable name. |
|
Return the netCDF variable name. |
|
Whether the netCDF variable name has been set. |
|
Set the netCDF variable name. |
|
Clear the dataset chunking strategy for the data. |
|
Get the dataset chunking strategy for the data. |
|
Set the dataset chunking strategy. |
Aggregation¶
Methods
The directories of files containing parts of the data. |
|
Replace a file directory in-place. |
NetCDF¶
Methods
Remove the netCDF variable name. |
|
Return the netCDF variable name. |
|
Whether the netCDF variable name has been set. |
|
Set the netCDF variable name. |
Groups¶
Methods
Return the netCDF variable group hierarchy. |
|
Remove the netCDF variable group hierarchy. |
|
Set the netCDF variable group hierarchy. |
Dataset chunks¶
Methods
Get the dataset chunking strategy for the data. |
|
Set the dataset chunking strategy. |
|
Clear the dataset chunking strategy for the data. |
Aliases¶
Methods
Alias for |
Attributes
Alias for |
Special¶
Methods
Called by the |
|
Return a subspace defined by indices. |
|
Called by the |
|
Called by the |
Docstring substitutions¶
Methods
Return the special docstring substitutions. |
|
Returns the substitutions that apply to methods of the class. |
|
Returns the class {{package}} substitutions package depth. |
|
Returns method names excluded in the class substitutions. |
Deprecated¶
Methods
Deprecated at version 3.0.0. |
|
Deprecated at version 3.0.0. |
|
Deprecated at version 3.0.0. |
|
Partition the data array. |
|
Deprecated at version 3.0.0, use method |
|
Deprecated at version 3.0.0. |
|
Deprecated at version 3.0.0, use |
|
Return the name of the file or files containing the data. |
|
Deprecated at version 3.0.0, use method |
|
Deprecated at version 3.0.0, use |
|
Deprecated at version 3.0.0, use |
|
Deprecated at version 3.0.0, use method |
|
Deprecated at version 3.0.0, use |
|
Deprecated at version 3.7.0, use |
|
Deprecated at version 3.7.0, use |
|
Deprecated at version 3.7.0, use |
|
Deprecated at version 3.7.0, use |
|
Deprecated at version 3.7.0, use |
|
Mask the array where invalid values occur. |
|
Deprecated at version 3.0.0, use method 'identity' instead. |
|
Deprecated at version 3.0.0, use method |
|
Deprecated at version 3.0.0. |
|
Deprecated at version 3.0.0, use method |
|
Deprecated at version 3.0.0, use |
|
Clear the HDF5 chunking strategy for the data. |
|
Get the HDF5 chunking strategy for the data. |
|
Set the HDF5 chunking strategy. |