Watts-Lab · paco-barreras · Apr 24, 2026 · Apr 24, 2026
diff --git a/.readthedocs.yaml b/.readthedocs.yaml
@@ -32,4 +32,6 @@ sphinx:
 # See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
 python:
   install:
-    - requirements: docs/requirements.txt
+    - method: pip
+      path: .
+    - requirements: docs/requirements.txt
diff --git a/docs/_static/stop_detection/benchmarking_runtime.png b/docs/_static/stop_detection/benchmarking_runtime.png
diff --git a/docs/_static/stop_detection/grid_based_demo.png b/docs/_static/stop_detection/grid_based_demo.png
diff --git a/docs/_static/stop_detection/hdbscan_demo.png b/docs/_static/stop_detection/hdbscan_demo.png
diff --git a/docs/_static/stop_detection/lachesis_demo.png b/docs/_static/stop_detection/lachesis_demo.png
diff --git a/docs/_static/stop_detection/tadbscan_demo.png b/docs/_static/stop_detection/tadbscan_demo.png
diff --git a/docs/api_reference.rst b/docs/api_reference.rst
@@ -0,0 +1,23 @@
+=============
+API Reference
+=============
+
+.. toctree::
+   :maxdepth: 2
+
+   api/nomad.agg
+   api/nomad.aggregation
+   api/nomad.city_gen
+   api/nomad.constants
+   api/nomad.contact_estimation
+   api/nomad.displacement
+   api/nomad.filters
+   api/nomad.filters_spark
+   api/nomad.generation
+   api/nomad.home_attribution
+   api/nomad.io
+   api/nomad.map_utils
+   api/nomad.metrics
+   api/nomad.stop_detection
+   api/nomad.traj_gen
+   api/nomad.visit_attribution
diff --git a/docs/base_module.rst b/docs/base_module.rst
diff --git a/docs/conf.py b/docs/conf.py
@@ -38,6 +38,7 @@
     "sphinx.ext.todo",
     "sphinx.ext.viewcode",
     "sphinx.ext.autodoc",
+    "sphinx.ext.napoleon",
     'sphinx_rtd_theme',
     'sphinx_design'
 ]
@@ -64,12 +65,11 @@
 # Theme options to customize the appearance
 html_theme_options = {
     'logo_only': True,  # Only show the logo, not the project name
-    'display_version': False,  # Don't display version info
 }
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ['_static']
 
-html_logo = "_static/nomad-logo-black.png"
+html_logo = "_static/nomad-logo-black.png"
diff --git a/docs/index.rst b/docs/index.rst
@@ -41,6 +41,7 @@ Installation
    :caption: User Guide
    :hidden:
 
+   getting_started
    data_ingestion
    filtering
    tessellation

diff --git a/docs/modules.rst b/docs/modules.rst
diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -1 +1,5 @@
-sphinx-rtd-theme==1.2.2
+sphinx==8.1.3
+sphinx-rtd-theme==3.0.2
+nbsphinx==0.9.7
+sphinx-design==0.6.1
+ipython
diff --git a/docs/source/generate_synthetic_pois.ipynb b/docs/source/generate_synthetic_pois.ipynb
@@ -1,5 +1,13 @@
 {
  "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "e55d095e",
+   "metadata": {},
+   "source": [
+    "# Synthetic POI Generation\n"
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": 1,

diff --git a/docs/source/generate_synthetic_trajectories.ipynb b/docs/source/generate_synthetic_trajectories.ipynb
@@ -307,14 +307,6 @@
     ")\n",
     "print(f\"Saved sparse trajectories to {output_path}\")"
    ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "50b21243-a3c0-4498-9afd-1ddb9651c8b7",
-   "metadata": {},
-   "outputs": [],
-   "source": []
   }
  ],
  "metadata": {

diff --git a/docs/source/lachesis_demo.ipynb b/docs/source/lachesis_demo.ipynb
diff --git a/docs/source/random_city.ipynb b/docs/source/random_city.ipynb
diff --git a/docs/source/tadbscan_demo.ipynb b/docs/source/tadbscan_demo.ipynb
diff --git a/docs/stop_detection.rst b/docs/stop_detection.rst
@@ -14,7 +14,7 @@ Overview of stop-detection methods
 
 A comparison of the stop-detection algorithms in NOMAD is shown below.
 
-.. figure:: _images/source_benchmarking_of_stop_detection_algorithms_10_0.png
+.. figure:: _static/stop_detection/benchmarking_runtime.png
    :target: source/benchmarking_of_stop_detection_algorithms.html
    :align: center
    :width: 80%
@@ -62,7 +62,7 @@ Notice that this method also works with **geographic coordinates** (lon, lat), u
 
 **Source:** Ester, M., Kriegel, H. P., Sander, J., & Xu, X. (1996). A density-based algorithm for discovering clusters in large spatial databases with noise. *Proceedings of the Second International Conference on Knowledge Discovery and Data Mining (KDD-96)*, 226-231.
 
-.. figure:: _images/source_tadbscan_demo_3_0.png
+.. figure:: _static/stop_detection/tadbscan_demo.png
    :target: source/tadbscan_demo.html
    :align: center
    :width: 80%
@@ -79,7 +79,7 @@ The HDBSCAN algorithm constructs a hierarchy of non-overlapping clusters from di
 
 **Source:** Campello, R. J., Moulavi, D., & Sander, J. (2013). Density-based clustering based on hierarchical density estimates. *Pacific-Asia Conference on Knowledge Discovery and Data Mining (PAKDD)*, 160-172.
 
-.. figure:: _images/source_hdbscan_demo_3_0.png
+.. figure:: _static/stop_detection/hdbscan_demo.png
    :target: source/hdbscan_demo.html
    :align: center
    :width: 80%
@@ -102,7 +102,7 @@ The algorithms work with the same call, provided there is at least a pair of coo
 
 **Source:** NOMAD implementation using spatial tessellation (H3, S2) for trajectory segmentation.
 
-.. figure:: _images/source_grid_based_demo_3_0.png
+.. figure:: _static/stop_detection/grid_based_demo.png
    :target: source/grid_based_demo.html
    :align: center
    :width: 80%
@@ -130,7 +130,7 @@ This algorithm has the following parameters, which determine the size of the res
 
 **Source:** Hariharan, R., & Toyama, K. (2004). Project Lachesis: Parsing and modeling location histories. *International Conference on Geographic Information Science*, 106-124.
 
-.. figure:: _images/source_lachesis_demo_3_0.png
+.. figure:: _static/stop_detection/lachesis_demo.png
    :target: source/lachesis_demo.html
    :align: center
    :width: 80%

diff --git a/nomad/city_gen.py b/nomad/city_gen.py
@@ -93,18 +93,6 @@ class City:
     gravity : pandas.DataFrame
         A DataFrame containing the gravity values between all pairs of streets.
 
-    Methods
-    -------
-    add_building
-        Adds a building to the city.
-    get_block
-        Returns the block (Street or Building) at the given coordinates.
-    get_street_graph
-        Constructs the graph of streets and calculates the shortest paths between all pairs of streets.
-    save
-        Saves the city object to a file.
-    plot_city
-        Plots the city on a given matplotlib axis.
     """
 
     def __init__(self,
@@ -667,12 +655,16 @@ def compute_gravity(self, exponent=2.0, callable_only=False, n_chunks=10, use_pr
 
         Notes
         -----
-        Hub mode approximates: dist(i,j) ≈ manhattan(door_i, hub_i) + graph(hub_i, hub_j) + manhattan(hub_j, door_j)
-        True mode computes: dist(i,j) = shortest_path_length(door_i, door_j) on street graph
+        Hub mode approximates ``dist(i, j)`` as the distance from
+        ``door_i`` to ``hub_i``, plus the graph distance from ``hub_i`` to
+        ``hub_j``, plus the distance from ``hub_j`` to ``door_j``.
+        True mode computes ``shortest_path_length(door_i, door_j)`` on the
+        street graph.
 
         Stores result in self.grav as DataFrame (callable_only=False) or callable (callable_only=True)
 
         Persistence:
+
         - Hub mode (use_proxy_hub_distance=True): Gravity infrastructure is saved by 
           save_geopackage() and restored by from_geopackage(load_gravity=True). The 
           city.grav callable works immediately after loading.

diff --git a/nomad/filters.py b/nomad/filters.py
@@ -711,6 +711,7 @@ def completeness(data,
     ----------
     data : pandas.Series or pandas.DataFrame
         Trajectory data containing timestamps, either as:
+
         - A pandas Series of Unix-second integers or datetime64 values.
         - A DataFrame, from which timestamp and user columns are identified
           via `traj_cols` or default column naming conventions.

diff --git a/nomad/traj_gen.py b/nomad/traj_gen.py
@@ -75,10 +75,12 @@ def sample_bursts_gaps(traj,
         scale parameter (mean) of Exponential distribution modeling ping inter-arrival times
         within a burst, where 1/beta_ping is the rate of events (pings) per minute.
     ha: float
-        Mean horizontal-accuracy radius *in 15 m blocks*. The actual per-ping accuracy is random: ha ≥ 8 m/15m
-        and follows a Pareto distribution with that mean. For each ping the spatial noise (ε_x, ε_y) is drawn
-        i.i.d. N(0, σ²) with σ = HA / 1.515 so that |ε| ≤ HA with 68 % probability.
-    seed : int0
+        Mean horizontal-accuracy radius in 15 m blocks. The actual per-ping
+        accuracy is random: ha >= 8 m / 15 m and follows a Pareto distribution
+        with that mean. For each ping the spatial noise (epsilon_x, epsilon_y)
+        is drawn i.i.d. from N(0, sigma^2), with sigma = HA / 1.515 so that
+        abs(epsilon) <= HA with 68 percent probability.
+    seed : int
         The seed for random number generation.
     output_bursts : bool
         If True, outputs the latent variables on when bursts start and end.
@@ -150,12 +152,6 @@ class Agent:
     dt : float
         Time step duration.
 
-    Methods
-    -------
-    plot_traj
-        Plots the trajectory of the agent on the given axis.
-    sample_traj_hier_nhpp
-        Samples a sparse trajectory using a hierarchical non-homogeneous Poisson process.
     """
 
     def __init__(self, 
@@ -1320,6 +1316,8 @@ def save_pop(self,
 
         Parameters
         ----------
+        traj_cols : dict, optional
+            Column mapping used to normalize trajectory data before writing.
         sparse_path : str or Path, optional
             Destination path for sparse trajectories.
         full_path : str or Path, optional
@@ -1330,9 +1328,15 @@ def save_pop(self,
             Destination path for diaries.
         dest_diaries_path : str or Path, optional
             Destination path for destination diaries.
-        partition_cols : list of partition column names.
+        partition_cols : list of str, optional
+            Column names used to partition written datasets.
+        mixed_timezone_behavior : str, optional
+            Behavior passed to ``nomad.io.base.from_df`` for mixed timezone
+            columns.
         filesystem : pyarrow.fs.FileSystem or None
             Optional filesystem object (e.g., s3fs.S3FileSystem). If None, inferred automatically.
+        fmt : str, optional
+            File format to write.
         **kwargs : dict, optional
             Additional static columns to include in the homes table. Each key-value pair
             represents a column name and its values. Values must be a list/array of length N
@@ -1526,4 +1530,4 @@ def allowed_buildings(local_ts):
     Finds allowed buildings for the timestamp
     """
     hour = local_ts.hour
-    return ALLOWED_BUILDINGS[hour]
+    return ALLOWED_BUILDINGS[hour]