CSN Operation Templates: Difference between revisions
From CSDMS
Line 1: | Line 1: | ||
= '''[[CSDMS_Standard_Names | CSDMS Standard Names]] — Operation Templates''' = | = '''[[CSDMS_Standard_Names | 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. | * 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. <br/> <br/> | ||
* In CF Standard Names, the word "transformation" is used in the same sense as we use "operation". | * Note that applying an operation to a quantity results in a new quantity that frequently has different units that the original quantity. <br/> <br/> | ||
* In CF Standard Names, the word "transformation" is used in the same sense as we use "operation". <br/> <br/> | |||
* These templates attempt to avoid operations that require two standard names, say X and Y, like these from the CF Standard Names: | * These templates attempt to avoid operations that require two standard names, say X and Y, like these from the CF Standard Names: | ||
Line 37: | Line 39: | ||
soil__derivative_wrt_time_of_saturated_hydraulic_conductivity | soil__derivative_wrt_time_of_saturated_hydraulic_conductivity | ||
* This pattern is extended to higher-order derivatives by adding a prefix like "second_", as in: "second_derivative_wrt_time_of_". | * This pattern is extended to higher-order derivatives by adding a prefix like "second_", as in: "second_derivative_wrt_time_of_". <br/> <br/> | ||
* "wrt" = "with respect to" | * "wrt" = "with respect to" <br/> <br/> | ||
* 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 "derivative_wrt_time_of_X" pattern is generally less ambiguous and therefore preferable. | * 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 "derivative_wrt_time_of_X" pattern is generally less ambiguous and therefore preferable. <br/> <br/> | ||
* 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. | * 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. <br/> <br/> | ||
* 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 not standard across the sciences and is not allowed in CSDMS Standard Names. | * 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 not standard across the sciences and is not allowed in CSDMS Standard Names. <br/> <br/> | ||
* In CF Standard Names, there is also the transformation pattern: "derivative_of_X_wrt_Y" and "time" is a CF Standard Name. | * In CF Standard Names, there is also the transformation pattern: "derivative_of_X_wrt_Y" and "time" is a CF Standard Name. <br/> <br/> | ||
* 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 "derivative_wrt_time_of". | * 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 "derivative_wrt_time_of". <br/> <br/> | ||
* CF Standard Names also has the transformation pattern: "change_over_time_in_X", with bounds given in metadata. | * CF Standard Names also has the transformation pattern: "change_over_time_in_X", with bounds given in metadata. | ||
Line 62: | Line 64: | ||
operation = "derivative_wrt_y_of_" <br/> | operation = "derivative_wrt_y_of_" <br/> | ||
* 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 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". <br/> <br/> | ||
* There are 4 CF Standard Names that use the "x_derivative_of_" or "y_derivative_of_" pattern. | * There are 4 CF Standard Names that use the "x_derivative_of_" or "y_derivative_of_" pattern. | ||
Line 72: | Line 74: | ||
operation_pattern = "derivative_wrt_X_of_Y" | operation_pattern = "derivative_wrt_X_of_Y" | ||
* In this case, it may not be possible to express the operation using an "operator prefix". This pattern is permitted in CF Standard Names, where both X and Y can also be standard names. | * In this case, it may not be possible to express the operation using an "operator prefix". This pattern is permitted in CF Standard Names, where both X and Y can also be standard names. <br/> <br/> | ||
* 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. | * 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. <br/> <br/> | ||
<br/> | <br/> | ||
Line 84: | Line 86: | ||
* "wrt" = "with respect to" | * "wrt" = "with respect to" | ||
* In CF Standard Names, there is also the transformation pattern: "integral_of_X_wrt_Y" and "time" is a CF Standard Name. 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". | * In CF Standard Names, there is also the transformation pattern: "integral_of_X_wrt_Y" and "time" is a CF Standard Name. 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". <br/> <br/> | ||
* Perhaps we should allow the time interval to be given in the operation name, at least for intervals like "day" and "year". e.g. | * Perhaps we should allow the time interval to be given in the operation name, at least for intervals like "day" and "year". e.g. | ||
Line 139: | Line 141: | ||
peak_value_of_discharge (or just "peak_of_discharge") | 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. | * 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. <br/> <br/> | ||
* 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. | * 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. |
Revision as of 18:15, 31 August 2012
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.
- Note that applying an operation to a quantity results in a new quantity that frequently has different units that the original quantity.
- In CF Standard Names, the word "transformation" is used in the same sense as we use "operation".
- These templates attempt to avoid operations that require two standard names, say X and Y, like these from the CF Standard Names:
change_in_X_due_to_change_in_Y correlation_of_X_with_Y derivative_of_X_wrt_Y integral_of_X_wrt_Y and instead express operations as a prefix whenever possible.
- Some of the "transformations" in the CF Standard Names are:
change_in_X_due_to_change_in_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)
Time Derivatives
operation = "derivative_wrt_time_of_" (maybe we should allow "d_dt_of" ??)
- Examples
bedrock_surface__derivative_wrt_time_of_elevation sea_water__derivative_wrt_time_of_northward_velocity_component soil__derivative_wrt_time_of_saturated_hydraulic_conductivity
- This pattern is extended to higher-order derivatives by adding a prefix like "second_", as in: "second_derivative_wrt_time_of_".
- "wrt" = "with respect to"
- 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 "derivative_wrt_time_of_X" pattern is generally less ambiguous and therefore preferable.
- 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 not standard across the sciences and 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.
- 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 "derivative_wrt_time_of".
- CF Standard Names also has the transformation pattern: "change_over_time_in_X", with bounds given in metadata.
Spatial Derivatives
operation = "derivative_wrt_east_of_"
operation = "derivative_wrt_x_of_"
operation = "derivative_wrt_north_of_"
operation = "derivative_wrt_y_of_"
- 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 "operator 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.
Time Integrals
operation = "integral_wrt_time_of_"
- "wrt" = "with respect to"
- In CF Standard Names, there is also the transformation pattern: "integral_of_X_wrt_Y" and "time" is a CF Standard Name. 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__integral_over_one_day_of_upward_longwave_radiation_flux OR air__one_day_integral_of_upward_longwave_radiation_flux Note that "air" is used as a synonym for "earth_atmosphere". See the template for Air in the CSDMS Object Templates.
Applied Functions
operation = [ function_name ] + "_of_"
- Examples
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)
Statistical Operators
operation = [ operator_name ] + "_of_"
- Examples
max_of_X mean_of_X min_of_X variance_of_X
- 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:
max_over_space_of max_over_time_of (e.g. for a "peak discharge") min_over_space_of min_over_time_of And perhaps also: max_over_day_of min_over_day_of max_over_period_of min_over_period_of
- 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 an operation like:
time_of_max_over_time_of_discharge OR peak_time_of_discharge and maybe: 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
direction_of_X (X must be a 2D vector field; returns an angle) magnitude_of_X (X must be a vector or tensor)
- In our "Quantity" templates, "magnitude" is a "quantity suffix" and turns a vector or tensor quantity into a scalar quantity. We may want to restrict "mathematical operators" to those that don't return a scalar value and require all "base quantities" to be scalars.
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.