Rename notes and description fields

Author: tsmbland

docs/generate_input_format_doc.py

@@ -79,12 +79,12 @@ def fields2table(fields: list[dict[str, str]]) -> tuple[str, str | None]:
     data = []
     for f in fields:
         # MarkdownTable can't handle newlines, so replace with HTML equivalent
-        desc = f.get("description", "")
-        desc = desc.replace("\n\n", "<br /><br />").replace("\n", " ")
+        notes = f.get("notes", "")
+        notes = notes.replace("\n\n", "<br /><br />").replace("\n", " ")
         row = {
             "Field": f"`{f['name']}`",
-            "Description": f["title"],
-            "Notes": desc,
+            "Description": f["description"],
+            "Notes": notes,
         }
         data.append(row)
     table = str(MarkdownTable.from_dicts(data))
@@ -97,8 +97,6 @@ def format_notes(notes) -> str:
     elif isinstance(notes, str):
         items = [add_full_stop(notes)]
     else:
-        items = []
-    if not items:
         return ""
     return "\n".join(f"- {item}" for item in items)
 

schemas/input/agent_commodity_portions.yaml

@@ -12,15 +12,15 @@ notes:
 fields:
   - name: agent_id
     type: string
-    title: The agent to apply these values to
+    description: The agent to apply these values to
   - name: commodity_id
     type: string
-    title: The commodity for which the agent is responsible
+    description: The commodity for which the agent is responsible
   - name: years
     type: string
-    title: The year(s) to which this entry applies
-    description: One or more milestone years separated by semicolons or `all`
+    description: The year(s) to which this entry applies
+    notes: One or more milestone years separated by semicolons or `all`
   - name: commodity_portion
     type: number
-    title: Portion of commodity demand
-    description: Value must be >0 and <=1. The portion applies only to the specified years.
+    description: Portion of commodity demand
+    notes: Value must be >0 and <=1. The portion applies only to the specified years.

schemas/input/agent_cost_limits.yaml

@@ -7,18 +7,18 @@ notes:
 fields:
   - name: agent_id
     type: string
-    title: The agent to apply these values to
+    description: The agent to apply these values to
   - name: years
     type: string
-    title: The year(s) to which this entry applies
-    description: One or more milestone years separated by semicolons or `all`
+    description: The year(s) to which this entry applies
+    notes: One or more milestone years separated by semicolons or `all`
   - name: capex_limit
     type: number
-    title: Maximum capital cost the agent will pay
-    description: Must be >0. Optional (defaults to infinity).
+    description: Maximum capital cost the agent will pay
+    notes: Must be >0. Optional (defaults to infinity).
   - name: annual_cost_limit
     type: number
-    title: Maximum annual operating cost
-    description: |
+    description: Maximum annual operating cost
+    notes: |
       The maximum annual operating cost (fuel plus variable operating cost etc.) that the agent will
       pay. Must be >0. Optional (defaults to infinity).

schemas/input/agent_objectives.yaml

@@ -11,20 +11,20 @@ notes:
 fields:
   - name: agent_id
     type: string
-    title: An agent ID
+    description: An agent ID
   - name: years
     type: string
-    title: The year(s) to which this entry applies
-    description: One or more milestone years separated by semicolons or `all`
+    description: The year(s) to which this entry applies
+    notes: One or more milestone years separated by semicolons or `all`
   - name: objective_type
     type: string
-    title: The type of objective
-    description: Currently only `lcox` is supported
+    description: The type of objective
+    notes: Currently only `lcox` is supported
   - name: decision_weight
     type: number
-    title: Weight for weighted sum decision rule
-    description: Currently unused
+    description: Weight for weighted sum decision rule
+    notes: Currently unused
   - name: decision_lexico_order
     type: integer
-    title: Order in which to consider objectives for lexico decision rule
-    description: Currently unused
+    description: Order in which to consider objectives for lexico decision rule
+    notes: Currently unused

schemas/input/agent_search_space.yaml

@@ -8,17 +8,17 @@ notes:
 fields:
   - name: agent_id
     type: string
-    title: An agent ID
+    description: An agent ID
   - name: commodity_id
     type: string
-    title: The commodity to which this entry applies
+    description: The commodity to which this entry applies
   - name: years
     type: string
-    title: The year(s) to which this entry applies
-    description: One or more milestone years separated by semicolons or `all`
+    description: The year(s) to which this entry applies
+    notes: One or more milestone years separated by semicolons or `all`
   - name: search_space
     type: string
-    title: The processes in which this agent will invest
-    description: |
+    description: The processes in which this agent will invest
+    notes: |
       One or more process IDs separated by semicolons. If this field is empty or `all`, all
       processes will be considered.

schemas/input/agents.yaml

@@ -2,19 +2,19 @@ description: Describes agents in the system
 fields:
   - name: id
     type: string
-    title: A unique identifier for an agent
+    description: A unique identifier for an agent
   - name: description
     type: string
-    title: A human-readable label for the agent
+    description: A human-readable label for the agent
   - name: regions
     type: string
-    title: The region(s) in which the agent operates
-    description: One or more region IDs, separated by semicolons or the string `all`
+    description: The region(s) in which the agent operates
+    notes: One or more region IDs, separated by semicolons or the string `all`
   - name: decision_rule
     type: string
-    title: The decision rule applied to objectives
-    description: Currently the only supported rule is `simple`
+    description: The decision rule applied to objectives
+    notes: Currently the only supported rule is `simple`
   - name: decision_lexico_tolerance
     type: number
-    title: Tolerance for `lexico` decision rule
-    description: Currently unused
+    description: Tolerance for `lexico` decision rule
+    notes: Currently unused

schemas/input/assets.yaml

@@ -3,21 +3,21 @@ description: Defines assets in the system
 fields:
   - name: process_id
     type: string
-    title: The process of which this asset is an instance
+    description: The process of which this asset is an instance
   - name: region_id
     type: string
-    title: The region in which this agent operates
+    description: The region in which this agent operates
   - name: agent_id
     type: string
-    title: The agent to which this asset belongs
+    description: The agent to which this asset belongs
   - name: capacity
     type: number
-    title: The capacity of the asset
-    description: Must be >0
+    description: The capacity of the asset
+    notes: Must be >0
   - name: commission_year
     type: integer
-    title: The year in which to commission this asset
-    description: |
+    description: The year in which to commission this asset
+    notes: |
       This value can be any integer >=0. If it is before the start of the simulation, it will
       already be commissioned in the first year and if it after the end of the simulation then it
       will never be commissioned.

schemas/input/commodities.yaml

@@ -9,19 +9,19 @@ notes:
 fields:
   - name: id
     type: string
-    title: A unique identifier for the commodity
+    description: A unique identifier for the commodity
   - name: description
     type: string
-    title: A human-readable label for the commodity
+    description: A human-readable label for the commodity
   - name: type
     type: string
-    title: The type of commodity
-    description: |
+    description: The type of commodity
+    notes: |
       Must be one of `svd` (service demand), `sed` (supply equals demand), `inc` (input
       commodity) or `ouc` (output commodity)
   - name: time_slice_level
     type: string
-    title: The time slice level at which constraints for this commodity are applied
-    description: |
+    description: The time slice level at which constraints for this commodity are applied
+    notes: |
       Must be one of `annual` (whole year), `season` (whole season) or `daynight` (a particular time
       of day)

schemas/input/commodity_levies.yaml

@@ -8,27 +8,27 @@ notes:
 fields:
   - name: commodity_id
     type: string
-    title: The commodity to which this entry applies
+    description: The commodity to which this entry applies
   - name: regions
     type: string
-    title: The region(s) to which this entry applies
-    description: One or more region IDs, separated by semicolons or the string `all`
+    description: The region(s) to which this entry applies
+    notes: One or more region IDs, separated by semicolons or the string `all`
   - name: years
     type: string
-    title: The year(s) to which this entry applies
-    description: One or more milestone years separated by semicolons or `all`
+    description: The year(s) to which this entry applies
+    notes: One or more milestone years separated by semicolons or `all`
   - name: time_slice
     type: string
-    title: The time slices(s) to which this entry applies
-    description: |
+    description: The time slices(s) to which this entry applies
+    notes: |
       Can be a single time slice (e.g. `winter.day`), a whole season (e.g. `winter`) or `annual`,
       representing the whole year
   - name: balance_type
     type: string
-    title: The type of balance to which this is applied
-    description: |
+    description: The type of balance to which this is applied
+    notes: |
       Can be `cons` (applies to consumption only), `prod` (applies to production only) or
       `net` (applies to consumption and production)
   - name: value
     type: number
-    title: The value of the levy/incentive
+    description: The value of the levy/incentive

schemas/input/demand.yaml

@@ -8,15 +8,15 @@ notes:
 fields:
   - name: commodity_id
     type: string
-    title: The service demand commodity to which this entry applies
+    description: The service demand commodity to which this entry applies
   - name: region_id
     type: string
-    title: The region to which this entry applies
-    description: A region ID
+    description: The region to which this entry applies
+    notes: A region ID
   - name: years
     type: string
-    title: The year(s) to which this entry applies
-    description: One or more milestone years separated by semicolons or `all`
+    description: The year(s) to which this entry applies
+    notes: One or more milestone years separated by semicolons or `all`
   - name: demand
     type: number
-    title: Total demand for this year
+    description: Total demand for this year