CSN Object Templates

  CSDMS Standard Names — Quantity 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 "quantity templates". For "object templates", see: CSDMS Object Templates.
  
  

• The "templates" listed below are not exhaustive, but they do address many commonly needed cases where the pattern may not be obvious. Additional templates can be created from any of the "base objects" listed in the text file "CSDMS_Standard_Name_Objects.txt".
  
  

• 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 Wikipedia: Object (philosophy). A partial list of base objects is given in the text file: "CSDMS_Standard_Name_Objects.txt".
  
  

• A quantity frequently applies to an object that is part of another object, such as the trunk of a tree. In these cases, the object name begins with the main object and is appended with the name of the object part. For example:

alaskan_black_bear_head_mean_diameter
  (OR alaskan_black_bear_mean_head_diameter.  How to decide?)
channel_cross_section_area
channel_reach_sinuosity
gm_hummer_engine_volume
gm_hummer_gas_tank_volume   (or capacity)
gm_hummer_fuel_economy  [mpg]
oak_tree_trunk_diameter
   
A more complex example is: 
 alaskan_black_bear_brain_to_body_mass_ratio 

but here, "brain_to_body" serves as a quantity modifier/adjective.

• There are several terms that may provide a "short name" or synonym for another object, such as:

ice         = frozen_water
ocean       = sea_water      (maybe distinguish between these)
water       = liquid_water
water_vapor = gaseous_water
wind        = air_flow

Air

  base_object = "air"

Examples

air_density
air emissivity
air_pressure
air_refraction_index
air_temperature
air_thermal_capacity
air_water_vapor_pressure   ## (or water_in_air_vapor_pressure ?)
 
earth_atmosphere_density
earth_atmosphere_pressure
earth_atmosphere_refraction_index
earth_atmosphere_temperature
earth_atmosphere_thermal_capacity

• 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". In many cases it may be better (i.e. less ambiguous) to use "earth_atmosphere" instead of "air". This generalizes to "mars_atmosphere" while "air" connotes Earth.
  
  

• By analogy, perhaps we should use "earth_land_surface" instead of just "land_surface".
  
  

• Like water, air is generally contained within another object and can therefore be viewed as one of that object's parts. (And we have a naming pattern for this.) So we could have "scuba_tank_air" or "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

alaskan_black_bear
black_widow_spider
mexican_free_tail_bat   (Carlsbad Caverns)
small_mouth_bass
spade_foot_toad
 
alaskan_black_bear_max_running_speed
alaskan_black_bear_mean_adult_male_weight
alaskan_black_bear_mean_brain_to_body_mass_ratio
alaskan_black_bear_mean_digestion_period
alaskan_black_bear_mean_gestation_period
alaskan_black_bear_mean_hibernation_period
alaskan_black_bear_mean_lifetime   (or "life_time"?  "living_period"?)
alaskan_black_bear_mean_sleeping_period
alaskan_black_bear_mean_territorial_area

• Standard vocabularies for many types of organisms already exist. For example, CSIRO has compiled a standard vocabulary of fish names. See Yearsley et al. (2006). Wikipedia also has a list of common fish names at: CSIRO Common Fish Names. Standardized names should be used whenever possible, with the source of the names provided in the associated metadata. However, common names are not as specific as scientific (genus-species) names. For the design goals of a "ligua 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 — attribute" 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.
  
  

• See the Ratios quantity pattern.

Atoms, Compounds, Ions and Molecules

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

Examples

carbon_dioxide_acidity
carbon_dioxide_boiling_point_temperature    (remove "point" ??)
carbon_dioxide_density
carbon_dioxide_dynamic_viscosity
carbon_dioxide_kinematic_viscosity
carbon_dioxide_in_air_partial_pressure    #####  2 substances, with "in"
carbon_dioxide_in_water_solubility        #####  2 substances, with "in"
carbon_dioxide_melting_point_temperature    (remove "point" ??)
carbon_dioxide_molar_mass
carbon_dioxide_refractive_index
 
cesium_atomic_mass      (insert atom ??)
cesium_atomic_weight
cesium_atom_characteristic_vibration_frequency
cesium_atom_neutron_number
cesium_atom_proton_number

dihydrogen_molecule_bond_length  (dihydrogen = H2)
dioxygen_molecule_bond_length    (dioxygen = O2, dinitrogen = N2)
   ## Note: trioxygen is another name for ozone.

water_molecule_actual_bond_angle
water_molecule_bond_dissociation_energy
    (http://en.wikipedia.org/wiki/Bond-dissociation_energy)
water_molecule_ideal_bond_angle  (or replace "ideal" by "VSEPR" ?)
water_molecule_hydrogen_number  (??? number of hydrogen atoms)
water_molecule_hydrogen_to_oxygen_bond_length
     OR water_molecule_hydrogen_to_oxygen_distance ?? (See Distance.)
     OR water_molecule_H_to_O_distance

• 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.
  
  

• For 3D (nonplanar) molecules, "torsion" (or "dihedral") angles can be specified. See: Wikipedia: Molecular Geometry.
  bond length is defined for 1 bond (2 atoms, e.g. dihydrogen)
  bond angle is defined for 2 consecutive bonds (3 atoms, e.g. water)
  torsion angle is defined for 3 consecutive bonds (4 atoms, e.g. ethane, C2H6)
  These are all defined as time averages. Ethane seems to have three different torsion angles, which are all "H_to_C_to_C_to_H".
  
  

• If all angles are the same, we can have things like:
  - benzene_molecule_C_to_C_to_C_bond_angle OR benzene_ring_bond_angle ???
  - benzene_molecule_C_to_C_to_H_bond_angle  ??
  
  

• There is also something called a "ligand cone angle"; see: Wikipedia: Ligand Cone Angle and a "ligand [natural] bite angle": Wikipedia: Bite Angle.
  
  

Channels, Streams, Rivers, Etc.

  object = "channel"

Examples

channel_water_flow_speed

• 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.
  
  

  Channel Parts

  object = "channel_bed"
  object = "channel_cross_section"
  object = "channel_head"
  object = "channel_mouth"
  object = "channel_reach"
  object = "channel_water"

Examples

channel_bed_d50_roughness_length
channel_bed_d84_roughness_length
channel_bed_manning_roughness_parameter
channel_bed_relative_roughness_ratio     (a dimensionless ratio)
channel_bed_mean_roughness_length
channel_bed_mean_shear_stress        ("shearing" may be better)
channel_bed_water_hydrostatic_pressure
channel_bed_water_pressure
 
channel_cross_section_area
channel_cross_section_depth_slope_product   ## (or channel_bed_depth_slope_product ??)
channel_cross_section_hydraulic_radius
channel_cross_section_max_depth
channel_cross_section_perimeter
channel_cross_section_top_width    (the top_width is usually the max)
channel_cross_section_trapezoid_bank_angle
channel_cross_section_trapezoid_bottom_width
channel_cross_section_wetted_perimeter
channel_cross_section_width_to_depth_ratio
 
channel_head_elevation
 
channel_mouth_d8_contributing_area
channel_mouth_elevation
channel_mouth_slope   ???

channel_reach_absolute_sinuosity
channel_reach_elevation_difference   (use difference as a quantity suffix ??)
channel_reach_length
channel_reach_meander_amplitude
channel_reach_meander_period
channel_reach_total_water_volume  (or channel_reach_water_total_volume ??)
 
channel_water_density
channel_water_discharge  (or channel_cross_section_water_discharge ??)
channel_water_friction_factor   #####
channel_water_froude_number
channel_water_max_depth
channel_water_mean_depth
channel_water_mean_speed   (speed = "velocity magnitude"; don't need "flow_speed"?)
channel_water_pressure     (anywhere in the channel; see channel_bed_water_pressure)
channel_water_temperature

• Note that "channel_bank_angle" by itself is ambiguous; is it the angle the bank makes with the vertical z-axis or with a horizontal x-axis?
  
  

• A quantity like "bottom_width" or "bank_angle" may only be well-defined for cross-sections of a particular shape, like a trapezoid. So we may want to insert the word "trapezoid" for these. Similarly, we could have "channel_cross_section_half_circle_radius".
  
  

• We talk of "channel_networks", but the network is not part of the channel.
  
  

• See the object pattern for Watershed, Basins and Catchments.

Coastlines, Shorelines and Beaches

Examples

(None yet)

Earth and Other Planets

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

Examples

earth_ellipsoid_eccentricity
earth_ellipsoid_equatorial_radius   (= semi_major_axis_length)
earth_ellipsoid_flattening_ratio
earth_ellipsoid_polar_radius        (= semi_minor_axis_length)
earth_mass
earth_mean_density
earth_orbit_eccentricity   (or earth_orbital_eccentricity)
earth_solar_irradiation_constant
    OR earth_insolation_constant
earth_to_sun_mean_distance
    OR earth_orbit_mean_radius  ???

• 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.
  
  

Glaciers, Land Ice, Ice Sheets

  object = "glacier"
  object = "glacier_ice"

Examples

glacier_ice_density
glacier_ice_depth
glacier_ice_temperature

• CF Standard Names use "land_ice" instead, contrasted with "sea_ice". If the quantity is an attribute of ice, we may want to add the word "ice" after glacier.
  
  

Product of a Given Company

  object = company_name + product_name

Examples

gm_hummer_total_weight
porsche_911_mrp   (cost)
porsche_911_max_speed
toyota_corolla_2008_blue_book_price  ??
toyota_corolla_gas_tank_volume
toyota_corolla_fuel_economy   [mpg]
toyota_corolla_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.
  
  

• See CSDMS Quantity Template for Fuel Efficiency.

Sea Water, Ocean

  object = "sea_water"

Examples

sea_water_eastward_velocity_component
sea_water_flow_speed       (or sea_water_velocity_magnitude; insert "flow"?? ##########)
sea_water_depth     (or "total_depth" ??)
sea_water_electrical_conductivity
sea_water_salinity
sea_water_secchi_depth
sea_water_surface_elevation
sea_water_surface_temperature
sea_water_temperature
sea_water_thermal_capacity

• 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 (e.g. sea_water_surface_wave).

Snow

  base_object = "snow"

Examples

snow_density
snow_depth
snow_grain_size
snow_melt_rate
snow_thermal_capacity
snow_thermal_energy_content

• We could use "surface_snow" (maybe CF does), but is that necessary?

Soil

  base_object = "_soil"

Examples

soil_effective_saturated_hydraulic_conductivity
soil_hydraulic_conductivity
soil_pressure_head
soil_saturated_hydraulic_conductivity
soil_saturated_water_content
soil_surface_infiltration_rate   (or vertical_flow_rate ??)
soil_porosity
soil_water_content
soil_vertical_flow_rate
 
clay_in_soil_volume_fraction   (using object_in_object pattern)
sand_in_soil_volume_fraction
silt_in_soil_volume_fraction

Surfaces and Isosurfaces

  base_object = "surface"
  base_object = "isosurface"

Examples

beach_surface
bedrock_surface
glacier_bottom_surface
glacier_top_surface
land_surface
sea_floor_surface   (or seabed_surface, or sea_bottom_surface ?)
sea_water_surface
tropopause_surface
water_table_surface  (or ground_water_table_surface)

• 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.
  
  

• Words like "bed", "floor" and "table" imply a surface, but we include the word "surface" as a base object anyway to create a natural grouping.
  
  

• We often want to refer to the "top" or "bottom" surface.
  
  

• Quantities like aspect_angle, plan_curvature, profile_curvature, slope and slope_angle can be associated with any surface.
  
  

Watersheds, Basins and Catchments

  object = "watershed"
  object = "watershed_boundary"
  object = "watershed_outlet"

Examples

watershed_boundary_diameter
watershed_boundary_shape_factor
watershed_boundary_perimeter
watershed_burned_area_fraction
watershed_d8_area             (i.e. upstream, contributing area)
watershed_d_infinity_area
watershed_drainage_density
watershed_forested_area_fraction
watershed_mass_flux_area      ####
watershed_outlet_slope  ###  (channel_slope ??)
watershed_outlet_suspended_sediment_discharge
watershed_outlet_water_depth
watershed_outlet_water_discharge
watershed_outlet_water_speed
watershed_outlet_width
watershed_outlet_width_to_depth_ratio
watershed_source_density
watershed_total_channel_length

• The word "basin" is used in other, non-water-related contexts.
  
  

• "watershed_boundary" seems better than "watershed_drainage_divide". We could introduce "watershed_interior" also, if needed.
  
  

• "watershed_polygon" relates to our shape pattern (i.e. trapezoid, ellipsoid)
  
  

Waves in Air

  base_object = "wave"

Examples

atmospheric_internal_gravity_wave
atmospheric_lee_wave  (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_water_internal_wave"
  object = "sea_water_surface_wave"
  object = "water_capillary_wave"

Examples

sea_water_surface_wave_height
sea_water_surface_wave_incidence_angle
sea_water_surface_wave_length
sea_water_surface_wave_number
sea_water_surface_wave_speed        (group or phase ??)
sea_water_surface_wave_steepness

• 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.
  
  

• 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.

Wind

  base_object = "wind"

Examples

wind_direction_angle
wind_reference_height_speed   (or maybe reference_height_wind_speed ??)
wind_speed               (vs. air_flow_speed)
wind_speed_reference_height

• Notice that "reference_height" and "wind_speed" can form a coupled pair of quantities: reference_height_wind_speed and wind_speed_reference_height, where the other quantity serves as an adjective/modifier. But what is the object in "reference_height_wind_speed"?
  
  

• While "wind" could be called "air_flow" (which follows the "object - process" pattern) we use the more common and widely-recognized term when possible.
  
  

• What about gusts, or speeds sustained for some time period?