CSN Object Templates

From CSDMS

  CSDMS Standard Names — Object Templates

  • A CSDMS Standard Name must have an "object" part and a "quantity" part, with adjectives and modifiers (as prefixes) being used to help avoid ambiguity and identify a specific object and associated quantity. This document contains "object templates". Some examples are given here after a short discussion of the rules, although they are not all up-to-date. Many more (and current) examples can be found at: CSDMS Standard Name Examples. For "quantity templates", see: CSDMS Quantity Templates.
  • The "templates" listed below are not exhaustive, but they do address many commonly needed cases where the pattern may not bealaskan_black_bear obvious. Additional templates can be created from any of the "base objects" listed in the text file "CSDMS_Standard_Name_Objects.txt".
  • Each template includes examples and explanatory notes, and many of them make reference to the CF Standard Names, sometimes using the abbreviation "CF".
  • Object appears to be the right word choice. It is used in the same sense in object-oriented programming. For example, in Java, the base class for all objects is "Object". See Object (philosophy). A partial list of base objects is given in the text file: "CSDMS_Standard_Name_Objects.txt".
  • General Base Object Name Rule. Some object names have many synonyms or closely related terms. For example, the words "channel", "creek", "brook", "stream" and "river" all refer to a similar concept. In such cases a single object name may be selected to represent that "type" of object so that potential matches are more likely. (Specific assumptions on size, etc. are provided in a Model Coupling Metadata (MCM) file using the CSDMS Assumption Names.) In the above example, the word "channel" has been selected as the representative term because it doesn't have a size connotation. Note that there are textbooks on "open channel flow", we talk of "channelized flow" and then there is the English Channel. See the Watershed template for another example.
  • Use of Standard Object Names Rule. Lists of standardized object names have been compiled for several classes of objects and organisms. In such cases, there may be a common name and a scientific name. CSDMS promotes the use of standardized object names when they exist but their source must be provided using an <object_name_source> tag in the Model Coupling Metadata (MCM) file. See the Animals and Plants template below for examples. The IUPAC has developed a standard nomenclature for chemical compounds.
  • Part of Another Object Pattern. A quantity frequently applies to an object that is part of another object, such as the trunk of a tree. Another example is a hierarchy of organizations, such as (country + agency + program), (e.g. "US", "NOAA", "NWS"). Also see the Product of a Company template. In these cases, the object name begins with the main object and is appended with the name of the object part, building left to right from the general to the specific. The Channel Parts template below gives many examples. The first example below also uses the Object-to-object Quantity Pattern from the CSDMS Quantity Templates. Examples include:


automobile_engine__volume
automobile_fuel__consumption_rate
automobile_fuel-tank__volume   (or capacity)
automobile__fuel_economy  [mpg]
bear~alaskan~black_brain-to-body__mass_ratio
bear~alaskan~black_head__mean_diameter
channel_x-section__area
channel_centerline__downvalley_sinuosity
earth_axis__tilt_angle
earth_orbit__eccentricity
tree~oak~bluejack_trunk__diameter
An important variant of this pattern is that words like "top", "bottom", "edge~east", "edge~north", "vertical-x-section", "center", "centroid" and "layer" may also be viewed as "parts" of an object and handled in the same way. (Note: "side~left" and "side~right" can also be used, and are taken relative to the direction of flow or travel). Examples include:
atmosphere_top_air__temperature   (the CF Standard Names use "toa" as an abbreviation for "top of atmosphere")
atmosphere_bottom_air__pressure
channel_bottom_water__static_pressure
channel_bottom_water__temperature
earth_orbit_aphelion__distance
glacier_terminus_side~left__latitude
glacier_top_ice__temperature
land_surface__infiltration_rate
land_surface_air__temperature
model_grid_cell_center__latitude
model_grid_cell_edge~east__latitude
sea_bottom_sediment_layer__thickness
sea_photic-zone_bottom__depth
soil_sat-zone_top__depth
  • Object_name + Model_name Pattern. Some quantities are only well-defined for some idealized version or model of a given object. For example, the quantities "equatorial_radius" and "semi_major_axis_length" are only well-defined for a planet when the planet shape is approximated as an ellipsoid. As another example, the quantities "bottom_width" and "bank_angle" are only well-defined when the channel cross section shape is approximated as a trapezoid. As a third example, a quantity such as "plan curvature" only makes sense for a mathematical surface that is "twice differentiable". However, there are often other quantities that do not depend on any such assumption regarding the shape, such as "earth" + "mass" and "channel_x-section" + "perimeter". Note that model assumptions (geometric shapes in these examples) should always be included in the Model Coupling Metadata (MCM) file with an <assume> tag and a value such as "trapezoid_shaped". See CSDMS Assumption Names for more information. When a quantity depends on a "model" assumption, we insert the "model name" after the object name as in:
channel_centerline + length
channel_x-section_trapezoid + bottom_width
earth_ellipsoid + equatorial_radius
earth_mean-sea-level-datum_air + pressure
land_surface + plan_curvature
A variant of this pattern occurs when naming quantities that are associated with a named model for the object, such as the Brooks-Corey soil model or the Green-Ampt infiltration model. The model is often indicated with one or more last names of people (and often followed by the word "law"), inserted as a modifier between the object_name and the quantity_name, as in:
basin__flint_law_exponent     (vs. "flint_law_concavity_exponent")
basin__flint_law_coefficient   (vs. "flint_law_steepness_parameter")
basin_channel~longest__hack_law_coefficient
basin_channel~longest__hack_law_exponent
channel__downstream_hydraulic_geometry_width_vs_discharge_coefficient
channel__downstream_hydraulic_geometry_width_vs_discharge_exponent
earth_interior_earthquake__gutenberg-richter_law_a_parameter
glacier_ice__glen_law_coefficient
glacier_ice__glen_law_exponent
soil_water__brooks-corey_b_parameter
soil_water__green-ampt_capillary_length
soil_water__smith-parlange_gamma_parameter
soil_water__van-genuchten_alpha_parameter

or:   glacier + glen_law_strain_rate_vs_shear_stress_exponent   ??
       basin + flint_law_slope_vs_area_exponent ??
For a named, power-law model, there is generally one coefficient and one or more exponents. Interpretations of coefficients and exponents (e.g. concavity, creep, steepness) are redundant and can be excluded. In the case of multiple exponents, the name of the quantity that is being raised to a power is inserted, as in "area_exponent", "conductivity_exponent" and "slope_exponent". Note that vs is used as a special reserved word.
  • Object-as-Object Pattern (under review). The amount of a chemical species present in a sample (e.g. in atmospheric chemistry) is often expressed in terms of the amount of a particular element/constituent in the sample. For example, the term "clox" (ClOx) is used to describe a family called "chlorine radicals" that contain inorganic chlorine, and the amount of chlorine radicals is quantified as the amount of chlorine. (See: Radical.) In the CF Standard Names, the pattern "X_expressed-as-Y" is used in 149 names. In the CSDMS Standard Names, the reserved word "as" is used, as in these examples:
atmosphere_air-column_clox-as-chlorine__mass-per-area_density    (or "chlorine_radicals-as-chlorine" ?)
atmosphere_air-column_hox-as-hydrogen__mass-per-area_density 
atmosphere_air-column_nox-as-nitrogen__mass-per-area_density 
 
sea_water_diatoms-as-carbon__mass_concentration
sea_water_diatoms-as-chlorophyll__mass_concentration
sea_water_diatoms-as-nitrogen__mass_concentration
The reserved word as could also be used in situations where one measured quantity serves as a surrogate for another, perhaps as in "activity-as-ph", "pressure-as-height" or "salinity-as-electrical_conductivity".


Air

  base_object = "air"

Examples
See Attributes of the Atmosphere on the page  CSDMS Standard Name Examples.
  • This refers to the mixture of gases in Earth's atmosphere. As a simple term for a complex mixture, it is similar to terms like "soil" and even "sea_water".
  • The word "atmosphere" is sometimes used to mean a place or a container that has attributes such as "thickness". In other contexts it is used as a synonym for "air", which is the substance that occupies that "container", with attributes such as "density". (In Wikipedia, air redirects to Atmosphere of Earth.) This distinction is carefully considered when constructing CSDMS Standard Names, where the goal is for names to be consistent, unambiguous and easily understood. Note that we could use "mars_atmosphere" to refer to either the specific mixture of gases in the atmosphere of Mars or the place/container.
  • Similarly, "land_surface" by itself is taken to mean a land surface on Earth. For Mars, we could use "mars_land_surface" if the distinction was important.
  • Like water, air is generally contained within another object and can therefore be viewed as one of that object's parts. The Part of Another Object Pattern addresses this issue. So we could have "balloon_air" or "scuba_tank_air". (And perhaps "earth_atmosphere_air"?)
  • Air is also used to indicate a domain, as in traveling by land, sea or air. This is also reflected in: Army, Navy, Air Force.
  • See Atoms, Compounds, Ions and Molecules.


Animals and Plants

  object = organism_name

Examples
bass~small-mouth
bat~mexican~free-tail   (Carlsbad Caverns)
bear~alaskan~black
spider~black-widow
toad~spade-foot
 
bear~alaskan~black + max_running_speed
bear~alaskan~black~adult~male + mean_weight
bear~alaskan~black_brain-to-body + mean_mass_ratio
bear~alaskan~black + mean_digestion_period
bear~alaskan~black + mean_gestation_period
bear~alaskan~black + mean_hibernation_period
bear~alaskan~black + mean_lifetime   (or "life_time"?  "living_period"?)
bear~alaskan~black + mean_sleeping_period
bear~alaskan~black + mean_territorial_area
  • Standard vocabularies for many types of organisms already exist. For example, Yearsley et al. (2006) compiled the CSIRO Standard Fish Names in Australia. Wikipedia also has a List of Common Fish Names. Standardized names should be used whenever possible, with the source of the names provided in the associated metadata using the tag "object_name_source". However, common names are not as specific as scientific (genus-species) names. For the design goals of a "lingua franca", we could just select one source for each common or scientific name and indicate that source.

  • Note that "mean" was inserted in each of the above examples. This word removes ambiguity (i.e., it indicates an average value for a population vs. the value for an individual) but perhaps it should be placed with the metadata.

  • Note that "lifetime" is a compound word that ends in "time", which connotes units of time. This can be viewed as another variation of the Process_name + Quantity Pattern", where "life" indicates the process of "living" and we are interested in the duration of that process. We avoid "life_expectancy" here because "expectancy" is an ambiguous base quantity name, similar to expectation, better viewed as an operator. We are frequently interested in attributes of processes that act on a particular object as another type of attribute for the object.

  • Note that our lingua franca is focused on "numerical attributes" that have units, called "quantities". Animals have many other attributes, e.g. behaviors, food preferences, habitats, geographical distribution, etc. which are not quantities and are beyond the current scope.


Atoms, Compounds, Ions and Molecules

  object = [ element_name ] + [ "_atom" ]
  object = [ compound_name ] + [ "_compound" ]
  object = [ molecule_name ] + [ "_molecule"]

Examples
See Attributes of the Atoms and Attributes of Molecules on the page  CSDMS Standard Name Examples.
  • Insert the word "atom", "molecule", etc. whenever necessary to remove ambiguity between the substance and the atom (e.g. iron) or molecule (e.g. water). The absence of these extra words implies a "bulk" quantity.
  • It seems that compound is the most general term for atoms held together by some type of chemical bond. A molecule is a special type of compound that is (1) electrically neutral and (2) held together by covalent bonds. An ion is a (compound or molecule??) that carries a charge.


Channels, Streams, Rivers, Etc.

  object = "channel"

Examples
See Attributes of Channels on the page  CSDMS Standard Name Examples.
  • The word "channel" seems preferable as a general term to words like "creek", "stream" and "river" because it doesn't have a size connotation. For example, there are textbooks on "open channel flow", we talk of "channelized flow" and then there is the English Channel.
  • We could allow terms like "stream" and "river", but this will reduce the number of potential matches when coupling models.
  • Note that "channel_bank_angle" by itself would be ambiguous; is it the angle the bank makes with the vertical z-axis or with a horizontal x-axis? However, "channel_cross_section_trapezoid_bank_angle" is clear.
  • A quantity like "bottom_width" or "bank_angle" may only be well-defined for cross-sections of a particular shape, like a trapezoid. In such cases we use the Object_name + model_name Pattern.
  • We talk of "channel networks", but the network is not part of the channel, it is part of a drainage basin (e.g. basinchannel-network).
  • An outlet would be considered part of a drainage basin and not part of a channel. See the object pattern for Watershed, Basins and Catchments.


Coastlines, Shorelines and Beaches

Examples
See Attributes of Oceans (sea_shoreline) on the page  CSDMS Standard Name Examples.


Earth and Other Planets

  object = "earth"
  object = "earth_axis"
  object = "earth_ellipsoid"
  object = "earth_orbit"

Examples
See Attributes of Planets on the page  CSDMS Standard Name Examples.
  • A quantity like "equatorial_radius" or "flattening_ratio" may only be well-defined for particular planet shapes, like an ellipsoid. So we may want to insert the word "ellipsoid" for these.
  • The distance from the earth to the sun requires specifying two objects and uses the Object-to-object Quantity Pattern to produce "earth-to-sun_mean_distance".


Glaciers, Land Ice and Ice Sheets

  object = "glacier"

Examples
See Variable Names for Glaciers and Variable Names for Sea Ice on the page  CSDMS Standard Name Examples.


  • CF Standard Names use "land_ice" instead, contrasted with "sea_ice".


Hydrometeors

  object = "atmosphere_hydrometeor"

Examples
See Variable Names for the Atmosphere on the page  CSDMS Standard Name Examples.
  • This is a general term for precipitating water in any of its possible forms, including: ice, sleet, hail, rain, snow and graupel.
  • For a substance other than water, a prefix other than "hydro" should probably be inserted in front of "meteor".


Product of a Company

  object = company_name + product_name

Examples
gm_hummer_total_weight
porsche~911 + msrp_price
porsche~911 + top_speed
toyota_corolla~2008 + kelley_blue_book_price  ??
toyota_corolla~2008_fuel-tank + volume
toyota_corolla~2008 + fuel_economy   [mpg]
toyota_corolla~2008 + motor_trend_magazine_safety_rating
     (or "motor_trend_magazine" could go into metadata; how measured)
  • We would do something similar for organizations contained within other organizations, such as "us_noaa_nws" (country_agency_program). The general pattern is to go from the general to the specific.


Sea Water and Ocean

  object = "sea_water"

Examples
See Attributes of Oceans on the Examples page for many examples.
  • The word "sea_water" is preferable to "ocean" when the quantity is an attribute of the water. CF Standard Names have a different rule to decide when to use "ocean" vs. "_sea_water" (double check).

  • See Waves.


Snow

  base_object = "snow"

Examples
See Attributes of Snow on the page  CSDMS Standard Name Examples.
  • We could use "surface_snow" (maybe CF does), but is that necessary?
  • The concept of "snow" generalizes to frozen precipitation of other substances like carbon dioxide (on Mars) and methane (on Jupiter's moon, Titan). The current and natural trend is to simply call these "carbon_dioxide_snow" and "methane_snow". The word "snow" used by itself then means "water_snow". Similarly, we would use "carbon_dioxide_ice" and "methane_ice", even though the former is also known as "dry ice".


Soil

  base_object = "soil"

Examples
See Attributes of Soil on the page  CSDMS Standard Name Examples.


Surfaces and Isosurfaces

  base_object = "surface"
  base_object = "isosurface"

Examples
See Attributes of the Topography, Attributes of Oceans, etc. on the page  CSDMS Standard Name Examples.
  • Here, "surface" means a function, z(x,y), that associates a single value (usually an elevation) with every point (or grid cell) in the horizontal plane. Note that an "isosurface" may not be expressible as z(x,y), e.g. surfaces of constant pressure or temperature, etc. Isosurfaces can associate multiple values with a given (x,y) position.

  • Words like "bed", "floor" and "table" imply a surface, but we still include the word "surface" in the object name in accordance with the Object_name + Model_name Pattern. It also creates a natural grouping.

  • Quantities like aspect_angle, plan_curvature, profile_curvature, slope and slope_angle are not always well-defined for real topography. Strictly speaking, these concepts only apply to a mathematical surface that is used to approximate the topography. Quantities like slope and aspect require a surface that is smooth enough to be differentiated once. Any type of curvature (e.g. plan, profile, tangential, streamline, laplacian) requires a surface that is smooth enough to be differentiated twice. This again shows why "surface" is included in the object name in accordance with the Object_name + Model_name Pattern.

  • We often want to refer to the "top" or "bottom" surface and then just add these additional modifiers before the word surface.


Watersheds, Basins and Catchments

  object = "basin"
  object = "basin_boundary"
  object = "basin_outlet"

Examples
See Attributes of Basins on the page  CSDMS Standard Name Examples.


Waves in Air

  base_object = "wave"

Examples
atmospheric_wave~internal~gravity
atmospheric_wave~lee  (OR   atmospheric_standing_wave)
hydrostatic_wave
rossby_wave   (or planetary_wave)
  • See "Lee Wave" in Wikipedia.

  • What about "sound waves" ??


Waves in Water

  object = "sea_surface_water_wave"
  object = "water_wave~capillary"

Examples
See Attributes of the Oceans on the page  CSDMS Standard Name Examples.
  • To avoid ambiguity, always add an adjective like "surface" or "internal" in front of the word "wave". Note that "surface_wave" means "surface gravity wave" and "internal_wave" means "internal gravity wave". In both cases, gravity (or buoyancy) is a restoring force acting at the interface of two fluids with different densities.
  • Note that a "gravitational wave" is a ripple in the curvature of spacetime, first predicted by Einstein. See Wikipedia: Gravitational Wave. They are not the same as "gravity waves".
  • Other types of waves include: "breaking", "capillary", "solitary" and "tsunami". So we could have "surface_breaking_wave" and "surface_capillary_wave". Do we want to include words like "rogue", "sound", "standing", "swell" and "wind" as wave types ?? ######
  • See Sea Water.
Retrieved from "https://csdms.colorado.edu/csdms_wiki/index.php?title=CSN_Object_Templates&oldid=84487"