CSN Operation Templates

  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
anomaly_of_X   (???)
cos_of_X
limit_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", "0.5_of" and "one_fifth_power_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.