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.
:
* Operations are applied 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.
:
* The CSDMS Standard Names currently (Feb. 5, 2013) support the concept of a quantity suffix that can be applied to a base quantity to create a new quantity that usually has the same units, as in "time_step", "elevation_increment", "mass_limit", "pressure_anomaly" and "temperature_correction". However, it appears that every quantity suffix can also be expressed as an operation, so the quantity suffix concept may be discontinued.
:
* The CSDMS operation templates attempt to express each operation 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_derivative_of_" (maybe we should allow "d_dt_of" ??)
:Examples
 bedrock_surface__time_derivative_of_elevation
 sea_water__time_derivative_of_north_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 inverse time to the units of the quantity it acts on.
:
* This pattern is extended to higher-order derivatives by adding a prefix like "2nd_", as in: "2nd_time_derivative_of_".
:
* Should we add "material_derivative_of" as another operation? See: Material derivative.
:
* 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).
== ==
  [ operator_name ] + "_of_"
:Examples
 alongshore_derivative_of_X
 cross-shore_derivative_of_X (or just "offshore" ??)
 cross-stream_derivative_of_X
 east_derivative_of_X
 normal_derivative_of_X
 north_derivative_of_X
 offshore_derivative_of_X
 streamwise_derivative_of_X
 tangential_derivative_of_X
 u_derivative_of_X # (for orthogonal curvilinear coordinates u and v)
 v_derivative_of_X # (for orthogonal curvilinear coordinates u and v)
 x_derivative_of_X
 x_x_derivative_of_X ### (or "second_x_derivative_of_" ??)
 x_y_derivative_of_X
 y_derivative_of_X
 y_y_derivative_of_X ### (or "second_y_derivative_of_" ??)
 z_derivative_of_X
* This pattern was changed on Feb 5, 2013.
:
* Multiple derivatives can be specified as shown above, as in "x_x_derivative" vs. "x_derivative_of_x_derivative_of".
:
* Perhaps we should allow a shorthand, such as "d_dx_of_" and "d2_dx_dy_of_".
:
* The adjectives "eastward" and "northward" have been shortened to "east" and "north". (8/6/14)
:
* Although both "alongshore" and "longshore" are used as synonyms, "alongshore" is used in the CSDMS Standard Names because it is less ambiguous.
== ==
  [ operator_name ] + "_of_"
:Examples
 advective_derivative_of_X
 material_derivative_of_X
 directional_derivative_of_X
* In fluid mechanics (Eulerian description), the advective derivative of a scalar fluid property, F, is defined as the dot product of grad(F) and the flow velocity, v. This is sometimes called the "convective derivative", but most textbook authors prefer "advective" vs. "convective" to avoid confusion.
:
* The advective derivative of a flow vector component (u, v or w) is called the "advective acceleration" (or alternately, the "convective acceleration"). The time derivative of a flow vector component is called the "local acceleration".
:
* In fluid mechanics (Eulerian description), the material derivative of F, usually denoted as "DF/Dt", is the sum of the (partial) time derivative of F and the advective derivative of F.
:
* A directional derivative of a scalar field, F, quantifies how much F changes as we move in a direction given by some unit vector field, u. It is computed as the dot product of grad(F) and u.
== ==
  operation_pattern = "Y_derivative_of"
* This is an extension of the pattern used for time and spatial derivatives, where Y can be a one-word base quantity name like "temperature" or "pressure", or can use multiple words to avoid ambiguity, when necessary.
== ==
  [ operator_name ] + "_of_"
:Examples
 time_integral_of_X
 time_integral_from_start_of_X
 area_integral_of_X
 basin_integral_of_X
 domain_integral_of_X
 domain_time_integral_of_X
 globe_integral_of_X
 line_integral_of_X
 volume_integral_of_X
 z_integral_of_X (for vertically-integrated quantities) 
* 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", "domain", "line", "time" and "volume" are inserted (possibly in combination) as descriptors in front of the word "integral".
:
* A "domain_integral" is an integral over the entire model domain. It is usually an area integral and the integration is usually over the model grid cells.
:
* A "basin_integral" is an integral over an entire drainage basin. It is therefore an area integral.
:
* A "globe_integral" is an integral over an entire planetary surface. It is therefore an area integral.
:
* Notice that an integral over both space (e.g. area) and time is expressed compactly as "domain_time_integral_of", instead of a long chain like: "domain_integral_of_time_integral_of".
:
* The pattern for time integrals can include some standard limits of integration, as reserved words, such as "from_start" and "to_finish". (8/6/14) If limits of integration are not specified, time integrals are taken from the start time of a model run to the current time (when the variable is accessed).
:
* The pattern for vertical or "z" integrals can include some standard limits of integration, as reserved words, such as "from_bottom" and "to_top". (8/7/14) Bottom and top are used throughout the CSDMS Standard Names to refer to the bottom and top of a layer (e.g. snow, channel water, sea water, atmosphere). This pattern can also include the prefix partial to indicate a "partial sum", as in "partial_z_integral_of". (8/6/14)
:
* Perhaps we should allow the time interval to be given in the operation name, at least for intervals like "hour", "day" and "year". e.g.
 
 land_surface_radiation~incoming~shortwave__one-hour_time_integral_of_energy_flux
== ==
  [ function_name ] + "_of_"
:Examples
 abs_of_X
 cos_of_X
 exp_of_X
 half_of_X
 inverse_of_X (used to specify the inverse of a function, when needed)
 log_of_X (instead of "ln_X" in CF)
 log10_of_X (instead of "log10_X" in CF)
 minus_of_X
 fourth_of_X
 sin_of_X (not in CF)
 sgn_of_X
 sqrt_of_X (not in CF)
 square_of_X (also a CF Standard Names transformation)
 tan_of_X
 tanh_of_X
 third_of_X
 0.2_power_of_X (???, or one_fifth_power_of ??)
:
* Multiplication by a floating-point number could be supported by allowing operation names like "2_of", "0.5_of" and "2_times_of".
:
* Addition and subtraction could be supported with function names like: 2_more_of and 2_less_of.
:
* The ones listed above are just examples; any function name used in mathematics would be used in the same way.
== ==
  [ function_name ] + "_of_X_and_Y"
:Examples
 difference_of_X_and_Y
 product_of_X_and_Y
 quotient_of_X_and_Y
 sum_of_X_and_Y
* A general power would instead be expressed with the pattern "Y_power_of_X", similar to a general derivative.
:
* The word "and" is a reserved word that acts as a delimiter between X and Y.
:
* It may be better to allow "times", "over", "minus" and "plus" to be used between X and Y, e.g. X_plus_Y.
== ==
  [ operator_name ] + "_of_"
:Examples
 1st_inverse_moment_of_pdf_of_X
 2nd_inverse_moment_of_pdf_of_X
 2nd_moment_of_pdf_of_X
 3rd_moment_of_pdf_of_X
 cdf_of_X (cumulative distribution function)
 max_of_X
 mean_of_X (or first_moment_of_X)
 median_of_X
 mid-range_of_X (= (min + max)/2
 min_of_X
 mode_of_X
 pdf_of_X (probability density function)
 range_of_X (= max - min)
 standard_deviation_of_X
 variance_of_X
 variation_coefficient_of_X (standard deviation over mean)
* 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_average_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
* Note that "time_average_of" is used instead of "time_mean_of" because it more closely follows how scientists talk.
:
* 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. For this purpose we could introduce a "time_of" operation to be combined with the "time_max_of" operation, as in: "time_of_time_max_of_volume_flux". However, the CSDMS Standard Names use the more compact "peak_time_of" operation, as in:
 
 peak_time_of_volume_flux
* Similarly, it is not always clear how "mean_of_" should be interpreted unless extra adjectives/modifiers are used. For example, does "channel_water" + "mean_of_depth" mean the mean over: (1) a channel cross-section, (2) time, (3) the entire channel reach or (4) a grid of such values that spans the model domain? To remove this ambiguity, we use: (1) "time_mean_of" for a mean (or average) with respect to time and (2) "domain_mean_of" for a mean over the model domain. When "mean_of" occurs without the "time" or "domain" prefix, the mean is taken over the last object in the object part, as in "channel_water_x-section" + "mean_of_depth", or "channel_water" + "mean_of_depth".
:
* The operations, "cdf_of" and "pdf_of" were introduced on 8/28/14, for use in models that get a variable X from a random number generator. They can be used in constructions like:
 integral_from_0_to_2_of_pdf_of_X
 mean_of_pdf_of_X
== ==
  [ operator_name ] + "_of_"
:Examples
 alongshore_component_of_X
 anomaly_of_X (e.g. anomaly_of_pressure; see drop and increment)
 azimuth_angle_of_X (X must be a 2D or 3D vector field; returns an angle)
 biharmonic_of_X (X must be a scalar field)
 complement_of_X (90 - X, where X is an angle; see supplement_of below)
 cross-shore_component_of_X
 cross-stream_component_of_X
 depression_of_X (e.g. depression_of_melting_point_temperature)
 drop_of_X (e.g. drop_of_elevation, drop_of_pressure, drop_of_voltage)
 divergence_of_X (X must be a vector field; returns a scalar.)
 downstream_component_of_X
 down_component_of_X
 east_component_of_X
 elevation_angle_of_X (X must be a 3D vector field; returns an angle)
 increment_of_X (e.g. positive or negative change after one model time step)
 laplacian_of_X (X must be a scalar field; returns a scalar.)
 limit_of_X (asymptotic limiting value)
 loss_of_X (e.g. loss_of_energy; maybe use "drop_of_energy" instead ?)
 magnitude_of_X (X must be a vector or tensor)
 nadir_angle_of_X (also called "off-nadir angle")
 north_component_of_X
 offset_of_X
 offshore_component_of_X
 reciprocal_of_X (also called the "multiplicative inverse". "inverse" is a more general concept.)
 reduction_of_X (e.g. atmosphere_aerosol_dust + reduction_of_transmittance)
 scalar_potential_of_X (X must be a 2D or 3D vector field; X = grad(phi), where phi = scalar potential)
 shift_of_X
 streamfunction_of_X (X must be a 2D vector field; X = (phi_y, -phi_x), where phi = stream function)
 supplement_of_X (180 - X, where X is an angle; see complement_of above)
 up_component_of_X (### should we only use "z_component_of" ??)
 u_component_of_X (orthogonal curvilinear coordinates)
 v_component_of_X (orthogonal curvilinear coordinates)
 x_component_of_X (Cartesian coordinates)
 x_y_component_of_X (for tensors, like stress)
 y_component_of_X (Cartesian coordinates)
 z_component_of_X (Cartesian coordinates)
 zenith_angle_of_X (X must be a 3D vector field; returns an angle)
 
 land_surface__laplacian_of_elevation
* Note that the "magnitude_of" operation turns a vector or tensor quantity into a scalar quantity. Some magnitudes have shorter synonyms, such as speed = magnitude_of_velocity and slope = magnitude_of_gradient_of_elevation. The word "magnitude" can also work as a "quantity suffix", but should only be used as an operation.
:
* For a 2D vector field, the azimuth angle is just the official name for the angle in the xy-plane that is used in polar coordinates. (Depending on the context, it may be measured counter-clockwise from the x-axis, or clockwise from the north- or y-axis. A model should specify which angle convention it uses with an <assume> tag in its Model Coupling Metadata (MCM) file.) (Perhaps we should insert "x_ccw_" or "north_cw_" in front of the word "azimuth"?) For a 3D vector field, it is the polar coordinates angle of the projection of the vector onto the xy plane. See Azimuth and Spherical coordinate system.
:
* 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 elevation angle (sometimes called the "altitude angle") is the complement of the zenith angle; it is measured from the horizontal (xy) plane and is more commonly used in the geosciences than the zenith angle.
:
* Note that nadir (straight downward) is in the opposite direction of zenith (straight upward). Sometimes (e.g. when talking about the "looking angle" of a satellite) the term "off-nadir angle" is used, which is very descriptive. We could similarly use "off-zenith_angle" which seems to be more clear than "zenith_angle".
:
* The word "flow" can be used in the object part of the name as a shorthand for "flow_field". This is an example of the Object Name + Model Name Pattern, since vector components are really attributes of a mathematical model or construct, the flow field.
:
* The adjective "local" could 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 "azimuth_angle_of_gradient_of_elevation". This differs from the "aspect_angle", which is associated with the downhill vs. uphill/gradient direction, and therefore differs by 180 degrees. The aspect angle is therefore equivalent to the "azimuth_angle_of_antigradient_of_elevation". Note that "laplacian_of" should be used as a short synonym for "divergence_of_gradient_of". Note that "x_component_of_gradient_of_X" can be simplified to "x_derivative_of_X".
:
* There are also operations that act on two vector quantities and return a scalar, such as "cross_product_of_X_and_Y", "dot_product_of_X_and_Y" and "dot_product_angle_of_X_and_Y".
:
* Although both "alongshore" and "longshore" are used as synonyms, "alongshore" is used in the CSDMS Standard Names because it is less ambiguous.
:
* The term "inverse flattening ratio" is used for Earth ellipsoids, where "inverse" means "reciprocal" or "multiplicative inverse". The term "inverse" is really a more general mathematical concept -- the operation that "undoes" a given operation.
== ==
  [ operator_name ] + "_of_"
:Examples
 antigradient_of_X (X must be a scalar field; returns a vector; opposite_of_gradient_of_X)
 curl_of_X (X must be a vector field; returns a vector.)
 gradient_of_X (X must be a scalar field; returns a vector.)
 left_normal_of_X (X must be a 2D vector field; returns the vector field rotated CCW by 90 degrees)
 opposite_of_X (X must be a vector field; returns a vector.)
 right_normal_of_X (X must be a 2D vector field; returns the vector field rotated CW by 90 degrees)
 vector_potential_of_X (X must be a 2D or 3D vector field such that X = curl of vector_potential)
 ccw_rotation_of_X (X must be a 2D vector field) 
 cw_rotation_of_X (X must be a 2D vector field)
 scaling_of_X (X must be a vector field)
 dilation_of_X (X must be a vector field)
 contraction_of_X (X must be a vector field)
 translation_of_X (X must be a vector field)
 azimuthal_projection_of_X (X must be a 3D vector (not a field); result is 2D)
 atmosphere_air_flow__curl_of_velocity 
 atmosphere_air_flow__gradient_of_pressure
 bedrock_surface__antigradient_of_elevation
* 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".
:
* Note that the term antigradient is equivalent to (and shorter than) opposite_of_gradient. Flows are often in the direction of the antigradient of a scalar field.
:
* Note that the "laplacian_of" operation is equivalent to (but shorter than) the compound operation: "divergence_of_gradient_of_".
:
* A perpendicular vector field can be produced from a given 2D vector field by rotating either 90 degrees clockwise or counterclockwise (CCW). This is equivalent to swapping the 2 components and multiplying one of them by -1. The dot product of the original and rotated vector field will then be zero everywhere. Another way to refer to these 2 perpendicular vector fields, used here, is to use "left_normal" and "right_normal" as operations. Here, left and right are relative to the local direction of the 2D vector field.
:
* See: Curl, Divergence and Vector potential.
== ==
:
* The CF Standard Names were developed by Lawrence Livermore National Lab (LLNL) as standardized labels for variables stored in NetCDF files. In the 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)
* Unlike the CF transformations, the CSDMS operation templates attempt to express each operation 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).
:
* 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".
:
* 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, the "component_of" and "derivative_of" operations can be combined as in "time_derivative_of_x_component_of_velocity".
:
* CF Standard Names also has the transformation pattern: "change_over_time_in_X", with bounds given in metadata.
:
* 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 4 CF Standard Names that use the "x_derivative_of_" or "y_derivative_of_" pattern.
:
* Instead of the "change_in_X" transformation in the CF Standard Names, the CSDMS Standard Names have an "increment_of_X" operation. There is also "quantity suffix" called "increment" that can be applied to any base quantity to create a new base quantity, but this may become obsolete. See the discussion at the top of CSDMS Quantity Templates.
:
* There are currently no CF Standard Names that use "correlation_of_X_with_Y", "curl_of_X" or "gradient_of_X". There are only 2 that use "divergence_of_X" and 4 that use "direction_of_X".
:
:
: