Document domain characteristics
What This Task Involves
Describing the physical variables used in software by using an ontology of standard names.
Training Materials
This training session was held on May 15, 2015:
- CSDMS Standard Names, includes slides and a paper
Suggested Readings
What To Do
Variables are symbols associated with values (numerical or string type) and are arguably the fundamental currency of science. These are the things we observe and measure, save in databases and predict with our computational models (and use to drive them). They are also the key players in the equations that govern our physics. They are the "exchange items" that are passed between connected resources (e.g. models and datasets). However, to automate the sharing of variables between resources, semantic mediation is necessary, since every resource has its own internal vocabulary.
This zipped Excel spreadsheet has a few examples of how to provide information on your model's internal variable names --- that is, the actual names, symbols or abbreviations you use in your model's source code. You can delete the example entries (but not the column headings) and then enter similar information for your model. For each variable name that your model uses internally, please go to: Searchable List of CSDMS Standard Names, then use your browser's search feature, along with the alphabetization, to search for a CSDMS Standard Variable Name that exactly matches that internal variable name. If found, enter it in the appropriate column in the spreadsheet. (Note: While this mapping is needed, there is no need to change your model's internal names.) Otherwise, you can try to construct a standard name that conforms to the rules at: Basic Rules of the CSDMS Standard Names and then enter SUGGESTED in the Notes column of the spreadsheet. If you don't want to try to construct a name, you can enter NOT FOUND in the Notes column. Please note that internal variables such as counters, intermediates and others that you don't foresee sharing with another model do not need to be listed in this spreadsheet. You can think of the variables in the spreadsheet as your model's "exchange items". This mapping from your model's internal variable names to standardized, descriptive and unambiguous variable names is very similar to a List of Symbols, which are often included scientific publications. It is also required to implement a Basic Model Interface (BMI) for your model.
In the Units column, use standard units abbreviations followed by a positive or negative number to indicate a power, and spaces between as in "m s-1" for velocity units or "m3" for volume units. In the Variable Kind column, indicate whether the variable is an input variable, output variable, or a model configuration variable. Configuration variables are those that your model reads from its configuration file (often a text file with key-value pairs) prior to each run. Note that a variable can be both a configuration variable and an output variable, or and input variable and an output variable. This simply means that your model, after acquiring the variable, can also share it as output. Use the slash character as in "config/output" in such cases.
The CSDMS Standard Names also includes a standardized list of model assumptions that can be used to attach additional descriptive information to model objects, quantities, grids or the model itself. The CSDMS Standard Assumption Names are a work in progress that is divided into 26 different categories (or facets) of assumptions. Software and an associated ontology is under development to make it easier to provide this new type of model metadata.
