Merge pull request #11 from USEPA/versionschemeupdate

Further schema update

VersioningScheme.md

@@ -2,60 +2,59 @@
 
 USEEIO model names follow a scheme.
 These model names are intended to identify a model by version and a set of key characteristics. 
-They are independent of the software or authors producing the model.
+They are independent of the software (with the exception of the `build` identifier) or authors producing the model.
 They are not full model descriptions.
-
+A named model does not imply that the model has been reviewed or released. 
 
 ## Naming pattern
 Model names are composed of parts in a clear pattern.
-The naming pattern is a set sequence of these parts with required separator characters.
+The naming pattern is a set sequence of these parts with separator characters that are required when the given part is present.
 ```
-{prefix}{root} v{major}.{minor}.{update}{form}{sectors}-{IOyear}-{subset}
+{loc}{root} v{major}.{minor}.{patch}+{build}-{form}{#sectors}-{#regions}r-{IOyear}-{subset}
+
 ```
+The version number is the major.minor.patch sequence. The version number plus the build identifier follows [Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.html) for software with some adaptations appropriate for use for a computational model versioning scheme.
 
 ## Name parts
 The following table define the parts of a model name.
 
-| Name part | Definition | Format | Default|  Example |
+| Name part | Definition | Format | Example | Assumed Value if Absent|
 |---|---|---|---|---|
-| prefix | Primary model region | Two-letter state name for state models| Blank, assumes national model| `GA`|
-| root   | Main model name | String | USEEIO | `USEEIO`|
-| major  | Major version number. Advances indicate a major methodological/data update | Integer | NA | `2` |
-| minor  | Minor version number. Advances indicate a minor methodological/data update | Integer | NA | `0` |
-| update | Update number. Advances indicates a minor fix or data update | Integer | NA | `1` |
-| form   | Indicator for CommodityxCommodity or IndustryxIndustry form | 'i' for IxI form | Blank, assumes default CXC | `i` |
-| sectors<sup>1</sup> | Base level of BEA ([see definitions](https://www.bea.gov/sites/default/files/methodologies/industry_primer.pdf#page=17)) or number of sectors | <ul><li>Character for a BEA level - 's' for Summary, 'c' for Sector, OR</li><li>Integer for an arbitrary number<sup>2</sup></li></ul> | Blank, assumes Detail level | `s` or `75` |
-| IOyear | Optional year of base input-output data | Integer | For deviation from IO year in base version | `2017` |
-| subset | Short name for a satellite or indicator subset | Hyphen followed by 3-6 digit string with letter in CAPS | Blank, assumes all satellite tables available for that region are present | `-GHG` |
-
-<sup>1</sup> If `sectors` is a letter, it means the model uses the original BEA Summary sectors; if it is a number, it means model sectors are hybridized (e.g. disaggregated and/or aggregated) and are not identical with the original BEA Summary sectors.
-
-<sup>2</sup> If the previous part is also an integer, a hyphen will be added before the integer, e.g. `USEEIOv2.0-411`.
+| loc   | Two-letter acronym for primary model location/region | string | `US`| not applicable|
+| root  | Main model type | string | `EEIO`| not applicable|
+| major | Major version number. Advances are for use of a new base IO schema | integer | `2` | not applicable|
+| minor | Minor version number. Advances indicate a minor methodological/data update | integer |  `0` | not applicable|
+| patch | OPTIONAL but PREFERRED. A patch number. Advances indicates a minor fix, format, or data update | integer | `1` | `0`|
+| build | OPTIONAL. A build identifier derived from software during model build time | string | `c2nde3d` | blank means not available|
+| form  | OPTIONAL. Indicator for Commodity x Commodity or Industry x Industry form | 'c' for commodityxcommodity , 'i' for industryxindustry | `i` | `c`|
+| #sectors<sup>1</sup> | OPTIONAL. Base level of BEA, ([see definitions](https://www.bea.gov/sites/default/files/methodologies/industry_primer.pdf#page=17)); or number of sectors | <ul><li>string for a BEA level - 'd' for detail, 's' for Summary, 'c' for Sector, OR</li><li>integer for an arbitrary number | `s` or `75` | `d` |
+| #regions | OPTIONAL. Number of model regions when greater than 1 | integer | `2` | `1` |
+| IOyear | OPTIONAL. Year of base input-output data. Used for deviations from the benchmark IO year of the major version | integer |  `2017` | IO data year for IO schema and major model version, see [Base IO Schema and Benchmark IO Data Year for Major Model Versions](#base-io-schema-and-benchmark-io-data-year-for-major-model-versions) |
+| subset | OPTIONAL. Short name for a satellite or indicator subset or blank if full set is included | string, 3-6 digit, all CAPS |  `GHG` | All resource, emission and waste flow classes found in the most recent version with a complete set of tables|
+
+<sup>1</sup> If `sectors` is a letter, it means the model uses the original BEA sectors associated with the given level; if it is a number, it means model sectors are disaggregated and/or aggregated.
+
+## Base IO Schema and Benchmark IO Data Year for Major Model Versions
+
+The base IO schema is the set of sector codes and names for commodities and industries.
+USEEIO models have used the BEA IO schema, which is updated every 5 years along with the release of the benchmark, detailed level IO tables for the same year.
+USEEIO models alter names for commodities in the schema and may add or remove sectors, and hence the IO schema is used as the base schema for the model but will not necessarily be identical to the model IO schema.
+
+| Major Version | IO Schema | Benchmark IO Data Year |
+|---|---|---|
+| 1 | BEA 2007 | 2007 |
+| 2 | BEA 2012 | 2012 |
 
 ## Examples of model names
 
 | Model Name | Interpretation |
 |---|---|
-| USEEIO v1.3-WASTE       | A national v1.3 model with only the waste satellite tables |
-| USEEIO v2.0i75-2016-WAT | A national v2.0 model in industry form with 75 industries using 2016 IO tables and the water (WAT) satellite table and indicators |
-| GAUSEEIOv2.0            | A GA model (in 2 region form) of the full v2.0 model |
-| USEEIOv2.0is-GHG+       | A national v2.0 model in industry form at the BEA summary level with GHG table and customized GHG indicators (like 20 yr GWP) |
+| USEEIO v1.3.0-WASTE       | A US v1.3.0 detailed level commodity form 1-region model using a 2007 base IO year with only the waste satellite tables |
+| USEEIO v2.0.0-i75-2016-WAT | A US v2.0.0 75-industry form model using 2016 base IO data and the 2012 IO schema with only the water satellite table |
+| GAEEIO v2.1.0-cs-2r        | A Georgia v2.1.0 BEA summary-level commodity model in 2 region form using a 2012 base IO year with all satellite tables and flows|
+| USEEIO v2.0.0-is-GHG+    | A national v2.0.0 model in industry form at the BEA summary level with GHG table and customized GHG indicators (like 20 yr GWP) |
 
-### Rules
+## Rules
 
-1. Models with the same version number (major.minor.update) will use the same data sources, data years (except when IOyear is specified as something else) and currency year.
+1. Models with the same major and minor version number (major.minor) will use the same data sources, data years (except when IOyear is specified as something else) and currency year.
 
-2. Model names do not indicate intended application or release status of models.
-
-### Model IDs
-Technically, any model version will also have a model ID.
-Model IDs will capture information on the complete built models based on a hashing algorithm.
-
-
-
-
-
-
-
-
-