| 19 | |
| 20 | |
| 21 | |
| 22 | = Constructs, Types = |
| 23 | |
| 24 | ==== markup notes ==== |
| 25 | |
| 26 | * An editor may add text: but this must be in ''italics''. |
| 27 | * An editor may raise a question about text section, this must be marked up as '''''bold italics''''' |
| 28 | * A suggested textual replacement may be indicated by ''('' current text | ''replacement text)'' |
| 29 | |
| 30 | This facilitates communication on the [https://cf-pcmdi.llnl.gov/trac/ticket/95 trac ticket] |
| 31 | |
| 32 | == Field construct == |
| 33 | |
| 34 | The central concept of the data model is a field construct. A field construct corresponds to exactly one data array together with associated information about the domain in which the data resides (defined by spatio-temporal and other coordinates) and other metadata. This data model makes a central assumption that each field construct is independent. |
| 35 | |
| 36 | ''A Field defines a single phenomenon, using a standard_name, long_name, units and other attributes, all of which are optional. Each element of the data array is a measure of this phenomenon within the sampling domain.'' |
| 37 | |
| 38 | Each field construct must contain: |
| 39 | |
| 40 | * ''domain_axes:'' An '''''unordered''''' list of zero or more domain axis constructs. Each domain axis construct declares a dimension of the field. |
| 41 | * A data array, which contains the data of the field. '''''The shape of the data array is determined by an ordered subset of the domain axes. All domain axes of size greater than one must be included in the subset, but domain axes of size one may optionally be omitted, because their position in the order of domain axes makes no difference to the order of data elements in the array. If there are no domain axes of greater size than one, the single datum may be a scalar instead of an array. If the data array has more than one element, they must all be of the same data type, which may be numeric, character or string.''''' |
| 42 | |
| 43 | Each Field Construct may optionally contain: |
| 44 | |
| 45 | * ''dimension_coords:'' '''''An unordered''''' collection of ''('' dimension coordinate constructs | ''!DimCoord instances)''. |
| 46 | * Each ''('' dimension coordinate construct | ''!DimCoord instance)'' provides physical coordinates to locate the cells at unique positions along a single domain axis. |
| 47 | * ''auxiliary_coords:'' '''''An unordered''''' collection of ''(''auxiliary coordinate constructs | ''!AuxCoord instances)''. Each ''(''auxiliary coordinate construct | ''!AuxCoord instance)'' provides physical coordinates to locate the cells along one or more domain axes. |
| 48 | * Yet to be worked upon: An unordered collection of cell measure constructs. |
| 49 | * Yet to be worked upon: A cell methods construct, which refers to the domain axes (but not their sizes). |
| 50 | * Yet to be worked upon: An optional unordered collection of ''(''transform constructs | ''Transforms)'' '''''(corresponding to CF-netCDF formula_terms and grid_mapping)'''''. |
| 51 | * '''''Other properties, which are metadata that do not refer to the domain axes, and serve to describe the data the field contains. Properties may be of any data type (numeric, character or string) and can be scalars or arrays. These properties correspond to attributes in the netCDF file, but we use the term "property" instead because not all CF-netCDF attributes are properties in this sense.''''' |
| 52 | * ''Attributes which define the phenomenon of the Field, using the controlled names: standard_name, long_name, units'' |
| 53 | * ''further attributes which use a name not controlled by the CF semantics.'' |
| 54 | * ''Yet to be worked upon:'' A list of ancillary fields, which contain metadata about the elements of the field's data array. |
| 55 | |
| 56 | Collectively, the ''(''domain axis, dimension coordinate, auxiliary coordinate, cell measure and cell method constructs | ''domain_axes, dimension_coords, auxiliary_coords and cell_measures)'' describe the domain in which the data resides ''and the sampling regime from that domain''. Thus a field construct can be regarded as a domain with data ''(''in that domain | ''sampled from that domain)''. |
| 57 | |
| 58 | ==== The Field in a NetCDF file ==== |
| 59 | |
| 60 | The CF-netCDF formula_terms (see also Transform constructs) and ancillary_variables attributes make links between field constructs. These links are fragile and it might not always be possible for data processing software to maintain a consistent set of such links when writing fields to files or manipulating them in memory. |
| 61 | |
| 62 | CF-netCDF considers fields which are contained in single netCDF files. In a dataset contained in a single netCDF file, each data variable corresponds to one field construct. This data model has a broader scope. It applies also to data contained in memory and to datasets comprising several netCDF files. A field construct may span data variables in more than one file, for instance from different ranges of a time coordinate. Rules for aggregating data variables from several files into a single field construct are needed but are not defined by CF version 1.5; such rules are regarded as the concern of data processing software. Technically, data variables stored in CF-netCDF files are often not independent, because they share coordinate variables. However, we view this solely as a means of saving disk space, and we assume that software will be able to alter any field construct in memory without affecting other field constructs. For instance, if the coordinates of one field construct are modified by averaging the field values over one dimension, it will not affect any other field construct. |
| 63 | |
| 64 | Explicit tests of domain consistency will be required to establish whether two data variables have the same coordinates or share a subset of these coordinates. Such tests are necessary in general if CF is applied to a dataset comprising more than one file, because different variables may then reside in different files, with their own coordinate variables ''(^this text may be better in the previous section^)''. Within a netCDF file, tests for the equality of coordinates between different data variables may be simplified if the data variables refer to the same coordinate variable. |
| 65 | |
| 66 | == Domain axis construct == |
| 67 | |
| 68 | A ''(''domain axis construct | ''!DomainAxis)'' must contain: |
| 69 | |
| 70 | * A size, which is an integer that must be greater than zero, but could be equal to one. |
| 71 | |
| 72 | == Dimension coordinate construct == |
| 73 | |
| 74 | A ''(''dimension coordinate construct | ''!DimCoord)'' ''(''may | ''must)'' contain: |
| 75 | |
| 76 | * A one-dimensional numerical coordinate array of the size specified ''(''for the domain axis | ''by the referencing !DomainAxis)''. |
| 77 | * '''''If the size is one, the single coordinate value may be a scalar instead of an array.''''' |
| 78 | * '''''If the size is greater than one,''''' the elements of the coordinate array must: |
| 79 | * all be of the same numeric data type, |
| 80 | * '''''they must''''' all have different non-missing values, |
| 81 | * '''''and they must''''' be monotonically increasing or decreasing. |
| 82 | * ''(''Dimension coordinate constructs | ''!DimCoord instances)'' cannot have string-valued ''(''coordinates | ''coordinate arrays)''. |
| 83 | |
| 84 | ''A (dimension coordinate construct | !DimCoord) may contain'': |
| 85 | |
| 86 | * A two-dimensional numerical boundary array, whose slow-varying dimension (first in CDL, second in Fortran) equals the size specified by the domain axis construct, and whose fast-varying dimension is two, indicating the extent of the cell. |
| 87 | * For climatological time dimensions, the bounds are interpreted in a special way indicated by the cell methods. |
| 88 | * Sometimes the bounds are the important information for locating the cell, and the coordinates are notional, especially for extensive quantities. |
| 89 | * ''(''Properties | ''Attributes)'' (in the same sense as for the ''(''field construct| Field)'') serving to ''(''describe the coordinates | ''define the coordinate's phenomenon''. |
| 90 | |
| 91 | ==== The Dimension Coordinate in a NetCDF file ==== |
| 92 | |
| 93 | A dimension coordinate construct corresponds to a netCDF coordinate variable, whose name is the same as the name of its single dimension, or a CF-netCDF numeric scalar coordinate variable. A CF-netCDF string-valued coordinate variable or string-valued scalar coordinate variable corresponds to an auxiliary coordinate construct (not a dimension coordinate construct), with a domain axis that is not associated with any dimension coordinate construct. |
| 94 | |
| 95 | In this data model we permit a domain axis construct not to have a dimension coordinate construct '''''if there is no appropriate numeric monotonic coordinate'''''. That is the case for a dimension that runs over ocean basins or area types, for example, or for a domain axis that indexes timeseries at scattered points. Such domain axes do not correspond to a continuous physical quantity. '''''(They will be called index dimensions in CF version 1.6.)''''' |
| 96 | |
| 97 | == Auxiliary coordinate construct == |
| 98 | |
| 99 | An auxiliary coordinate construct must contain: |
| 100 | |
| 101 | * A coordinate array whose shape is determined by the ''(''domain axes | ''!DomainAxis instances)'' in the order listed, '''''optionally omitting any domain axes of size one'''''. |
| 102 | * '''''If all domain axes are of size one, the single coordinate value may be a scalar instead of an array.''''' |
| 103 | * ''(''If the array has more than one element, they | ''elements)'' must all be of the same data type (numeric, character or string), but they do not have to be distinct or monotonic. |
| 104 | * '''''Missing values are not allowed (in CF version 1.5).''''' |
| 105 | |
| 106 | An auxiliary coordinate construct may contain: |
| 107 | |
| 108 | * A boundary array with all the dimensions, in the same order, as the coordinate array, and an additional dimension (following the coordinate array dimensions in CDL, preceding them in Fortran) equal to the number of vertices of each cell. |
| 109 | * ''(''Properties | ''Attributes)'' (in the same sense as for the field construct) serving to describe the coordinates. |
| 110 | |
| 111 | ==== Auxiliary Coordinates in Cf NetCDF ==== |
| 112 | |
| 113 | Auxiliary coordinate constructs correspond to auxiliary coordinate variables named by the coordinates attribute of a data variable in a CF-netCDF file. CF requires there to be auxiliary coordinate constructs of latitude and longitude if there is two-dimensional horizontal variation but the horizontal coordinates are not latitude and longitude. |
| 114 | |
| 115 | In CF-netCDF, a string-valued auxiliary coordinate construct can be stored either as a character array with an additional dimension (last dimension in CDL) for maximum string length, or represented by a numerical auxiliary coordinate variable with a flag_meanings attribute to supply the translation to strings. |
| 116 | |
| 117 | |
| 118 | |
| 119 | |
| 120 | |
| 121 | |
| 122 | = Legacy text For reference only = |