Clean up of format specs

-use `` for example values
-replace double with float
-other rewrites, changes

format specs/Contexts.md

@@ -4,13 +4,13 @@ The context input file is in the form of CSV data with the following fields.
 
  Field | Type | Required |  Note |
 ----------- |  ---- | ---------| -----  |
- Directionality | string | Y | defines whether flow is emission or resource |
- Environmental Media | string | Y | environmental compartment emission or resource flows to or from, respectively |
- Vertical Strata | string | N | defines atmospheric or subterranean strata |
- Land Use | string | N | primary use based on human activity or naturally occurring community of flora and fauna in a habitat |
- Human-Dominated | string | N  | primary use categories based on ecologically-dominant human activity |
- Terrestrial | string | N | primary use based on human activity or naturally occurring community of flora and fauna in a habitat |
- Aquatic Feature | string | N | describing different formations of water bodies |
- Indoor | string |  N |  defines if release occurs to air inside of a building or enclosed structure |
- Population Density | string | N | describes the population density of the area of a release. This context can describe air, water or ground emissions |  
- Release Height | string | N | height at which an air release occurs, ground-level is default |
+ Directionality | string | Y | See [FlowablePrimaryContext](FlowablePrimaryContext.md). |
+ Environmental Media | string | Y | See [FlowablePrimaryContext](FlowablePrimaryContext.md). |
+ Vertical Strata | string | N | A secondary context component that defines atmospheric or subterranean strata, like `Troposphere` |
+ Land Use | string | N | A secondary context component that indicates if the land use is human-dominated or a primary terrestrial or aquatic natural use. |
+ Human-Dominated | string | N  |  A secondary context component for naming human-dominated land use type, like `Urban`. Used if Land Use is `Human-Dominated`.|
+ Terrestrial | string | N | A secondary context component that describes various terrestrial habitat types, like `Forest`. Used if Land Use is `Terrestrial`.|
+ Aquatic Feature | string | N | A secondary context component that describes different water body types, like `Lake`. Used if Land Use is a broader water body type like `Fresh Water Body`. |
+ Indoor | string |  N |  A secondary context component that indicates `Indoor` for releases that occur to air inside of a building or enclosed structure. |
+ Population Density | string | N | A secondary context component that describes the population density of the area of an emission or resource, like `Urban`.|  
+ Release Height | string | N | A secondary context component that describes the height at which an air release occurs, like `Ground-level` or `Low` |

format specs/FlowList.md

@@ -4,15 +4,15 @@ A Flow List is in the form of a pandas data frame with the following fields.
 
  Field | Type | Required |  Note |
 ----------- |  ---- | ---------| -----  |
- Flowable | string | Y | the flow name |
+ Flowable | string | Y | The flow name |
  CAS No | string | N | CAS number |
- Formula | string | N | chemical formula|
- Synonyms | string | N | flow synonyms
- Unit | string | Y  | the reference unit. uses olca units |
- Class | string | Y | The flow class, e.g. 'Energy' or 'Chemical' |
- External Reference | string | N | e.g. a web link |
- Preferred | int |  N |   1 for preferred, 0 for non-preferred
- Context | string | Y | A path-like set in the form of directionality/environmental media/environmental compartment... e.g. 'emission/air/tropophere'|  
+ Formula | string | N | Chemical formula|
+ Synonyms | string | N | Flow synonyms
+ Unit | string | Y  | The reference unit. uses [olca-ipc.py](https://github.com/GreenDelta/olca-ipc.py) units |
+ Class | string | Y | The flow class, e.g. `Energy` or `Chemical` |
+ External Reference | string | N | E.g. a web link |
+ Preferred | int |  N |   `1` for preferred, `0` for non-preferred
+ Context | string | Y | A path-like set of context compartments in the form of directionality/environmental media/environmental compartment... e.g. `emission/air/tropophere`|  
  Flow UUID | string | Y | Unique hexadecimal ID for the flow |
  AltUnit | string | N | Alternate unit for the flow |
- AltUnitConversionFactor | double | N | Conversion factor to convert from Unit to AltUnit | 
+ AltUnitConversionFactor | float | N | Conversion factor in the form of alternate units/reference unit | 

format specs/FlowMapping.md

@@ -4,19 +4,19 @@ Flow mapping data is in the form of a pandas dataframe with the following fields
 
 Field |	Type |	Required? | Note |
 ----- | ---- | --------  | ----------- |
-SourceListName | string | Y | Name and version of the source flowlist, e.g. 'openLCA1.7' |
+SourceListName | string | Y | Name and version of the source flowlist, e.g. `openLCA1.7` or `TRACI2.1` |
 SourceFlowName	| string | Y | Name of the source flow |
 SourceFlowUUID	| string | N | If no UUID present, UUID generated based on olca algorithm|
-SourceFlowContext | string | Y | Compartments separated by '/', like 'emission/air'|
-SourceUnit | string | Y | A unit abbreviation, like 'kg', using units from openLCA as a reference |
-MatchCondition | string | N |Single character. '=', '>','<','~'. Meaning 'equal to','a superset of', 'a subset of', 'a proxy for'. Assumes '=' if not present |
-ConversionFactor | double | N |	Value for multiplying with source flow to equal target flow. Assumes 1 if not present |
+SourceFlowContext | string | Y | Compartments separated by `/`, like `emission/air`|
+SourceUnit | string | Y | A unit abbreviation, like `kg`|
+MatchCondition | string | N |Single character. `=`, `>`,`<`,`~`. Meaning 'equal to','a superset of', 'a subset of', 'a proxy for'. Assumes `=` if not present |
+ConversionFactor | float | N |	Value for multiplying with source flow to equal target flow. Assumes `1` if not present |
 TargetFlowName | string | Y | Name of the Fed Commons flowable |
 TargetFlowUUID	| string| Y| UUID for Fed Commons flow |
-TargetFlowContext | string | Y | Fed commons context, in form like 'emission/air' |
-TargetUnit | string | Y | A unit abbreviation, like 'kg', using units from openLCA as a reference |
-Mapper	| string | N	|Person creating the mapping |
-Verifier |	string | N |Person verifying the mapping |
+TargetFlowContext | string | Y | Fed commons context, in form like `emission/air` |
+TargetUnit | string | Y | A unit abbreviation, like `kg`|
+Mapper	| string | N	| Person creating the mapping |
+Verifier |	string | N | Person verifying the mapping |
 LastUpdated | datetime | N | Date mapping last updated |
 
 Note that TargetList is not present, because the Fed LCA Commons Elementary Flow List

format specs/FlowableAltUnits.md

@@ -4,8 +4,8 @@ The flowable alternate units input files are in the form of CSV data with the fo
 
  Field | Type | Required |  Note |
 ----------- |  ---- | ---------| -----  |
- Flowable | string | Y | the flowable name |
- Alternate Unit | string | Y | unit of measure, different than the preferred unit |
- Reference Unit | string | Y | unit of measure, original preferred unit |
- Conversion Factor | float | Y | factor for conversion from reference unit to alternate unit |
- External Reference | string | Y | description or link to reference for conversion values |
+ Flowable | string | Y | The flowable name |
+ Alternate Unit | string | Y | Unit of measure, different than the preferred unit |
+ Reference Unit | string | Y | Unit of measure, original preferred unit |
+ Conversion Factor | float | Y | Factor for unit conversion, in the form of alternate units/reference unit|
+ External Reference | string | Y | Description or link to reference for conversion values |

format specs/FlowablePrimaryContexts.md

@@ -4,6 +4,6 @@ Flowable primary context input files are the form of CSV data with the following
 
  Field | Type | Required |  Note |
 ----------- |  ---- | ---------| -----  |
- Flowable | string | Y | the flowable name |
- Directionality | string | Y | defines whether flow is emission or resource |
- Environmental Media | string | Y | environmental compartment emission or resource flows to or from, respectively |
+ Flowable | string | Y | The flowable name |
+ Directionality | string | Y | A primary context component indicating direction of flow. Currently `emission` or `resource` |
+ Environmental Media | string | Y | A primary context component indicating primary environmental compartment that is origin or destination of the flow. Currently `air`, `ground`, `water`, or `biotic` |

format specs/Flowables.md

@@ -4,10 +4,10 @@ Flowable input files are the form of CSV data with the following fields.
 
  Field | Type | Required |  Note |
 ----------- |  ---- | ---------| -----  |
- Flowable | string | Y | the flowable name |
+ Flowable | string | Y | The flowable name |
  CAS No | string | N | CAS number |
- Formula | string | N | chemical formula |
- Synonyms | string | N | flow synonyms |
- Unit | string | Y  | the reference unit. uses olca units |
- External Reference | string | N | description or link to reference for conversion values |
- Flowable Preferred | int | Y | 1 for preferred, 0 for non-preferred |
+ Formula | string | N | Chemical formula |
+ Synonyms | string | N | Flow synonyms |
+ Unit | string | Y  | The reference unit. Uses [olca-ipc.py](https://github.com/GreenDelta/olca-ipc.py) units |
+ External Reference | string | N | Description or link to definition of flowable |
+ Flowable Preferred | int | Y | Indicates whether or not flowable is preferred. `1` for preferred, `0` for non-preferred |

format specs/README.md

@@ -0,0 +1,6 @@
+Format specifications for input files, [Flowables](Flowables.md), [FlowablePrimaryContexts](FlowablePrimaryContexts.md),
+[FlowableAltUnits](FlowableAltUnits.md), [Contexts](Contexts.md), and [SecondaryContextMembership](SecondaryContextMembership.md)
+ as well as the formats provided and used by `fedelemflowlist`, [FlowList](FlowList.md) and [FlowMapping](FlowMapping.md).
+  See the EPA report linked to in the main [README](https://github.com/USEPA/Federal-LCA-Commons-Elementary-Flow-List/)
+   for an explanation of the purpose the files using these formats.   
+

format specs/SecondaryContextMembership.md

@@ -1,18 +1,21 @@
 ## Secondary Context Membership Input File Format
 
-The secondary context membership input file is in the form of CSV data with the following fields. Binary entries indicate possible compartment combinations resulting in unique contexts.
-
+The secondary context membership input file is in the form of CSV data with the following fields. 
+ 
  Field | Type | Required |  Note |
 ----------- |  ---- | ---------| -----  |
- FlowClass | string | Y | the flow name |
- Directionality | string | Y | defines whether flow is emission or resource |
- Environmental Media | string | Y | environmental compartment emission or resource flows to or from, respectively |
- Vertical Strata | int | Y | defines atmospheric or subterranean strata |
- Land Use | int | Y | primary use based on human activity or naturally occurring community of flora and fauna in a habitat |
- Human-Dominated | int | Y  | primary use categories based on ecologically-dominant human activity |
- Terrestrial | int | Y | primary use based on human activity or naturally occurring community of flora and fauna in a habitat |
- Aquatic Feature | int | Y | describing different formations of water bodies |
- Indoor | int |  Y |  defines if release occurs to air inside of a building or enclosed structure |
- Population Density | int | Y | describes the population density of the area of a release. This context can describe air, water or ground emissions |  
- Release Height | int | Y | height at which an air release occurs, ground-level is default |
- ContextPreferred | int | Y | 1 for preferred, 0 for non-preferred |
+ FlowClass | string | Y | The flow class. See [FlowList](FlowList.md). |
+ Directionality | string | Y |  A primary context compartment. See [FlowablePrimaryContext](FlowablePrimaryContext.md) |
+ Environmental Media | string | Y | A primary context compartment.  See [FlowablePrimaryContext](FlowablePrimaryContext.md) |
+ Vertical Strata | int | Y | `1` for included and `0` for excluded. See note.  |
+ Land Use | int | Y | `1` for included and `0` for excluded. See note. |
+ Human-Dominated | int | Y  | `1` for included and `0` for excluded. See note. |
+ Terrestrial | int | Y | `1` for included and `0` for excluded. See note. |
+ Aquatic Feature | int | Y | `1` for included and `0` for excluded. See note. |
+ Indoor | int |  Y |  `1` for included and `0` for excluded. See note. |
+ Population Density | int | Y | `1` for included and `0` for excluded. See note. |  
+ Release Height | int | Y | `1` for included and `0` for excluded. See note. |
+ ContextPreferred | int | Y | `1` for included and `0` for excluded. See note. |
+
+Note: Indicates whether or not contexts with compartment of this class (see [Contexts](Contexts.md) for class definitions)
+ should be associated with flows from this FlowClass and primary contexts (Directionality and Environmental Media).