Package: ecoinvent-interface
ecoinvent_interfaceThis is anunofficial and unsupportedPython library to get ecoinvent data.Quickstartfromecoinvent_interfaceimportSettings,EcoinventRelease,ReleaseTypemy_settings=Settings(username="John.Doe",password="example")release=EcoinventRelease(my_settings)release.list_versions()>>>['3.9.1','3.9','3.8','3.7.1',...]release.list_system_models('3.7.1')>>>['cutoff','consequential','apos']release.get_release(version='3.7.1',system_model='apos',release_type=ReleaseType.ecospold)>>>PosixPath('/Users/JohnDoe/Library/Application Support/''EcoinventRelease/cache/ecoinvent 3.7.1_apos_ecoSpold02')The ecospold files are downloaded and extracted automatically.UsageAuthentication viaSettingsobjectAuthentication is done via theSettingsobject. Accessing ecoinvent requires supplying a username and password.Note that youmust acceptthe ecoinvent license and personal identifying information agreement on the website before using your user account via this library.You can provide credentials in three ways:Manually, via arguments to theSettingsobject instantiation:fromecoinvent_interfaceimportSettingsmy_settings=Settings(username="bob",password="example")Via theEI_PASSWORDandEI_USERNAMEenvironment variablesexportEI_USERNAME=bobexportEI_PASSWORD=exampleIf your environment variable values have special characters, using single quotes should work, e.g.export EI_PASSWORD='compl\!cat$d'.Followed by:fromecoinvent_interfaceimportSettings# Environment variables read automaticallymy_settings=Settings()Or with the use of apydantic_settings secrets directory. The easiest way to create the correct files is via the utility functionpermanent_setting:fromecoinvent_interfaceimportSettings,permanent_settingpermanent_setting("username","bob")permanent_setting("password","example")# Secrets files read automaticallymy_settings=Settings()Secrets files are stored inecoinvent_interface.storage.secrets_dir.For each value, manually set values alwaystake precedenceover environment variables, which in turntake precendenceover secrets files.A reasonable guide for choosing between the three is to use secrets on your private, local machine, and to use environment variables on servers or containers.EcoinventReleaseinterfaceTo interact with the ecoinvent website, instantiateEcoinventRelease.fromecoinvent_interfaceimportEcoinventRelease,Settingsmy_settings=Settings()ei=EcoinventRelease(my_settings)Database releasesTo get a database release, we need to make three selections. First, the version:ei.list_versions()>>>['3.9.1','3.9','3.8','3.7.1',...]Second, the system model:ei.list_system_models('3.7.1')>>>['cutoff','consequential','apos']The ecoinvent API uses a short and long form of the system model names; you can get the longer names by passingtranslate=False. You can use either form in allEcoinventReleasemethods.ei.list_system_models('3.7.1',translate=False)>>>['Allocation cut-off by classification','Substitution, consequential, long-term','Allocation at the Point of Substitution']Finally, the type of release. These are stored in anEnum. There are six release types; if you just want the database to do calculations choose theecospoldtype.ReleaseType.ecospold: The single-output unit process files in ecospold2 XML formatReleaseType.matrix: The so-called "universal matrix export"ReleaseType.lci: LCI data in ecospold2 XML formatReleaseType.lcia: LCIA data in ecospold2 XML formatReleaseType.cumulative_lci: LCI data in ExcelReleaseType.cumulative_lcia: LCIA data in ExcelSee the ecoinvent website for more information on what these values mean.Once we have made a selection for all three choices, we can get the release files. They are saved to a cache directory and extracted by default.ei.get_release(version='3.7.1',system_model='apos',release_type=ReleaseType.matrix)>>>PosixPath('/Users/JohnDoe/Library/Application Support/''EcoinventRelease/cache/universal_matrix_export_3.7.1_apos')The default cache usesplatformdirs, and the directory location is OS-dependent. You can use a custom cache directory with by specifyingoutput_dirwhen creating theSettingsclass instance.You can work with the cache when offline:cs=CachedStorage()list(cs.catalogue)>>>['ecoinvent 3.7.1_LCIA_implementation.7z']cs.catalogue['ecoinvent 3.7.1_LCIA_implementation.7z']>>>{'path':'/Users/<your username>/Library/Application Support/''EcoinventRelease/cache/ecoinvent 3.7.1_LCIA_implementation','extracted':True,'created':'2023-09-03T20:23:57.186519'}EcoinventReleaseextrafilesThere are two other kinds of files available:reports, and what we callextrafiles. Let's see theextrafiles for version'3.7.1':ei.list_extra_files('3.7.1')>>>{'ecoinvent 3.7.1_LCIA_implementation.7z':{'uuid':...,'size':...,'modified':datetime.datetime(2023,4,25,0,0)},...}This returns a dictionary of filenames and metadata. We can download theecoinvent 3.7.1_LCIA_implementation.7zfile; by default it will automatically be extracted.ei.get_extra(version='3.7.1',filename='ecoinvent 3.7.1_LCIA_implementation.7z')>>>PosixPath('/Users/<your username>/Library/Application Support''/EcoinventRelease/cache/ecoinvent 3.7.1_LCIA_implementation')EcoinventReleasereportsReports require a login but not a version number:ei.list_report_files()>>>{'Allocation, cut-off, EN15804_documentation.pdf':{'uuid':...,'size':...,'modified':datetime.datetime(2021,10,1,0,0),'description':('This document provides a documentation on the calculation ''of the indicators in the “Allocation, cut-off, EN15804” ''system model.')}}Downloading follows the same pattern as before:ei.get_report('Allocation, cut-off, EN15804_documentation.pdf')>>>PosixPath('/Users/<your username>/Library/Application Support/EcoinventRelease/cache/Allocation, cut-off, EN15804_documentation.pdf')Zip and 7z files are extracted by default.EcoinventProcessinterfaceThis class gets data and reports for specific processes. It first needs to know what release version and system model to work with:fromecoinvent_interfaceimportEcoinventProcess,Settingsmy_settings=Settings()ep=EcoinventProcess(my_settings)ep.set_release(version="3.7.1",system_model="apos")Finding a dataset idThe ecoinvent API uses integer indices, and these values aren't found in the release values. We have cached these indices for versions3.7.1,3.8, and3.9.1. If you already know the integer index, you can use that:ep.select_process(dataset_id="1")You can also use the filename, if you know it:F="b0eb27dd-b87f-4ae9-9f69-57d811443a30_66c93e71-f32b-4591-901c-55395db5c132.spold"ep.select_process(filename=F)ep.dataset_id>>>"1"Finally, you can pass in a set ofattributes. You should use the name, reference product, and/or location to uniquely identify a process. You don't need to give all attributes, but will get an error if the attributes aren't specific enough.attributesis a dictionary, and can take the following keys:nameoractivity_name,reference productorreference_product, andlocationorgeography. The system will adapt the names as needed to find a match.ep.select_process(attributes={"name":"rye seed production, Swiss integrated production, for sowing","location":"CH","reference product":"rye seed, Swiss integrated production, for sowing",})ep.dataset_id>>>"40"Basic process informationOnce you have selected the process, you can get basic information about that process:ep.get_basic_info()>>>{'index':1,'version':'3.7.1','system_model':'apos','activity_name':'electricity production, nuclear, boiling water reactor','geography':'FI','reference_product':'electricity, high voltage','has_access':True}You can also callep.get_documentation()to get a representation of the ecospold2 XML file in Python.Process documentsYou can useep.get_filewith one of the following file types to download process files:ProcessFileType.upr: Unit Process ecospold XMLProcessFileType.lci: Life Cycle Inventory ecospold XMLProcessFileType.lcia: Life Cycle Impact Assessment ecospold XMLProcessFileType.pdf: PDF Dataset ReportProcessFileType.undefined: Undefined (unlinked and multi-output) Dataset PDF ReportFor example:fromecoinvent_interfaceimportProcessFileTypefrompathlibimportPathep.get_file(file_type=ProcessFileType.lcia,directory=Path.cwd())Would download the life cycle impact assessment ecospold XML file to the current working directory. Theget_filemethod requires specifying thedirectory.Relationship to EIDLThis library initially started as a fork ofEIDL, the ecoinvent downloader. As of version 2.0, it has been completely rewritten. Currently only the authentication code comes fromEIDL.Differences withEIDL:Designed to be a lower-level infrastructure library. All user and web browser interaction was removed.Username and password can be specified usingpydantic_settings.Can download all release files, plus reports and "extra" files.Will autocorrect filenames when possible for ecoinvent inconsistencies.Can download data on inventory processes.Can find inventory processes using their filename or attributes.Uses a more robust caching and cache validation strategy.More reasonable token refresh strategy.No HTML parsing or filename string hacks.Streaming downloads.Descriptive logging and error messages.No shortcuts for Brightway or other LCA software.Custom library headers are set to allow users of this library to be identified. No user information is transmitted.Comprehensive tests.ContributingContributions are very welcome, but please note the following:This library consumes and unpublished an under development APIExtensions of the current API to get process LCI or LCIA data or LCIA scores won't be includedBrightway-specific code won't be includedTo learn more, see theContributor Guide.LicenseDistributed under the terms of theMIT license,ecoinvent_interfaceis free and open source software.IssuesIf you encounter any problems,
pleasefile an issuealong with a detailed description.