Standardise column names in the documentation (#768)

* Standardise column names in the documentation

* Update example models

* Fix unit tests and small changes to documentation

* Update tutorial models

* Update notebooks

* Update release notes

* Update error messages

Author: tsmbland

docs/advanced-guide/extending-muse.ipynb

@@ -665,7 +665,7 @@
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "Python 3.8.2 ('.venv': venv)",
+   "display_name": "muse_env",
    "language": "python",
    "name": "python3"
   },
@@ -679,12 +679,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.12.4"
-  },
-  "vscode": {
-   "interpreter": {
-    "hash": "bef583514e26a7e735428d308331ee3372c412f577c9d62d7c3154d972034ba3"
-   }
+   "version": "3.12.11"
   }
  },
  "nbformat": 4,

docs/inputs/agents.rst

@@ -10,7 +10,7 @@ one agent per row, using a format meant specifically for retrofit and new-capaci
 For instance, we have the following CSV table:
 
 .. csv-table::
-   :header: Name, Type, AgentShare, RegionName, Objective1, SearchRule, DecisionMethod, ...
+   :header: name, type, agent_share, region, objective1, search_rule, decision_method, ...
 
    A1, New, Agent1New, ASEAN, EAC, all->maturity, epsilonCon, ...
    A2, New, Agent2New, ASEAN, CapitalCosts, all->spend_limit, weightedSum, ...
@@ -23,35 +23,35 @@ The columns have the following meaning:
 
 .. _name:
 
-``Name``
+``name``
    Name shared by a retrofit and new-capacity agent pair.
 
-``Type``
+``type``
    One of **New** or **Retrofit**. **New** and **Retrofit** agents make up a pair with a given
-   :ref:`name <Name>`. The demand is split into two, with one part coming from
+   :ref:`name <name>`. The demand is split into two, with one part coming from
    decommissioned assets, and the other coming from everything else. "Retrofit" agents
    invest only to make up for decommissioned assets. They are often limited in the
-   technologies they can consider (by :ref:`SearchRule <SearchRule>`). **New** agents
+   technologies they can consider (by :ref:`search_rule <search_rule>`). **New** agents
    invest on the rest of the demand, and can often consider more general sets of
    technologies. If only **New** agents are included, they will also invest to make up for
    decommissioned assets, but the end mix might be different than using a specialised
    **Retrofit** agent for that.
    **Note: Retrofit agents will be deprecated in a future release.**
 
-``AgentShare``
+``agent_share``
    Name used to assign a fraction of existing capacity to the agent in the :ref:`inputs-technodata` file.
    If using "New" and "Retrofit" agents, you should create a column with the name of each "Retrofit" agent share (e.g. "Agent1Retro", "Agent2Retro" etc.) in the :ref:`inputs-technodata` file,
    with values summing to 1 for each technology.
    If only using "New" agents, you should create a column with the name of each "New" agent share in the :ref:`inputs-technodata` file,
    with values summing to 1 for each technology.
    See documentation for the :ref:`inputs-technodata` file for more details.
 
-``RegionName``
+``region``
    Region where an agent operates.
 
 .. py:currentmodule:: muse.objectives
 
-``Objective1``
+``objective1``
    Objective that an agent will try and maximize or minimize during investment.
    This objective should be one registered with
    :py:func:`@register_objective <register_objective>`. The following objectives are
@@ -91,32 +91,32 @@ The columns have the following meaning:
    - :py:func:`equivalent_annual_cost <equivalent_annual_cost>`: Annualized form of the
      net present value. Aliased to "EAC" for simplicity.
 
-   The weight associated with this objective can be changed using :ref:`ObjData1
-   <ObjData1>`.  Whether the objective should be minimized or maximized depends on
-   :ref:`Objsort1 <Objsort1>`. Multiple objectives are combined using the
-   :ref:`DecisionMethod <DecisionMethod>`
+   The weight associated with this objective can be changed using ``obj_data1``.
+   Whether the objective should be minimized or maximized depends on
+   ``obj_sort1``. Multiple objectives are combined using the
+   :ref:`decision method <decision_method>`
 
 
-``ObjData1``
+``obj_data1``
    A weight associated with the objective.
-   Whether it is used will depend in large part on the :ref:`decision method <DecisionMethod>`.
+   Whether it is used will depend in large part on the :ref:`decision method <decision_method>`.
 
 
-``Objsort1``
+``obj_sort1``
    Determines whether the objective is maximized or minimized.
    This should be set to "True" for minimization and "False" for maximisation.
 
 Additional objectives
    For certain decision methods you can use more than one objective.
-   In this case, additional objectives can be specified with additional columns (e.g. ``Objective2``, ``ObjData2``, ``Objsort2`` etc.)
-   For example, when using the weighted sum decision method, the ``ObjDataX`` column for each objective defines the weight of the objective in the weighted sum calculation.
+   In this case, additional objectives can be specified with additional columns (e.g. ``objective2``, ``obj_data2``, ``obj_sort2`` etc.)
+   For example, when using the weighted sum decision method, the ``obj_dataX`` column for each objective defines the weight of the objective in the weighted sum calculation.
 
 
 .. py:currentmodule:: muse.filters
 
-.. _SearchRule:
+.. _search_rule:
 
-``SearchRule``
+``search_rule``
    The search rule allows users to par down the search space of technologies to those an
    agent is likely to consider.
    The search rule is any function with a given signature, and registered with MUSE via
@@ -146,16 +146,15 @@ Additional objectives
    - :py:func:`maturity <maturity>`: Only allows technologies that have achieved a given
      market share.
 
-   - :py:func:`spend_limit <spend_limit>`: Only allows technologies with a unit capital cost (cap_par in
-      :ref:`inputs-technodata`) lower than the spend limit.
+   - :py:func:`spend_limit <spend_limit>`: Only allows technologies with a unit capital cost (cap_par in :ref:`inputs-technodata`) lower than the spend limit.
 
    Filters can be combined by chaining them with "->". For example, "all->maturity->spend_limit".
 
 .. py:currentmodule:: muse.decisions
 
-.. _DecisionMethod:
+.. _decision_method:
 
-``DecisionMethod``
+``decision_method``
    Decision methods reduce multiple objectives into a single scalar objective per
    replacement technology. They allow combining several objectives into a single metric
    through which replacement technologies can be ranked.
@@ -186,21 +185,21 @@ Additional objectives
    The functions allow for any number of objectives. However, the format described here
    allows only for three.
 
-``Quantity``
+``quantity``
    Represents the fraction of new demand that is assigned to the agent
    (e.g. if 0.2, 20% of new demand in each year will be assigned to the agent).
    Must sum to 1 across all "New" agents.
    When using both "Retrofit" agents and "New" agents, this only applies to the "New" agents.
 
 Additional optional columns
-   Certain columns may also be required when using certain search rules. These are:
+  Certain columns may also be required when using certain search rules. These are:
 
-  ``MaturityThreshold``
-   Only applies when using the :py:func:`maturity <muse.filters.maturity>` search rule.
-   Allows agents to only consider technologies that have achieved a certain market share
-   (e.g. if 0.5, the agent will only invest in technologies that have a current market share of 50% or more).
+  ``maturity_threshold``
+     Only applies when using the :py:func:`maturity <muse.filters.maturity>` search rule.
+     Allows agents to only consider technologies that have achieved a certain market share
+     (e.g. if 0.5, the agent will only invest in technologies that have a current market share of 50% or more).
 
-  ``SpendLimit``
-   Only applies when using the :py:func:`spend_limit <muse.filters.spend_limit>` search rule.
-   Allows agents to only consider technologies with a unit capital cost (`cap_par`) lower than the spend limit.
-   (e.g. if 10, the agent will only invest in technologies with a `cap_par` of 10 or lower, as listed in the :ref:`inputs-technodata` file).
+  ``spend_limit``
+     Only applies when using the :py:func:`spend_limit <muse.filters.spend_limit>` search rule.
+     Allows agents to only consider technologies with a unit capital cost (`cap_par`) lower than the spend limit.
+     (e.g. if 10, the agent will only invest in technologies with a `cap_par` of 10 or lower, as listed in the :ref:`inputs-technodata` file).

docs/inputs/commodities.rst

@@ -9,19 +9,19 @@ represent energy, services, pollutants/emissions. The commodities for the simula
 a whole are defined in a csv file with the following structure.
 
 .. csv-table:: Global commodities
-   :header: CommodityName, Description, CommodityType, Unit
+   :header: commodity, description, commodity_type, unit
 
    hardcoal, Coal, Energy, PJ
    agires, Agricultural-residues, Energy, PJ
 
-``CommodityName``
+``commodity``
    the internal name used for a commodity inside the model (e.g. "heat" or "elec").
    Any references to commodities in other files must use these names.
 
-``Description`` (optional)
+``description`` (optional)
    an extended name/description of a commodity (e.g. "Heating" or "Electricity").
 
-``CommodityType``
+``commodity_type``
    defines the type of a commodity:
 
    The **energy** type includes energy commodities, such as biomass, electricity, gasoline, and hydrogen,
@@ -35,7 +35,7 @@ a whole are defined in a csv file with the following structure.
    The **environmental** type refers to non-energy commodities whichare used to quantify an impact on the environment,
    such as greenhouse gases or CO2. They can be subjected to different types of environmental fees or taxes.
 
-``Unit`` (optional)
+``unit`` (optional)
    is the unit used to represent quantities of the commodity (e.g "PJ").
    This parameter does not need to be included, as it isn't used in the model, but is
    highly recommended for documentation purposes.

docs/inputs/commodities_io.rst

@@ -41,32 +41,32 @@ Below it is shown the generic structure of the input commodity file for the elec
 heater.
 
 .. csv-table:: Commodities used as consumables - Input commodities
-   :header: ProcessName, RegionName, Time, Level, electricity
+   :header: technology, region, year, level, electricity
 
    resBoilerElectric, region1, 2010, fixed, 300
    resBoilerElectric, region1, 2030, fixed, 290
 
 
-``ProcessName``
+``technology``
    represents the technology ID and needs to be consistent across all the data inputs.
 
-``RegionName``
+``region``
    represents the region ID and needs to be consistent across all the data inputs.
 
-``Time``
+``year``
    represents the period of the simulation to which the value applies; it needs to
    contain at least the base year of the simulation.
 
-``Level`` (for **input** commodities only)
-   characterises inputs as either "fixed" or "flexible".
+``level`` (for **input** commodities only)
+   characterises inputs as either **fixed** or **flexible**.
    Fixed inputs are always used by a technology in a fixed proportion.
    Flexible inputs allow a technology to choose amongst several alternative fuels,
    depending on which one is cheapest at the time.
    For example, if a vehicle can use either petrodiesel or biodiesel, these
-   should be specified as "flexible" inputs, and the technology will choose between
+   should be specified as **flexible** inputs, and the technology will choose between
    them based on the price of each.
    If a process has a mix of fixed and flexible inputs, these should be split over two rows.
-   Defaults to "fixed".
+   Defaults to **fixed**.
 
 Commodities (one column per commodity)
    Any further columns represent commodities, with names matching those

docs/inputs/correlation_files.rst

@@ -22,9 +22,9 @@ An example of a shortened macrodriver file is shown below. This file contains th
    :widths: 50 50 50 25 25 25
    :header-rows: 1
 
-   * - Variable
-     - RegionName
-     - Unit
+   * - variable
+     - region
+     - unit
      - 2010
      - 2011
      - ...
@@ -41,13 +41,13 @@ An example of a shortened macrodriver file is shown below. This file contains th
      - 81.82599
      - ...
 
-``Variable``
+``variable``
     This is the variable that you would like to use in the regression for the service demand.
 
-``RegionName``
+``region``
     This is the region that the data applies to. This must correlate with the regions set in the rest of your input files, as well as the toml file.
 
-``Unit``
+``unit``
     This unit can be whatever you like, however they must be consistent across all input files.
 
 Years (one column per year)
@@ -62,17 +62,17 @@ In the regression parameters file, it is necessary to state the parameters of th
 An example file is shown below:
 
 .. csv-table:: Regression Parameters File
-   :header: SectorName,FunctionType,Coeff,RegionName,electricity,gas,heat,CO2f
+   :header: sector,function_type,coeff,region,electricity,gas,heat,CO2f
 
    Residential,logistic-sigmoid,GDPexp,R1,0,0,9.94E-02,0
    Residential,logistic-sigmoid,constant,R1,0,0,0.0000434,0
    Residential,logistic-sigmoid,GDPscaleLess,R1,0,0,753.1068725,0
    Residential,logistic-sigmoid,GDPscaleGreater,R1,0,0,672.9316672,0
 
-``SectorName``
+``sector``
     This is the sector name in which these parameters apply to.
 
-``FunctionType``
+``function_type``
     This is the function type you would like to MUSE to use. MUSE allows these to be:
 
         - Exponential
@@ -85,10 +85,10 @@ An example file is shown below:
 
     Your own functions can be created using the `@register_regression` hook, from the `regressions.py` file.
 
-``Coeff``
+``coeff``
     This is the coefficient for the respective function type. These are explicitly defined within the `regressions.py` file, as they differ between functions.
 
-``RegionName``
+``region``
     This is the region in which these parameters apply to.
 
 Commodities (one column per commodity)
@@ -103,7 +103,7 @@ In this file, you are able to split the energy service proportionally by timesli
 An example file is shown below:
 
 .. csv-table:: Timeslice share
-   :header: SN,RegionName,electricity,gas,heat,CO2f,wind
+   :header: timeslice,region,electricity,gas,heat,CO2f,wind
 
     1,R1,0,0,0.034835,0,0
     2,R1,0,0,0.064546,0,0
@@ -112,10 +112,10 @@ An example file is shown below:
     5,R1,0,0,0.014145,0,0
     6,R1,0,0,0.085783,0,0
 
-``SN``
+``timeslice``
     This is the timeslice index.
 
-``RegionName``
+``region``
     This is the region in question for this data.
 
 Commodities (one column per commodity)

docs/inputs/existing_capacity.rst

@@ -12,16 +12,16 @@ follow the structure reported in the table.
 
 
 .. csv-table:: Existing capacity of technologies: the residential boiler example
-   :header: ProcessName, RegionName, 2010, 2020, 2030, 2040, 2050
+   :header: technology, region, 2010, 2020, 2030, 2040, 2050
 
    resBoilerElectric, region1, 5, 0.5, 0, 0, 0
    resBoilerElectric, region2, 39, 3.5, 1, 0.3, 0
 
 
-``ProcessName``
+``technology``
    represents the technology ID and needs to be consistent across all the data inputs.
 
-``RegionName``
+``region``
    represents the region ID and needs to be consistent across all the data inputs.
 
 Years (one column per year)

docs/inputs/projections.rst

@@ -28,7 +28,7 @@ The interpretation of these prices depends on the type of commodity:
 The price trajectory should follow the structure shown in the table below.
 
 .. csv-table:: Initial market projections
-   :header: RegionName, Attribute, Time, com1, com2, com3
+   :header: region, attribute, year, com1, com2, com3
 
    region1, CommodityPrice, 2010, 20, 1.9583, 2
    region1, CommodityPrice, 2015, 20, 1.9583, 2
@@ -41,14 +41,14 @@ The price trajectory should follow the structure shown in the table below.
    region1, CommodityPrice, 2050, 22.85714286, 2.238057143, 2.285714286
 
 
-``RegionName``
+``region``
    represents the region ID and needs to be consistent across all the data inputs
 
-``Attribute``
+``attribute``
    defines the attribute type. In this case it refers to the CommodityPrice; it is
    relevant only for internal use
 
-``Time``
+``year``
    corresponds to the time periods of the simulation; the simulated time framework in
    the example goes from 2010 through to 2050 with a 5-year time step