BibData

BibData is a tool developed to centralise the references and the use of data such as model parameters.

The idea is to collect and retrieve values across a bibliography, that can be shared among various users. The idea is to use the Notes option in bibliography manager softwares. The two that have been tested as compatible are Zotero and Mendeley.

The package then provides an easy way to extract custom data set in the annote or note field of a bib file, and can be used in Python or in Quarto, using rbibdata chunk.

The basics

The package is designed to extract data in a specific format in the notes field of the .bib file. Each position in the note has a meaning, according to the following format:

+- ENTRY # row_key:set: general description of entry # confidence = 0.4 # ref_year = 1975
param1 = min:value1:max [unit1] # short_name: a comment about the param and its value
param2 = value2 [unit2] # # confidence = 0.4
+- /ENTRY

Where the fields described as follows:

Fields	Description	Mandatory
ENTRY	The name of the entry to which the parameters belong	True
row_key	An identifier	False
set	Use to retrieve all values from a user (e.g. all values for scenario_oil)	False
general_description	A comment on the entry or on the paper	False
param	Name of the parameter characterised	False
value	Value of the parameter	True
min	Minimal value that the parameter can have	False
max	Maximal value that the parameter can have	False
unit	Unit of the parameter	True
confidence	The level of confidence in the value (useful for average). Can be precised for a technology or a parameter. The value from the parameter overwrites the one from the technology	False
ref_year	The reference year for the values, in case they have to be actualised. If not precised, the publication date is used	False

The minimal information to provide is the +- ENTRY   +- /ENTRY. The fields after the # are optional, as well as the min and max values.

Note

Spaces in the key/value line are for readability but are not required.

To be able to read all those notes at once, one must export the bibliography collection, either in Better BibTeX or in BibTeX. In the last case, the line breaks one must be added directly in the note as such:

+- ENTRY # row_key:set: general description of tech # confidence = 0.4 \n
param1 = min:value1:max [unit1] # short_name: a comment about the param and its value \n
param2 = value2 [unit2] # # confidence = 0.4 \n
+- /ENTRY

Additional format

For some models, such as _Energyscope_, one needs to add also values for layers. In that case, the keyword layer should be added in the parameter field. Again, spaces are for readility and special characters can be added without hindering the parsing.

+- TECH # row_key:set: general description of tech # confidence = 0.4 # ref_year = 1975
Layer: param1 = min:value1:max [unit1] # short_name: a comment about the param and its value
layer_param2 = value2 [unit2] # # confidence = 0.4
+- /TECH

Energyscope also has demands and resources. Of course, they can also be reported using the package, following this format for a proper export of the data.

• Demands

  +- Demand % SECTOR # row_key:set: general description of tech # confidence = 0.4 # ref_year = 1975
  end_use_category1 = min:value1:max [unit1] # short_name: a comment about the param and its value
  end_use_category2 = value2 [unit2] # # confidence = 0.4
  +- /SECTOR
  

  For instance:

  +- Demand % INDUSTRY
  ELECTRICITY_MV = 30 [GWh]
  HEAT_HIGH_T = 60 [GWh]
  +- /INDUSTRY
  

• Resources

  +- RESOURCE # row_key:set: general description of tech # confidence = 0.4 # ref_year = 1975
  param1 = min:value1:max [unit1] # short_name: a comment about the param and its value
  param2 = value2 [unit2] # # confidence = 0.4
  +- /RESOURCE
  

  For instance:

  +- BIOGAS
  c_op = 20 [USD/GWh]
  +-/BIOGAS
  

To help to format properly the note, an interface has been developed that connects to Zotero and writes the note with the correct formatting. The interface is not online but can be found on Git bibdatamanagement_ui and run locally. This interface is related to EnergyScope but could be adapted to any type of note.

Use the data in code

With the data correctly referenced in a bibliography, in their notes, with the formatting above, the .bib file must be exported and read in code.

For Python users

Describes the Python package.

For Quarto users

Describes the R library, useful for reporting.

Contribute

All contributions are welcome in this project. The users may find some additional features are needed and propose or even implement them.

All suggestions or implementation must be tracked with dedicated issues and reported at the project GitHub