Restructure CHILLED code to be more trackable and customizable

.gitignore

@@ -20,4 +20,7 @@ doc/_build
 .DS_Store
 
 # Scratch code
-scratch*
+scratch*
+
+# CHILLED user settings
+user_settings.py

doc/chilled.rst

@@ -0,0 +1,68 @@
+.. currentmodule:: message_ix_buildings.chilled
+
+CHILLED (:mod:`.chilled`)
+*************************
+
+:mod:`.chilled` (Cooling and HeatIng gLobaL Energy Demand) is a model that assesses the impacts of climate change (temperature change).
+
+Methods
+=======
+
+
+Data
+====
+
+Input data
+----------
+
+
+Parameters
+----------
+
+In this module, the "version" refers to the version of the model, not the version of the data. For example, the "ALPS2023" version refers to the set of scenario inputs/parameters for the "ALPS2023" run.
+When specifying a version, CHILLED will look in the `/data/chilled/version` directory that the version name exists and that the following files exist as well:
+
+- `arch_input_reg.xlsx` (or `arch_input.xlsx`)
+- `arch_regions.xlsx`
+- `par_var.csv`
+- `runs.csv`
+
+Usage
+=====
+
+The preprocessing (preparing MESSAGE region rasters and country codes) happens without specifying GCM or RCP scenario. Therefore, it can be run first on its own using the following command (from within :mod:`chilled.run`):
+
+.. code-block:: bash
+
+   python -m preprocess.py -version "version_name"
+
+If the `-version` command is not provided, then the default version is "ALPS2023".
+
+The main model can be run using the following command:
+
+.. code-block:: bash
+
+   python -m main.py -version "version_name" -gcm "gcm_name" -rcp "rcp_name"
+
+If the `-version` command is not provided, then the default version is "ALPS2023". 
+If the `-gcm` and `-rcp` commands are not provided, then the default GCM is "GFDL-ESM2M" and the default RCP is "baseline".
+
+
+Code reference
+==============
+
+.. automodule:: message_ix_buildings.chilled
+   :members:
+
+.. currentmodule:: message_ix_buildings.chilled.preprocess.message_raster
+
+Create raster of MESSAGE regions (:mod:`~.chilled.preprocess.message_raster`)
+-----------------------------------------------------------------------------
+
+.. automodule:: message_ix_buildings.chilled.preprocess.message_raster
+   :members:
+
+   .. autosummary::
+
+      create_message_raster
+

doc/conf.py

@@ -3,6 +3,12 @@
 # For the full list of built-in configuration values, see the documentation:
 # https://www.sphinx-doc.org/en/master/usage/configuration.html
 
+import os
+import sys
+
+
+sys.path.insert(0, os.path.abspath(".."))
+
 # -- Project information ---------------------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
@@ -14,9 +20,17 @@
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
 extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.coverage",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.extlinks",
     "sphinx.ext.intersphinx",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.todo",
+    "sphinx.ext.viewcode",
 ]
 
+
 templates_path = ["_templates"]
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 

doc/index.rst

@@ -9,18 +9,19 @@ Welcome to MESSAGEix-Buildings's documentation!
 “MESSAGEix-Buildings” refers to a collection of linked models, including:
 
 - ACCESS
-- CHILLED
+- :doc:`chilled`
 - :doc:`sturm`
 
 …and their integration with the :doc:`MESSAGEix-GLOBIOM model family <message_ix_models:index>`.
 
-At present, the package :mod:`message_ix_buildings` contains STURM only.
+At present, the package :mod:`message_ix_buildings` contains STURM and CHILLED only.
 
 .. toctree::
    :maxdepth: 2
    :hidden:
 
    sturm
+   chilled
    dev
 
 Indices and tables

message_ix_buildings/chilled/aggregate.py → message_ix_buildings/chilled/analysis/aggregate.py

@@ -1,7 +1,7 @@
 import glob
 import os
 
-import pandas as pd  # type: ignore
+import pandas as pd
 from sklearn.utils.fixes import parse_version, sp_version  # type: ignore
 
 from message_ix_buildings.chilled.variable_dicts import SCENARIO_NAMES

message_ix_buildings/chilled/check_pop.py → message_ix_buildings/chilled/analysis/check_pop.py

@@ -1,20 +1,16 @@
 import os
 from itertools import product
 
-import pandas as pd  # type: ignore
+import pandas as pd
 import xarray as xr
 
-from message_ix_buildings.chilled.config import Config
-from message_ix_buildings.chilled.variable_dicts import (
+from message_ix_buildings.chilled.functions.variable_dicts import (
     VARDICT_COOL,
     VARDICT_HEAT,
     VARUNDICT_COOL,
     VARUNDICT_HEAT,
 )
 
-cfg = Config()
-
-dle_path = cfg.dle_path
 vstr = cfg.vstr
 vstrcntry = cfg.vstrcntry
 gcm = cfg.gcm

message_ix_buildings/chilled/preprocess.py → message_ix_buildings/chilled/archive/preprocess.py

@@ -3,11 +3,12 @@
 from itertools import product
 
 import numpy as np
-import pandas as pd  # type: ignore
+import pandas as pd
 import xarray as xr
 from dask.diagnostics import ProgressBar
 
-from message_ix_buildings.chilled.buildings_funcs_grid import (
+from message_ix_buildings.chilled.util.config import Config
+from message_ix_buildings.chilled.functions.buildings_funcs_grid import (
     P_f,
     Q_c_tmax,
     Q_h,
@@ -30,28 +31,6 @@
     calc_vdd_h,
     calc_vdd_tmax_c,
 )
-from message_ix_buildings.chilled.config import Config
-from message_ix_buildings.chilled.variable_dicts import (
-    VARS_ARCHETYPES,
-    YEARS_BASELINE,
-    YEARS_OTHERS,
-)
-
-#     print(clims + " + " + archs + " + " + parset_name_run + " + " + urts)
-
-
-def create_archetype_template_map(
-    dle_path,
-    version_name,
-    gcm,
-    rcp_scenario,
-    message_region_file,
-    archs_specified,
-    arch_setting,
-    urts,
-    comp,
-):
-    output_path_arch = os.path.join(
         dle_path,
         f"output_data_{version_name}",
         gcm,

message_ix_buildings/chilled/vdd_functions.py → message_ix_buildings/chilled/archive/vdd_functions.py

@@ -7,12 +7,12 @@
 import cartopy.feature as cfeature  # type: ignore
 import matplotlib.pyplot as plt  # type: ignore
 import numpy as np
-import pandas as pd  # type: ignore
+import pandas as pd
 import pyam  # type: ignore
 import xarray as xr
 from dask.diagnostics import ProgressBar
 
-from message_ix_buildings.chilled.buildings_funcs_grid import (
+from .buildings_funcs_grid import (
     P_f,
     Q_c_tmax,
     Q_h,
@@ -35,7 +35,7 @@
     calc_vdd_h,
     calc_vdd_tmax_c,
 )
-from message_ix_buildings.chilled.variable_dicts import (
+from .variable_dicts import (
     VARDICT_COOL,
     VARDICT_HEAT,
     VARS_ARCHETYPES,

message_ix_buildings/chilled/z1_VDD_ene_calcs.py → message_ix_buildings/chilled/archive/z1_VDD_ene_calcs.py

@@ -2,13 +2,13 @@
 
 import numpy as np
 
-from message_ix_buildings.chilled.aggregate import (
+from message_ix_buildings.chilled.analysis.aggregate import (
     aggregate_ISO_tables_to_regions,
     create_prereg_data,
 )
-from message_ix_buildings.chilled.regression import apply_regression
-from message_ix_buildings.chilled.user_settings import DICT_USER_SETTINGS
-from message_ix_buildings.chilled.vdd_functions import (
+from message_ix_buildings.chilled.functions.regression import apply_regression
+from message_ix_buildings.chilled.functions.user_settings import DICT_USER_SETTINGS
+from message_ix_buildings.chilled.functions.vdd_functions import (
     aggregate_urban_rural_files,
     calculate_cumulative_carbon_emissions,
     create_archetype_template_map,