Docs

.readthedocs.yaml

@@ -0,0 +1,30 @@
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+version: 2
+
+# Set the OS, Python version, and other tools
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+  configuration: docs/conf.py
+  fail_on_warning: false
+
+# Optional: include PDF and ePub outputs
+formats:
+  - pdf
+
+# Install dependencies
+python:
+  install:
+    # Install docs requirements
+    - requirements: docs/requirements.txt
+    # Install the package itself (without external FRB deps for docs)
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs

docs/Makefile

@@ -0,0 +1,18 @@
+# Minimal makefile for Sphinx documentation
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/api.rst

@@ -0,0 +1,238 @@
+.. _api:
+
+=============
+API Reference
+=============
+
+This section provides detailed API documentation for all public modules
+and classes in the ``zdm`` package.
+
+Core Modules
+============
+
+These modules form the backbone of the zdm package, providing parameter
+management, survey handling, and z-DM grid computation.
+
+parameters
+----------
+
+Central configuration system for FRB z-DM analysis. All model parameters
+are organized into dataclasses grouped by category (cosmology, FRB demographics,
+host galaxy, IGM, etc.). The ``State`` class aggregates all parameter groups.
+
+.. automodapi:: zdm.parameters
+   :no-inheritance-diagram:
+
+survey
+------
+
+FRB Survey class for modeling telescope observations. Encapsulates instrument
+characteristics, beam patterns, detection efficiencies, and detected FRB data.
+Survey files are loaded from ECSV format with header metadata and FRB tables.
+
+.. automodapi:: zdm.survey
+   :no-inheritance-diagram:
+
+grid
+----
+
+Core z-DM grid class for FRB population modeling. Computes 2D probability
+distributions of FRB detection rates as a function of redshift and DM by
+combining cosmological volumes, p(DM|z), telescope efficiency, and luminosity
+functions.
+
+.. automodapi:: zdm.grid
+   :no-inheritance-diagram:
+
+repeat_grid
+-----------
+
+Grid extension for repeating FRB population modeling. Models expected numbers
+of single and repeated detections given a distribution of repeater rates
+following dN/dR ~ R^Rgamma.
+
+.. automodapi:: zdm.repeat_grid
+   :no-inheritance-diagram:
+
+Computation Modules
+===================
+
+Physics and statistics modules for computing cosmological quantities,
+DM probability distributions, and energy functions.
+
+cosmology
+---------
+
+Lambda CDM cosmology calculations including distance measures (comoving,
+angular diameter, luminosity), volume elements, and source evolution functions.
+Uses interpolation tables for fast array operations.
+
+.. automodapi:: zdm.cosmology
+   :no-inheritance-diagram:
+
+pcosmic
+-------
+
+Probability distribution of cosmic dispersion measure given redshift, p(DM|z).
+Implements the Macquart relation from Macquart et al. (2020) with the feedback
+parameter F controlling variance. Also provides host galaxy DM convolution kernels.
+
+.. automodapi:: zdm.pcosmic
+   :no-inheritance-diagram:
+
+energetics
+----------
+
+FRB luminosity/energy function implementations including power-law and
+gamma-function distributions. Uses spline interpolation of the upper incomplete
+gamma function for computational efficiency during grid calculations.
+
+.. automodapi:: zdm.energetics
+   :no-inheritance-diagram:
+
+iteration
+---------
+
+Likelihood calculation routines for z-DM grids. Computes log-likelihoods of
+FRB survey data given model predictions, including components for p(DM,z),
+Poisson number counts, SNR distributions, and width/scattering.
+
+.. automodapi:: zdm.iteration
+   :no-inheritance-diagram:
+
+Utility Modules
+===============
+
+Helper functions for data loading, plotting, and common operations.
+
+loading
+-------
+
+High-level functions for loading surveys and initializing analysis state.
+Provides convenience functions like ``set_state()`` for creating properly
+configured State objects with default or best-fit parameters.
+
+.. automodapi:: zdm.loading
+   :no-inheritance-diagram:
+
+misc_functions
+--------------
+
+Miscellaneous utility functions including grid initialization, parameter
+updates, probability calculations, and other common operations used
+throughout the package.
+
+.. automodapi:: zdm.misc_functions
+   :no-inheritance-diagram:
+
+figures
+-------
+
+Plotting functions for visualizing z-DM grids and FRB data. Provides
+publication-quality plots of probability distributions and analysis results.
+
+.. automodapi:: zdm.figures
+   :no-inheritance-diagram:
+
+beams
+-----
+
+Telescope beam pattern modeling utilities. Provides functions for generating
+and loading beam patterns (Gaussian, Airy, measured) that affect solid angle
+and sensitivity variations across the field of view.
+
+.. automodapi:: zdm.beams
+   :no-inheritance-diagram:
+
+Analysis Modules
+================
+
+Parameter estimation and analysis tools.
+
+MCMC
+----
+
+MCMC parameter estimation using the emcee package. Provides functions for
+running samplers, computing log-posteriors, and exploring parameter space
+with support for multiple surveys and uniform priors.
+
+.. automodapi:: zdm.MCMC
+   :no-inheritance-diagram:
+
+MCMC_analysis
+-------------
+
+Analysis utilities for MCMC chains including convergence diagnostics,
+corner plots, and posterior summaries.
+
+.. automodapi:: zdm.MCMC_analysis
+   :no-inheritance-diagram:
+
+analyze_cube
+------------
+
+Tools for analyzing pre-computed parameter cubes.
+
+.. automodapi:: zdm.analyze_cube
+   :no-inheritance-diagram:
+
+vvmax
+-----
+
+V/Vmax statistical tests for FRB population analysis.
+
+.. automodapi:: zdm.vvmax
+   :no-inheritance-diagram:
+
+Data Classes
+============
+
+Base classes and data structures.
+
+data_class
+----------
+
+Base dataclass utilities for parameter management. Provides common functionality
+for serialization, dictionary access, and parameter metadata handling used by
+all parameter dataclasses.
+
+.. automodapi:: zdm.data_class
+   :no-inheritance-diagram:
+
+survey_data
+-----------
+
+Data structures for survey metadata and FRB observations.
+
+.. automodapi:: zdm.survey_data
+   :no-inheritance-diagram:
+
+Specialized Modules
+===================
+
+Additional modules for specific use cases.
+
+galactic_dm_models
+------------------
+
+Models for Galactic DM contributions including different halo models.
+
+.. automodapi:: zdm.galactic_dm_models
+   :no-inheritance-diagram:
+
+optical
+-------
+
+Optical counterpart and host galaxy association utilities.
+
+.. automodapi:: zdm.optical
+   :no-inheritance-diagram:
+
+io
+--
+
+Input/output utilities for file handling including JSON I/O and
+grid data persistence.
+
+.. automodapi:: zdm.io
+   :no-inheritance-diagram: