Package: elmada
elmada: Dynamic electricity carbon emission factors and prices for EuropeThe open-source Python packageelmadaprovides electricity carbon emission factors and wholesale prices for European countries.
The target group includes modelers of distributed energy hubs who needelectricitymarketdata (short:elmada), e.g., to evaluate the environmental effect of demand response.elmadais part of theDraf Projectbut can be used as a standalone package.FeaturesCarbon emission factors (CEF)are calculated depending on country and year in up to quarter-hourly resolution.
You can choose betweengrid mix emission factors (XEFs) from fuel type-specificENTSO-Eelectricity generation data (method="XEF_EP")and approximations using merit order based simulations which allow also for the calculation of marginal emission factors (MEFs).
The according Power Plant method (PP) and Piecewise Linear method (PWL) are described inthis open-access Applied Energy paper.
The data used depends on the method chosen, seescheme below.Wholesale electricity pricesare provided for European countries. You can choose between the real historicalENTSO-Edata or the simulation results of thePP/PWLmethod.Other interesting market data such as merit order lists, fuel-specific generation data, or power plant lists are provided as a by-product of the CEF calculations.MethodologyWith theXEF_EPmethod, XEFs are calculated by multiplying the share matrixS(fuel type specific share of electricity generation per time step fromENTSO-E) with the intensity vectorε(fuel type specific life cycle carbon emission intensities fromTranberg.2019):The methodsPP,PWL, andPWLvare explained inthis Applied Energy paper. Here is an overview:DataGeographic scopeInelmada, two-letter country codes (ISO 3166-1 alpha-2) are used.The countries supported byelmadacan be seen in the map below which is the output ofelmada.plots.cef_country_map(year=2020, method="XEF_EP").In theUsage sectionthey are referred to as Europe30.
They include:20 countries analyzed in theApplied Energy paper: AT, BE, CZ, DE, DK, ES, FI, FR, GB, GR, HU, IE, IT, LT, NL, PL, PT, RO, RS, SI8 countries with onlyone reported fossil fuel type: BA, CH, EE, LV, ME, MK, NO, SE2 countries where installed generation capacity data for 2019 were only available after the publication of theApplied Energy paper: BG, SKData modesYou can useelmadain two data modes which can be set withelmada.set_mode(mode=<MODE>):mode="safe"(default):Pre-cached data for 4 years and 20 countries are used. The data are described in theApplied Energy paper.The years are 2017 to 2020 and the countries AT, BE, CZ, DE, DK, ES, FI, FR, GB, GR, HU, IE, IT, LT, NL, PL, PT, RO, RS, SI.The data is available in the space-saving and quick-to-readParquet formatunder.../safe_cache.mode="live":Up-to-date data are retrieved on demand and are cached to an OS-specific directory, seeelmada.paths.CACHE_DIR. A symbolic link to it can be conveniently created by executingelmada.make_symlink_to_cache().Available years are 2017 until the present.Slow due to API requests.Requires valid API keys of ENTSO-E, Morph, Quandl, seetable below.Data sourcesDescriptionLocal data locationSourceChannelInvolved inGeneration time series & installed generation capacities.../safe_cacheorCACHE_DIRENTSO-E🔌 on-demand-retrieval viaEntsoePandasClient(requires validENTSO-E API key)CEFs viaEP,PP,PWL,PWLvCarbon prices (EUA).../safe_cacheorCACHE_DIRSandbag&ICE🔌 on-demand-retrieval viaQuandl(requires validQuandl API key)CEFs viaPP,PWL,PWLvShare of CCGT among gas power plants.../safe_cacheorCACHE_DIRGEO🔌 on-demand-download viaMorph(requires validMorph API key)CEFs viaPWL,PWLv(Average) fossil power plants sizes.../safe_cacheorCACHE_DIRGEO🔌 on-demand-scraping viaBeautifulSoup4CEFs viaPWL,PWLvGerman fossil power plant list with efficiencies.../safe_cacheorCACHE_DIROPSD🔌 on-demand-download fromhereCEFs viaPP,PWL,PWLvTransmission & distribution losses.../worldbankWorldbank💾 manual download fromhereCEFs viaPP,PWL,PWLvFuel prices for 2015 (+ trends).../from_other.py(+.../destatis)Konstantin.2017(+DESTATIS)🔢 hard-coded values (+ 💾 manual download fromhere)CEFs viaPP,PWL,PWLvFuel type-specific carbon emission intensities.../from_other.py&.../tranbergQuaschning&Tranberg.2019🔢 hard-coded valuesCEFs viaEP,PP,PWL,PWLvTime zonesThe data is in local time since theDraf Projectfocuses on the modeling of individual energy hubs.
Standard time is used i.e. daylight saving time is ignored.
Also seethis tableof the time zones used.InstallationUsingpippython-mpipinstallelmadaNOTE: Readherewhy you should usepython -m pipinstead ofpip.From source using condaFor a conda environment including a full editableelmadaversion do the following steps.Clone the source repository:gitclonehttps://github.com/DrafProject/elmada.gitcdelmadaCreate an conda environment based onenvironment.ymland install an editable localelmadaversion:condaenvcreateActivate the environment:condaactivateelmadaFrom source without using condaFor Unixgitclonehttps://github.com/DrafProject/elmada.gitcdelmada
python3-mvenvenvsourceenv/bin/activate
python-mpipinstall-e.[dev]For Windowsgitclonehttps://github.com/DrafProject/elmada.gitcdelmada
py-mvenvenv
.\env\Scripts\activate
py-mpipinstall-e.[dev]TestsThis should always work:pytest-m="not apikey"This works only if API keys are set as describedbelow:pytestUsageimportelmadaOPTIONAL: Set your API keys and go live modeelmada.set_api_keys(entsoe="YOUR_ENTSOE_KEY",morph="YOUR_MORPH_KEY",quandl="YOUR_QUANDL_KEY")# NOTE: API keys are stored in an OS-dependent config directory for later use.elmada.set_mode("live")Carbon Emission factorselmada.get_emissions(year=2019,country="DE",method="MEF_PWL",freq="60min",use_datetime=True)... returns marginal emission factors calculated by thePWLmethod with hourly datetime index:2019-01-0100:00:00990.1034922019-01-0101:00:00959.758367...2019-12-3122:00:001064.1221462019-12-3123:00:001049.852079
Freq:60T,Name:MEFs,Length:8760,dtype:float64Themethodargument ofget_emissions()takes strings that consists of two parts seperated by an underscore.
The first part is the type of emission factor: grid mix emission factors (XEF) or marginal emission factors (MEF).
The second part determines the calculation method: power plant method (PP), piecewise linear method (PWL),  or piecewise linear method in validation mode (PWLv).The first part can be omitted (_PP,_PWL,_PWLv) to return a DataFrame that includes additional information.elmada.get_emissions(year=2019,country="DE",method="_PWL")... returns all output from the PWL method:residual_loadtotal_loadmarginal_fuelefficiencymarginal_costMEFsXEFs021115.0051609.75lignite0.37843240.889230990.103492204.730151118919.5051154.50lignite0.39039739.636039959.758367164.716687
........................875827116.0041652.00lignite0.35210943.9460471064.122146388.542911875925437.7539262.75lignite0.35689543.3567231049.852079376.009477[8760rowsx7columns]Additionally, XEFs can be calculated from historic fuel type-specific generation data (XEF_EP).Here is an overview of validmethodargument values:methodReturn typeReturn valuesRestrictionXEF_PPSeriesXEFs using PP methodDEXEF_PWLSeriesXEFs using PWL methodEurope30XEF_PWLvSeriesXEFs using PWLv methodDEMEF_PPSeriesMEFs from PP methodDEMEF_PWLSeriesMEFs using PWL methodEurope30MEF_PWLvSeriesMEFs using PWLv methodDE_PPDataframeextended data for PP methodDE_PWLDataframeextended data for PWL methodEurope30_PWLvDataframeextended data for PWLv methodDEXEF_EPSeriesXEFs using fuel type-specific generation data fromENTSO-EEurope30You can plot the carbon emission factors withelmada.plots.cefs_scatter(year=2019,country="DE",method="MEF_PP")Wholesale priceselmada.get_prices(year=2019,country="DE",method="hist_EP")028.32110.07...875838.88875937.39
Length:8760,dtype:float64Possible values for themethodargument ofget_prices()are:methodDescriptionRestrictionPPUsing the power plant methodDEPWLUsing piecewise linear methodEurope30PWLvUsing piecewise linear method in validation modeDEhist_EPUsing historicENTSO-EdataEurope30without BA, ME, MKhist_SMUsing historicSmarddataused only as backup for DE, 2015 and 2018Merit orderelmada.plots.merit_order(year=2019,country="DE",method="PP")... plots the merit order:elmada.get_merit_order(year=2019,country="DE",method="PP")... returns the merit order as DataFrame with detailed information on individual power plant blocks.Pre-processed dataThe following table describes additionalelmadafunctions that provide pre-processed data.
Keyword arguments are for examplekw = dict(year=2019, freq="60min", country="DE").elmada.function callReturn type (Dimensions)Return valueUsage inelmadaUsed withinget_el_national_generation(**kw)DataFrame (time, fuel type)National electricity generationShare matrixSXEF_EPmethodget_el_national_generation(**kw).sum(axis=1)Series (time)Total national electricity generationProxy for the total loadXEFs calculationsget_residual_load(**kw)Series (time)Conventional national generationProxy for the residual load (seescheme above)PP,PWLandPWLvContributingContributions in any form are welcome! To contribute changes, please have a look at ourcontributing guidelines.In short:Fork the project and create a feature branch to work on in your fork (git checkout -b new-feature).Commit your changes to the feature branch and push the branch to GitHub (git push origin my-new-feature).On GitHub, create a new pull request from the feature branch.Citing elmadaIf you useelmadafor academic work please citethis open-access paperpublished in Applied Energy in 2021.LicenseCopyright (c) 2021 Markus FleschutzTHE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.