update some references

yamilbknsu · yamilbknsu · commit b07503f3450b · 2026-03-02T14:32:48.000-05:00
diff --git a/README.md b/README.md
@@ -18,27 +18,18 @@ A technical memorandum describing DEMOS is available [here](./DEMOS_Technical_Me
 ### Docker Compose (recommended)
 The latest docker image for demos is stored in `ghcr.io/NatLabRockies/demos:latest`. The input data and configuration file are fed to the container through volumes ([more info about Docker volumes](https://docs.docker.com/engine/storage/volumes/)). We provide a `docker-compose` workflow that can be used to make the process of mounting volumes easier.
 
-#### Prepare the configuration file and data folder
+#### Clone this repository
+By cloning this repository you download the configuration and data for an example run of DEMOS.
 
 Run the following command in the Terminal App (MacOS) or Command Prompt/PowerShell (Windows):
-
 ```bash
-# Create a directory where to run DEMOS from
-mkdir demos
-cd demos
-
-# Create the configuration folder and retrieve an example configuration
-mkdir configuration
-cd configuration
-curl -L -o demos_config.toml https://raw.githubusercontent.com/NatLabRockies/DEMOS/main/configuration/demos_config_small_example.toml
-
-# Create the data folder for the output to be stored
-cd ..
-mkdir data
-# Populate the data folder
-
-# Finally, retrieve the docker-compose.yml file
-curl -L -o docker-compose.yml https://raw.githubusercontent.com/NatLabRockies/DEMOS/main/docker-compose.yml
+git clone https://github.com/NatLabRockies/DEMOS.git
+
+# Move into the project folder
+cd DEMOS
+
+# This folder contains (among other files) a data and configuration folder
+# as well as a docker-compose.yml file
 ```
 
 Make sure you have [Docker](https://docs.docker.com/desktop/) and [Docker Compose](https://docs.docker.com/compose/install/) installed. Now you can run docker as follows:
diff --git a/configuration/demos_config.toml b/configuration/demos_config.toml
@@ -2,7 +2,7 @@
 random_seed = 100
 base_year = 2010
 forecast_year = 2019
-calibrated_models_dir = "../data/sf_bay_example/calibrated_models_coefficients/"
+calibrated_models_dir = "../data/small_example/calibrated_models_coefficients/"
 inconsistent_persons_table_behavior = "fix"
 modules = [
     "aging",
@@ -26,38 +26,40 @@ initialize_empty_tables = [
     "rebalanced_households"
 ]
 
+
 # Data sources
+
 ## Synthetic population data
 [[tables]]
 file_type = "h5"
 table_name = "persons"
-filepath = "../data/sf_bay_example/custom_mpo_06197001_model_data.h5"
+filepath = "../data/small_example/small_example_tables.h5" # custom_mpo_06197001_model_data_small.h5,  minihh.h5, custom_mpo_06197001_model_data_small_stratHH.h5, custom_mpo_06197001_model_data_hh0.05.h5, countyNM.h5
 h5_key = "persons"
 
 [[tables]]
 file_type = "h5"
 table_name = "households"
-filepath = "../data/sf_bay_example/custom_mpo_06197001_model_data.h5"
+filepath = "../data/small_example/small_example_tables.h5" # custom_mpo_06197001_model_data_small.h5,  minihh.h5, custom_mpo_06197001_model_data_hh0.05.h5, custom_mpo_06197001_model_data_county1, countyNM.h5
 h5_key = "households"
 
 ## Other static data tables
 [[tables]]
 file_type = "csv"
 table_name = "relational_adjustment_mapping"
-filepath = "../data/sf_bay_example/relmap_06197001.csv"
+filepath = "../data/small_example/relmap_06197001.csv"
 index_col = "index"
 
 [[tables]]
 file_type = "csv"
 table_name = "income_rates"
-filepath = "../data/sf_bay_example/observed_calibration_values/income_rates_06197001.csv"
+filepath = "../data/small_example/observed_calibration_values/income_rates_06197001.csv"
 index_col = "year"
 custom_dtype_casting = {"lcm_county_id" = "object", "year" = "int", "rate" = "float"}
 
 [[tables]]
 file_type = "csv"
 table_name = "hsize_ct"
-filepath = "../data/sf_bay_example/observed_calibration_values/hsize_ct_06197001.csv"
+filepath = "../data/small_example/observed_calibration_values/hsize_ct_06197001_4155.csv"
 index_col = "year"
 custom_dtype_casting = {"lcm_county_id" = "object", "year" = "int", "hh_size" = "object", "total_number_of_households" = "int"}
 
@@ -67,13 +69,13 @@ custom_dtype_casting = {"lcm_county_id" = "object", "year" = "int", "hh_size" =
 [[tables]]
 file_type = "csv"
 table_name = "observed_employment"
-filepath = "../data/sf_bay_example/observed_calibration_values/employment_obs.csv"
+filepath = "../data/small_example/observed_calibration_values/employment_obs_county.csv"
 index_col = "year"
 
 [[tables]]
 file_type = "csv"
 table_name = "observed_marrital_data"
-filepath = "../data/sf_bay_example/observed_calibration_values/marrital_status_over_time_obs.csv"
+filepath = "../data/small_example/observed_calibration_values/marrital_status_over_time_obs_county.csv"
 index_col = "year"
 
 
@@ -88,24 +90,24 @@ momentum_weight = 0.3
 [mortality_module_config.calibration_procedure]
 procedure_type = "rmse_error"
 tolerance_type = "absolute"
-tolerance = 1000
-max_iter = 1000
+tolerance = 30 
+max_iter = 500
 [mortality_module_config.calibration_procedure.observed_values_table]
 file_type = "csv"
 table_name = "observed_fatalities_data"
-filepath = "../data/sf_bay_example/observed_calibration_values/mortalities_over_time_obs.csv"
+filepath = "../data/small_example/observed_calibration_values/mortalities_over_time_obs_county2.csv"
 index_col = "year"
 
 ## Birth
 [birth_module_config.calibration_procedure]
 procedure_type = "rmse_error"
 tolerance_type = "absolute"
-tolerance = 1000
+tolerance = 60 # lower
 max_iter = 1000
 [birth_module_config.calibration_procedure.observed_values_table]
 file_type = "csv"
 table_name = "observed_births_data"
-filepath = "../data/sf_bay_example/observed_calibration_values/births_over_time_obs.csv"
+filepath = "../data/small_example/observed_calibration_values/births_over_time_obs_county2.csv"
 index_col = "year"
 
 ## HH Reorg
@@ -115,7 +117,7 @@ geoid_col = "lcm_county_id"
 [hh_reorg_module_config.simultaneous_calibration_config]
 tolerance = 5_000
 max_iter = 100
-learning_rate = 2.5
+learning_rate = 1.5
 momentum_weight = 0.3
 
 ## HH Rebalancing
@@ -128,6 +130,5 @@ geoid_col = "lcm_county_id"
 [kids_moving_module_config]
 geoid_col = "lcm_county_id"
 calibration_target_share = 0.12
-calibration_tolerance = 0.001
-
-
+calibration_tolerance = 0.01
+max_iter = 100
diff --git a/configuration/demos_config_ref.toml b/configuration/demos_config_ref.toml
@@ -2,7 +2,7 @@
 random_seed = 100
 base_year = 2010
 forecast_year = 2019
-calibrated_models_dir = "../data/small_example/calibrated_models_coefficients/"
+calibrated_models_dir = "../data/sf_bay_example/calibrated_models_coefficients/"
 inconsistent_persons_table_behavior = "fix"
 modules = [
     "aging",
@@ -26,40 +26,38 @@ initialize_empty_tables = [
     "rebalanced_households"
 ]
 
-
 # Data sources
-
 ## Synthetic population data
 [[tables]]
 file_type = "h5"
 table_name = "persons"
-filepath = "../data/small_example/small_example_tables.h5" # custom_mpo_06197001_model_data_small.h5,  minihh.h5, custom_mpo_06197001_model_data_small_stratHH.h5, custom_mpo_06197001_model_data_hh0.05.h5, countyNM.h5
+filepath = "../data/sf_bay_example/custom_mpo_06197001_model_data.h5"
 h5_key = "persons"
 
 [[tables]]
 file_type = "h5"
 table_name = "households"
-filepath = "../data/small_example/small_example_tables.h5" # custom_mpo_06197001_model_data_small.h5,  minihh.h5, custom_mpo_06197001_model_data_hh0.05.h5, custom_mpo_06197001_model_data_county1, countyNM.h5
+filepath = "../data/sf_bay_example/custom_mpo_06197001_model_data.h5"
 h5_key = "households"
 
 ## Other static data tables
 [[tables]]
 file_type = "csv"
 table_name = "relational_adjustment_mapping"
-filepath = "../data/small_example/relmap_06197001.csv"
+filepath = "../data/sf_bay_example/relmap_06197001.csv"
 index_col = "index"
 
 [[tables]]
 file_type = "csv"
 table_name = "income_rates"
-filepath = "../data/small_example/observed_calibration_values/income_rates_06197001.csv"
+filepath = "../data/sf_bay_example/observed_calibration_values/income_rates_06197001.csv"
 index_col = "year"
 custom_dtype_casting = {"lcm_county_id" = "object", "year" = "int", "rate" = "float"}
 
 [[tables]]
 file_type = "csv"
 table_name = "hsize_ct"
-filepath = "../data/small_example/observed_calibration_values/hsize_ct_06197001_4155.csv"
+filepath = "../data/sf_bay_example/observed_calibration_values/hsize_ct_06197001.csv"
 index_col = "year"
 custom_dtype_casting = {"lcm_county_id" = "object", "year" = "int", "hh_size" = "object", "total_number_of_households" = "int"}
 
@@ -69,13 +67,13 @@ custom_dtype_casting = {"lcm_county_id" = "object", "year" = "int", "hh_size" =
 [[tables]]
 file_type = "csv"
 table_name = "observed_employment"
-filepath = "../data/small_example/observed_calibration_values/employment_obs_county.csv"
+filepath = "../data/sf_bay_example/observed_calibration_values/employment_obs.csv"
 index_col = "year"
 
 [[tables]]
 file_type = "csv"
 table_name = "observed_marrital_data"
-filepath = "../data/small_example/observed_calibration_values/marrital_status_over_time_obs_county.csv"
+filepath = "../data/sf_bay_example/observed_calibration_values/marrital_status_over_time_obs.csv"
 index_col = "year"
 
 
@@ -90,24 +88,24 @@ momentum_weight = 0.3
 [mortality_module_config.calibration_procedure]
 procedure_type = "rmse_error"
 tolerance_type = "absolute"
-tolerance = 30 
-max_iter = 500
+tolerance = 1000
+max_iter = 1000
 [mortality_module_config.calibration_procedure.observed_values_table]
 file_type = "csv"
 table_name = "observed_fatalities_data"
-filepath = "../data/small_example/observed_calibration_values/mortalities_over_time_obs_county2.csv"
+filepath = "../data/sf_bay_example/observed_calibration_values/mortalities_over_time_obs.csv"
 index_col = "year"
 
 ## Birth
 [birth_module_config.calibration_procedure]
 procedure_type = "rmse_error"
 tolerance_type = "absolute"
-tolerance = 60 # lower
+tolerance = 1000
 max_iter = 1000
 [birth_module_config.calibration_procedure.observed_values_table]
 file_type = "csv"
 table_name = "observed_births_data"
-filepath = "../data/small_example/observed_calibration_values/births_over_time_obs_county2.csv"
+filepath = "../data/sf_bay_example/observed_calibration_values/births_over_time_obs.csv"
 index_col = "year"
 
 ## HH Reorg
@@ -117,7 +115,7 @@ geoid_col = "lcm_county_id"
 [hh_reorg_module_config.simultaneous_calibration_config]
 tolerance = 5_000
 max_iter = 100
-learning_rate = 1.5
+learning_rate = 2.5
 momentum_weight = 0.3
 
 ## HH Rebalancing
@@ -130,5 +128,6 @@ geoid_col = "lcm_county_id"
 [kids_moving_module_config]
 geoid_col = "lcm_county_id"
 calibration_target_share = 0.12
-calibration_tolerance = 0.01
-max_iter = 100
+calibration_tolerance = 0.001
+
+
diff --git a/docs/source/pages/default_configuration.rst b/docs/source/pages/default_configuration.rst
@@ -1,9 +1,9 @@
 Default Configuration File
 ==========================
 
-This page shows the default `demos_config.toml`
+This page shows the default `demos_config_ref.toml`
 
-.. literalinclude:: ../../../configuration/demos_config.toml
+.. literalinclude:: ../../../configuration/demos_config_ref.toml
    :language: toml
    :linenos:
-   :caption: Default configuration (`demos_config.toml`)
+   :caption: Default configuration (`demos_config_ref.toml`)
diff --git a/docs/source/pages/intro.md b/docs/source/pages/intro.md
@@ -28,33 +28,26 @@ This document summarizes instructions to install, configure and run DEMOS. Secti
 ### Docker Compose (recommended)
 The latest docker image for demos is stored in `ghcr.io/NatLabRockies/demos:latest`. The input data and configuration file are fed to the container through volumes ([more info about Docker volumes](https://docs.docker.com/engine/storage/volumes/)). We provide a `docker-compose` workflow that can be used to make the process of mounting volumes easier.
 
-#### Prepare the configuration file and data folder
+#### Clone this repository
+By cloning this repository you download the configuration and data for an example run of DEMOS.
 
 Run the following command in the Terminal App (MacOS) or Command Prompt/PowerShell (Windows):
-
 ```bash
-# Create a directory where to run DEMOS from
-mkdir demos
-cd demos
-
-# Create the configuration folder and retrieve an example configuration
-mkdir configuration
-cd configuration
-curl -L -o demos_config.toml https://raw.githubusercontent.com/NatLabRockies/DEMOS/main/configuration/demos_config_small_example.toml
-
-# Create the data folder for the output to be stored
-cd ..
-mkdir data
-# Populate the data folder
-
-# Finally, retrieve the docker-compose.yml file
-curl -L -o docker-compose.yml https://raw.githubusercontent.com/NatLabRockies/DEMOS/main/docker-compose.yml
+git clone https://github.com/NatLabRockies/DEMOS.git
+
+# Move into the project folder
+cd DEMOS
+
+# This folder contains (among other files) a data and configuration folder
+# as well as a docker-compose.yml file
 ```
 
-Now you can run docker as follows:
+Make sure you have [Docker](https://docs.docker.com/desktop/) and [Docker Compose](https://docs.docker.com/compose/install/) installed. Now you can run docker as follows:
+
 ```bash
 docker compose up
 ```
+
 > **Note:**  
 > Make sure the Docker Daemon is running. This changes from system to system but Docker Desktop should have a status flag indicating if the daemon is live, if Desktop is available
 
