CSN Operation Templates: Difference between revisions
From CSDMS
Line 30: | Line 30: | ||
:''Examples'' | :''Examples'' | ||
bedrock_surface__time_derivative_of_elevation | bedrock_surface__time_derivative_of_elevation | ||
sea_water__time_derivative_of_northward_component_of_velocity | |||
soil__time_derivative_of_hydraulic_conductivity | soil__time_derivative_of_hydraulic_conductivity | ||
Revision as of 21:52, 5 March 2013
CSDMS Standard Names — Operation Templates
- Operations can optionally be given as a prefix to the quantity part of an existing standard name. The prefix always ends in the word "_of", which is a reserved word. It can therefore be used as a delimiter to separate the operation from the quantity name it acts on.
- Applying an operation to a quantity results in a new quantity that frequently has different units than the original quantity.
- We apply the operation to the quantity part of the name instead of to the entire name (object + quantity) so that all standard names associated with a given object will group together alphabetically.
- In CF Standard Names, the word "transformation" is used in the same sense as "operation" is used in the CSDMS Standard Names. Some of the "transformations" in the CF Standard Names are:
change_in_X_due_to_change_in_Y correlation_of_X_with_Y curl_of_X derivative_of_X_wrt_Y direction_of_X divergence_of_X gradient_of_X integral_of_X_wrt_Y magnitude_of_X tendency_of_X (time_derivative)
- Note that many of the CF transformations require two standard names (X and Y). The CSDMS operation templates below attempt to avoid operations that require two standard names. Whenever possible, each operation is expressed as a prefix to a quantity name. For example, "time_derivative_of_X" is used instead of "derivative_of_X_wrt_time". This allows operations to be chained together (e.g. a time derivative and a space derivative).
Time Derivatives
operation = "time_derivative_of_" (maybe we should allow "d_dt_of" ??)
- Examples
bedrock_surface__time_derivative_of_elevation sea_water__time_derivative_of_northward_component_of_velocity soil__time_derivative_of_hydraulic_conductivity
- This pattern was modified on Nov. 19, 2012; "derivative_wrt_time_of" was replaced by "time_derivative_of".
- This pattern adds units of time to the quantity it acts on.
- This pattern is extended to higher-order derivatives by adding a prefix like "second_", as in: "second_time_derivative_of_".
- Many quantity names built from process names have a sign connotation, such as "erosion_rate", "deposition_rate" and "accumulation_rate". If either sign is possible, the "time_derivative_of_X" pattern is generally less ambiguous and therefore preferable (e.g. time_derivative_of_elevation vs. erosion_rate).
- We could possibly use a base quantity like "_change_rate" for time derivatives, but this seems limited and ambiguous and it isn't used much in practice.
- In CF Standard Names, a "transformation" called "tendency_of" is used to indicate a time derivative. There are 435 names that use this pattern. But it is a domain-specific term (i.e. not standard across the sciences) and therefore is not allowed in CSDMS Standard Names.
- In CF Standard Names, there is also the transformation pattern: "derivative_of_X_wrt_Y" and "time" is a CF Standard Name. ("wrt" = "with respect to" )
- In CF Standard Names, the transformation pattern for the derivative of a vector component is: "[component]_derivative_of_X". In the CSDMS Standard Names, "_component" is used as a "quantity suffix" (like "increment") and the name would start with an operation prefix like "time_derivative_of".
- CF Standard Names also has the transformation pattern: "change_over_time_in_X", with bounds given in metadata.
Spatial Derivatives
operation = "eastward_derivative_of_"
operation = "x_derivative_of_"
operation = "northward_derivative_of_"
operation = "y_derivative_of_"
- This pattern was changed to: "eastward_derivative_of", "x_derivative_of", etc. (Feb 5, 2013).
- There are only 10 CF Standard Names that contain "derivative" and they do not follow a consistent pattern. Note, however, that in CF Standard Names, time derivatives start with "tendency_of" and don't contain the word "derivative".
- There are 4 CF Standard Names that use the "x_derivative_of_" or "y_derivative_of_" pattern.
General Derivatives
operation_pattern = "derivative_wrt_X_of_Y"
- In this case, it may not be possible to express the operation using an "operation prefix". This pattern is permitted in CF Standard Names, where both X and Y can also be standard names.
- In most cases, it appears that we can accommodate this pattern by replacing X by a single-word, base quantity name like "temperature" and replacing Y by a fully-qualified standard name.
Space and Time Integrals
operation = "time_integral_of_"
operation = "area_integral_of_"
operation = "area_time_integral_of_"
operation = "volume_integral_of_"
operation = "line_integral_of_"
- The naming rules for integrals were modified on Nov. 19, 2012. This new pattern (shown above) is more flexible and results in shorter operation names. Single words such as "area", "time", "volume" and "line" are inserted (possibly in combination) as descriptors in front of the word "integral".
- Notice that an integral over both space (e.g. area) and time is expressed compactly as "area_time_integral_of", instead of a long chain like: "area_integral_of_time_integral_of".
- It is sometimes necessary to indicate that a spatial integral is over a particular domain, such as a model domain or a watershed. It seems that this should be indicated by using "watershed" or "model" as the first word in the object name part and then the operation "area_integral_of" applied to a quantity.
- In CF Standard Names, there is also the transformation pattern: "integral_of_X_wrt_Y" and "time" is a CF Standard Name. ("wrt" = "with respect to"). Bounds for the integral are given in metadata. There are currently 18 CF Standard Names that contain "integral" and 12 of these end with "_wrt_time".
- Perhaps we should allow the time interval to be given in the operation name, at least for intervals like "day" and "year". e.g.
air__one_day_time_integral_of_upward_longwave_radiation_flux Note that "air" is sometimes used as a synonym for "earth_atmosphere". See the template for Air in the CSDMS Object Templates.
Applied Functions
operation = [ function_name ] + "_of_"
- Examples
abs_of_X cos_of_X log_of_X (instead of "ln_X" in CF) log10_of_X (instead of "log10_X" in CF) sin_of_X (not in CF) sqrt_of_X (not in CF) square_of_X (also a CF Standard Names transformation) tan_of_X tanh_of_X 0.2_power_of_X (???)
- Multiplication by a floating-point number could be supported by allowing operation names like "2_of" and "0.5_of".
Statistical Operators
operation = [ operator_name ] + "_of_"
- Examples
max_of_X mean_of_X median_of_X min_of_X mode_of_X standard_deviation_of_X variance_of_X
- However, many quantities vary in both space and time, so an operation like "max_of" could be ambiguous. In order to address such cases, the following operation names can be used:
domain_max_of_X domain_min_of_X time_max_of_X (e.g. for a "peak discharge") time_min_of_X And perhaps also: one_day_time_max_of_X one_day_time_min_of_X OR max_over_day_of_X min_over_day_of_X max_over_period_of_X min_over_period_of_X
- When there is interest in a "peak" value (i.e. a maximum with respect to time), there is generally also interest in the time at which that peak value occurs. We could use "time" as a quantity suffix in such cases, but it might be better to introduce a "time_of" operation like:
time_of_max_over_time_of_discharge OR time_of_max_of_discharge (since "max_over_time" is implied by "time_of") or maybe: peak_time_of_discharge and peak_value_of_discharge (or just "peak_of_discharge")
- Similarly, it may not always be clear how "mean_of_" should be interpreted unless extra adjectives/modifiers are used. For example, does "mean_of_channel_water_depth" mean the mean over a cross section or over an entire channel reach or over a grid of such values? This case also needs a more prescriptive rule and/or the details of the operation could be provided in metadata along with units, etc.
- Note that min, max or "peak" could also be used as adjectives/modifiers in the construction of a full quantity name if the meaning is clear.
Mathematical Operators that Return Scalars
operation = [ operator_name ] + "_of_"
- Examples
downward_component_of_X eastward_component_of_X local_azimuthal_angle_of_X (X must be a 2D or 3D vector field; returns an angle) local_zenith_angle_of_X (X must be a 3D vector field; returns an angle) magnitude_of_X (X must be a vector or tensor) northward_component_of_X x_component_of_X y_component_of_X
- In our "Quantity" templates, "magnitude" is a "quantity suffix" and turns a vector or tensor quantity into a scalar quantity.
- For a 2D vector field, the azimuthal angle is just the angle used in polar coordinates. For a 3D vector field, it is the polar coordinates angle of the projection of the vector onto the xy plane.
- For a 3D vector field, the zenith angle (sometimes called the "polar angle") is the angle between the z-axis (zenith) and the vector at a given spatial location. (It can be computed using the dot product formula.)
- The adjective "local" can be used for vector fields to emphasize that the angle or magnitude varies over the spatial domain.
- Some of these can be combined, as in "x_component_of_gradient_of_elevation" or "local_azimuth_angle_of_gradient_of_elevation". Is the latter the same as "aspect_angle" and if so, should we have both?
Mathematical Operators that Return Vectors
operation = [ operator_name ] + "_of_"
- Examples
curl_of_X (X must be a vector field; returns a vector.) divergence_of_X (X must be a vector field; returns a vector.) gradient_of_X (X must be a scalar field; returns a vector.) air__divergence_of_pressure_gradient air__divergence_of_temperature_gradient bedrock_surface__divergence_of_elevation_gradient
- These all return vectors, so if we require base quantities to be scalars they would not qualify unless combined with a scalar-producing operator like "magnitude_of_". So we could have derived quantities like: "magnitude_of_gradient_of_X".
Change Increments
- Instead of a "change_in_X" operator (as in CF), the CSDMS Standard Names have a "quantity suffix" called "increment" that can be applied to any base quantity to create a new base quantity. See the discussion at the top of CSDMS Quantity Templates.