Usage Guide
===========

This guide provides instructions on how to set up, configure, and run the Inhabit model.

Installation
------------

The Inhabit model requires Python 3.11.9 or higher. To verify your current Python version, run:

.. code-block:: console

   $ python --version

Set up the environment and install dependencies by navigating to the project root and running:

.. code-block:: console

   $ pip install -r requirements.txt

Data Requirements
-----------------

While the model is designed to work with **SOEP (Socio-Economic Panel)** data, it is configured to run using pre-computed empirical data found in the ``data/evidence/`` directory.

If you wish to process raw SOEP data:
1. Apply for data access at the `DIW Berlin <https://www.diw.de/en/diw_01.c.601584.en/data_access.html>`_.
2. Place the required CSV files in the path specified in your configuration.
3. Note that once the evidence files are generated, the original SOEP data is no longer required for the projection steps.

Configuration
-------------

Most model parameters are managed via the ``inputs.xlsx`` file. Key areas for configuration include:

*   **Time Ranges**: Set the start and end years for your simulation.
*   **Scenarios**: Choose between different preference variants (e.g., ``current_quintile``, ``quintile_above``) or mobility assumptions.
*   **Thresholds**: Define maximum household sizes, room counts, and age classes.
*   **Paths**: Configure where input data is located and where results should be saved.

Running the Model
-----------------

The main entry point for the simulation is ``inhabit_matrix.py``. You can run the model using the default configuration or by passing specific flags to override settings.

To run the standard simulation:

.. code-block:: console

   $ python inhabit_matrix.py

Settings Limitations
____________________

Limitations in inputs.xlsx, if not given anyways:

*   **alloc_rate_iteration**: Must sum up to 100
*   **model_start_year**: Only tested for 2019. No way to use model_start_year > 2019
*   **target_year**:    Only tested for 2045. No way to use target_year > 2045
*   **max_hh_size**:    Only tested for values <=5.
*   **max_rooms**:  Census specific maximum and best value is 7
*   **scenario_start_year**:    Useless if < model_start_year

Disaggregation Requirements
---------------------------

The model requires specific disaggregation levels for accurate results. The following disaggregations are mandatory:

Household Characteristics:
   * Household size (hh_size)
   * Income quintile (income_quintile)
   * Household region type (region_type_hh)

Dwelling Characteristics:
   * Building type (building_type)
   * Number of rooms (room_num)
   * Dwelling region type (region_type_dwell)

Optional Disaggregations:
   * Household type (hh_type)
   * Age (age)
   * Ownership (ownership)
   * Condition (condition)

These optional disaggregations can be enabled or disabled as needed for your specific analysis.
Correct model runs are only guaranteed by including all optional disaggregations.
Changing the disaggregation requires SOEP data.

Optional Flags
^^^^^^^^^^^^^^

The script supports several command-line arguments to customize the run:

*   ``--new_evidence``: Create new inhabit matrices from evidence.
*   ``--new_soep``: New calculations of stored soep csvs.
*   ``--debug``: Enable verbose debugging output.
*   ``--new_config``: Automatically deletes data folders that might need different configuration.

Example with flags:

.. code-block:: console

   $ python inhabit_matrix.py --new_evidence --debug

Analyzing Results
-----------------

Once a run is complete, results are saved to the ``output/`` directory (or the path defined in ``inputs.xlsx``). You can generate visualizations using the analysis scripts:

.. code-block:: console

   $ python scripts/analysis_charts.py
   $ python scripts/occupation_charts.py

These scripts will process the generated CSV files and produce charts (often in PDF or HTML format) showing changes in living space, occupancy rates, and stock distributions.