Getting Started with FEDEFL
On this 'Getting Started' page you will find guidance for accessing the FEDEFL, creating project mappings to convert your existing LCA project inventories to match the FEDEFL, and using our online interface to convert your new mapping files to a JSON-LD file for importing into openLCA.
The current FEDEFL release is available on the Federal LCA Commons here:
Simply click “Download” and select the format you prefer. JSON-LD is recommended for use with openLCA. Create a new database in openLCA, selecting ‘Units and flow properties’ under the ‘Database content’ category, then import your JSON_LD file to get started.
The TRACI LCIA method is also available on the Commons mapped and ready to use with the FEDEFL. It can be found here:
To learn more about the Federal LCA Commons click here:
This section provides guidance to users interested in generating a mapping of their own dataset or existing openLCA projects to the FEDEFL. This will enable integration with the current repositories on the Federal LCA Commons that were generated using the FEDEFL.
Mapping Template: The mapping template file simply supplies the column headers required for you to generate a mapping file, which corresponds to the format specifications. As described below in the Preparing Source Data section you will want to start with a UTF-8 encoded CSV and paste these headings into the first row.
Complete list of FEDEFL flows: This file provides all of the flowables and associated contexts in the FEDEFL and corresponds to the flow list format. This list includes CAS numbers and some synonyms for the flowables which can be helpful when mapping. This file also indicates which flowables are 'preferred' as well as which alternate units and conversion factors are available for each flowable. For more details about the flow list, please see the EPA report.
All current mappings: This file provides all of the existing mappings housed within this repository and corresponds to the flow mapping format. This list includes the 'SourceFlowName' and 'SourceFlowContext' entries for various datasets and the corresponding 'TargetFlowName' and 'TargetFlowContext' which can be helpful when mapping. This file also indicates the 'SourceUnit', 'TargetUnit', and any 'ConversionFactor' that may have been used.
All contexts: This file provides all of the available environmental contexts for FEDEFL and corresponds to the flow mapping format. This list includes only the 'TargetFlowContext' names. This file is helpful when determining which contexts to assign for your flows.
To start you will need a list of the elementary flows you wish to map. This may be newly collected data or an existing inventory you wish to convert to be FEDEFL compatible. Flows include the flowable names and their associated environmental context. The EPA report provides detailed definitions for elementary flows and the various flow components which are needed to model them appropriately.
If you already have an openLCA database that you would like to map, you can export the flows using the following python script in openLCA:
import csv
from org.openlca.core.model import FlowType
from org.openlca.core.database import FlowDao
from org.openlca.io import CategoryPath
# => define the path to the CSV file here
CSV_FILE = "C:/Users/ms/Desktop/flows.csv"
with open(CSV_FILE, "wb") as f:
writer = csv.writer(f)
writer.writerow(["UUID", "Name", "Category", "CAS", "Formula",
"Ref.Unit", "Ref.Quantity"])
dao = FlowDao(db)
for flow in dao.getAll():
if flow.flowType != FlowType.ELEMENTARY_FLOW:
continue
cat = CategoryPath.getFull(flow.category)
refq = flow.referenceFlowProperty
refu = refq.unitGroup.referenceUnit
writer.writerow([flow.refId, flow.name, cat, flow.casNumber,
flow.formula, refu.name, refq.name])
You can specify the file path where you would like to save the output from openLCA.
Once you have the data for which you want to create a mapping, follow these steps:
- Create a UTF-8 encoded CSV file using Excel or other appropriate software. To do this in Excel, open a new workbook, select "Save As", and pick the "CSV UTF-8" file type option, using whatever file name you prefer. This encoding will help ensure that formatting and special characters are properly retained while you work with the file.
- Utilizing the mapping template hosted on this GitHub repository, copy all of the column headings into the first row of your workbook. This is the standard layout for FEDEFL mapping files.
- Paste in your 'Source' data using the appropriate fields. Your list being mapped is the ‘Source’, while the FEDEFL names are always the ‘Target’.
- The flowables must conform to the definition provided in the EPA Report, which also provides details the criteria for preferred flowables.
- Download the FedElemFlowList_1.x.x.x_all.xlsx and All_Mappings.xlsx, which are described above in Resources for Mapping.
- You must then go through the process of identifying the appropriate FEDEFL 'TargetFlowName' entries which match the 'SourceFlowName' entries you added to your template in the pre-formatting steps. The FEDEFL and All_Mappings CSVs will ensure you are using mappings that have been developed and verified by FEDEFL maintainers.
If using excel, we recommend using an Index/Match formula across the files to generate the appropriate mappings in your 'TargetFlowName' based on your 'SourceFlowName' column.
=INDEX('TargetFlowName' array in resource files,MATCH('SourceFlowName' entry in mapping template,'SourceFlowName'array in resource files,0))
Example formula in cell H2 for 'TargetFlowName' in the template:
=INDEX('All_Mappings.xlsx'!$H:$H,MATCH(B2,'All_Mappings.xlsx'!$B:$B,0))
This formula can be applied to the whole list to generate as many mappings as possible, simplifying the process. If you have CAS numbers in your source data you can put them in an additional column in the mapping template and do a match to the FEDEFL file using the CAS numbers.
- In some cases you may not find a match using existing mappings. In these cases we recommend checking the following references to identify the CAS or any synonyms that may be associated with your 'SourceFlowName':
If you were able to identify a synonym or CAS you can check the FEDEFL CSV again to identify the appropriate 'TargetFlowName'.
The 'MatchCondition' field does not impact the automated JSON generation, but can be helpful to record relationships between the 'SourceFlowName' and 'TargetFlowName'. The Flow Mapping format guidance provides standard signs used for this field.
- Using your template and the resources you have downloaded you must now go match the appropriate FEDEFL 'TargetFlowContext' entries to the 'SourceFlowContext' records you added to your template in the pre-formatting steps.
You will want to make a list of each unique 'SourceFlowContext' entry and create matches to the appropriate FEDEFL 'TargetFlowContext', referencing the All Contexts resource file.
Once you have your list you can add the mappings to the 'TargetFlowContext' column of your mapping file.
You will want to check contexts carefully if the 'SourceFlowContext' is unspecified or limited to the primary contexts (air, ground, water). In some cases 'SourceFlowNames' may contain information relevant to the mapping of the context, for example:
Gas, natural, in ground which would map to the 'TargetFlowContext' resource/air/subterranean
or
Water, river which would map to the 'TargetFlowContext' resource/water/fresh water body/river
You can use a similar Index/Match formula to generate the appropriate mappings for your 'TargetUnit' column based on your 'SourceFlowName' column.
=INDEX('TargetUnit' array in resource files,MATCH('TargetFlowName' entry in mapping template,'TargetFlowName'array in resource files,0))
Example formula in cell K2 for 'TargetUnit' in the template:
=INDEX('All_Mappings.xlsx'!$K:$K,MATCH(B2,'All_Mappings.xlsx'!$H:$H,0))
This formula can be applied to the whole list to generate as many mappings as possible, simplifying the process. You can also reference the full list of FEDEFL flows to verify the 'TargetUnit' or to identify any alternate units. If your 'SourceUnit' does not match the 'TargetUnit' but is listed as an alternate unit in the FEDEFL, a conversion value will automatically be applied to your mapping during the generation of the JSON file.
If left blank, the 'ConversionFactor' field is assumed to be 1, meaning that the source flow and target flow are in the same units and quantity.
The remaining fields are not required for your mapping file:
- 'SourceList': Can be used to record a name for your source data
- 'SourceFlowUUID': Can be used to record the UUID from your source data if applicable
- 'Mapper': Can be used to record the name of the person who mapped the flow
- 'Verifyer': Can be used to record the name of the person verifying the flow mapping
- 'LastUpdated': Can be used to record the date that the mapping was generated
'TargetFlowUUID' should not be filled out, this will be generated during the creation of your JSON file.
The FEDEFL uses a jupyter notebook (https://jupyter.org/) and binder (https://mybinder.org/) interface to enable users to interact with the python code without needing a local developer environment. Users can use this interface to generate a personalized JSON mapping file for use in openLCA from their mapping files.
Go Here to launch the Run Mappings binder to initiate ‘run_mappings.ipynb’. This notebook will allow you to:
- Upload a csv mapping file
- Automatically add universally unique identifiers (UUIDs) from the latest version of FEDEFL to your mapping file based on the 'TargetFlowName', 'TargetFlowContext', and 'TargetUnit'
- Generate a JSON file for downloading which can be used to integrate your newly mapped dataset with an openLCA database.
Upon launching the binder, the mybinder interface will generate the connection to the jupyter notebook. To run the notebook, select the first cell with code and click Run.
This will generate an upload button. Upload your mapped CSV file that conforms to the mapping template prior to proceeding.
In sequence, select the next two cells and click run. The resulting JSON file can be downloaded.
Once your JSON file is downloaded you will be able to utilize the flow mapping feature in openLCA to link your previous flows ("SourceFlowName") to your newly created FEDEFL flow mappings in your openLCA databases. This will allow you to use the currently available Federal LCA Commons resources that have been built using the FEDEFL.