From 9fb33ec488f18662693cd7163c49ab873a383f9f Mon Sep 17 00:00:00 2001
From: Vivek Yadav <vivekyadav2691@gmail.com>
Date: Tue, 19 Sep 2023 10:40:29 -0500
Subject: [PATCH] auto ownership

---
 activitysim/abm/models/auto_ownership.py    | 28 +++++++++++++---
 docs/dev-guide/components/auto_ownership.md | 36 +++++++++++++++++++++
 2 files changed, 59 insertions(+), 5 deletions(-)
 create mode 100644 docs/dev-guide/components/auto_ownership.md

diff --git a/activitysim/abm/models/auto_ownership.py b/activitysim/abm/models/auto_ownership.py
index ba18a09df..0b0f85485 100644
--- a/activitysim/abm/models/auto_ownership.py
+++ b/activitysim/abm/models/auto_ownership.py
@@ -5,29 +5,47 @@
 import logging
 
 import pandas as pd
+from pydantic import validator
 
 from activitysim.core import config, estimation, simulate, tracing, workflow
+from activitysim.core.configuration.base import PreprocessorSettings, PydanticReadable
+from activitysim.core.configuration.logit import LogitComponentSettings
 
 logger = logging.getLogger(__name__)
 
 
+class AutoOwnershipSettings(PydanticReadable):
+    """
+    Settings for the `auto_ownership` component.
+    """
+
+    SPEC: str = "auto_ownership.csv"
+    """Filename for the auto ownership specification (csv) file."""
+
+
 @workflow.step
 def auto_ownership_simulate(
     state: workflow.State,
     households: pd.DataFrame,
     households_merged: pd.DataFrame,
+    model_settings: AutoOwnershipSettings | None = None,
+    model_settings_file_name: str = "auto_ownership.yaml",
+    trace_label: str = "auto_ownership_simulate",
+    trace_hh_id: bool = False,
 ) -> None:
     """
     Auto ownership is a standard model which predicts how many cars a household
     with given characteristics owns
     """
-    trace_label = "auto_ownership_simulate"
-    model_settings_file_name = "auto_ownership.yaml"
-    model_settings = state.filesystem.read_model_settings(model_settings_file_name)
-    trace_hh_id = state.settings.trace_hh_id
+
+    if model_settings is None:
+        model_settings = AutoOwnershipSettings.read_settings_file(
+            state.filesystem,
+            model_settings_file_name,
+        )
 
     estimator = estimation.manager.begin_estimation(state, "auto_ownership")
-    model_spec = state.filesystem.read_model_spec(file_name=model_settings["SPEC"])
+    model_spec = state.filesystem.read_model_spec(file_name=model_settings.SPEC)
     coefficients_df = state.filesystem.read_model_coefficients(model_settings)
     model_spec = simulate.eval_coefficients(
         state, model_spec, coefficients_df, estimator
diff --git a/docs/dev-guide/components/auto_ownership.md b/docs/dev-guide/components/auto_ownership.md
new file mode 100644
index 000000000..240ddb98c
--- /dev/null
+++ b/docs/dev-guide/components/auto_ownership.md
@@ -0,0 +1,36 @@
+(component-auto-ownership)=
+# Auto Ownership
+
+```{eval-rst}
+.. currentmodule:: activitysim.abm.models.auto_owenership
+```
+
+The auto ownership model selects a number of autos for each household in the simulation.
+The primary model components are household demographics, zonal density, and accessibility.
+
+## Structure
+
+- *Configuration File*: `auto_ownership.yaml`
+- *Core Table*: `households`
+- *Result Field*: `auto_owenership`
+
+This model is structured as nested logit model.
+
+## Configuration
+
+```{eval-rst}
+.. autopydantic_model::
+    :inherited-members: BaseModel, PydanticReadable
+    :show-inheritance:
+```
+
+### Examples
+
+- [Prototype MTC](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_mtc/configs/auto_ownership.yaml)
+- [Prototype ARC](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_arc/configs/auto_ownership.yaml)
+
+## Implementation
+
+```{eval-rst}
+.. autofunction:: auto_ownership
+```