CSN Object Templates: Difference between revisions
No edit summary |
No edit summary |
||
Line 1: | Line 1: | ||
{{TOC limit| | {{TOC limit|2}} | ||
= '''[[CSDMS_Standard_Names | CSDMS Standard Names]] — Object Templates''' = | = '''[[CSDMS_Standard_Names | CSDMS Standard Names]] — Object Templates''' = |
Revision as of 11:08, 15 August 2012
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". 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 be 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 Wikipedia: 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 Metadata 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.
- 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 Metadata File. See the Animals and Plants template below for examples.
- 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 (nesting from the general to the specific). The Channel Parts template below gives many examples. Some additional examples are:
alaskan_black_bear_head_mean_diameter (OR alaskan_black_bear_mean_head_diameter. How to decide?) channel_cross_section_area channel_reach_sinuosity earth_axis_tilt_angle earth_orbit_eccentricity 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.
- 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_cross_section_perimeter". Note that model assumptions (geometric shapes in these examples) should always be included in the Model Metadata File with an<assumption> 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_cross_section_trapezoid_bottom_width earth_ellipsoid_equatorial_radius land_surface_plan_curvature
- 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, 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 — 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 quantity template for Ratios in CSDMS Quantity Templates.
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 (Wikipedia: 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_axis"
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.
- The distance from the earth to the sun requires specifying two objects. There is a Quantity Name pattern for this case that uses the word "to", as in: "earth_to_sun_mean_distance".
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_field_capacity_water_content soil_hydraulic_conductivity soil_hygroscopic_water_content soil_initial_water_content soil_normalized_water_content (also called "effective saturation") soil_pressure_head soil_residual_water_content soil_saturated_hydraulic_conductivity soil_saturated_water_content soil_surface_infiltration_rate (or vertical_flow_rate ??) soil_porosity soil_vertical_flow_rate soil_water_content soil_wilting_point_water_content
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 ground_water_table_surface land_surface sea_floor_surface (or seabed_surface, or sea_bottom_surface ?) sea_water_surface tropopause_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. 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 = "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" would be another example of our Object_name + Model_name Pattern.
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.
- 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".
- There are many specific types of waves, often named after their discoverer, such as Kelvin waves, Rossby (gravity) waves, Lamb waves, Rayleigh waves, Tollmien-Schlicting waves and edge 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.
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" (object_name + process_name), which would allow us to use our Process_name + Quantity Pattern, we use the more common and widely-recognized term in such cases.
- What about gusts, or speeds sustained for some time period?