ratio-study 0.3.0__py3-none-any.whl

ratio_study/__init__.py

@@ -0,0 +1,241 @@
+""" Ratio Studies Package
+This package makes easier running a Ratio Study, an instrument on the analysis of real property valuation models
+
+Based on IAAO's Standard on Ratio Studies available at https://www.iaao.org/media/standards/Standard_on_Ratio_Studies.pdf
+and on the following work:
+Quintos, C. (2021). A Gini decomposition of the sources of inequality in property assessments. Journal of
+Property Tax Assessment & Administration, 18(2). Retrieved from https://researchexchange.iaao.org/ jptaa/vol18/iss2/6
+Quintos, C. (2020). A Gini measure for vertical equity in property assessments. Journal of Property Tax
+Assessment & Administration, 17(2). Retrieved from https://researchexchange.iaao.org/jptaa/vol17/iss2/ 2
+Thomas J. DiCiccio. Bradley Efron. "Bootstrap confidence intervals." Statist. Sci. 11 (3) 189 - 228, August 1996.
+https://doi.org/10.1214/ss/1032280214
+Formulas on article by David Zaslavsky: https://www.ellipsix.net/blog/2012/11/the-gini-coefficient-for-distribution-inequality.html
+"""
+__author__ = 'Eric Kutchukian @ MPAC'
+__copyright__ = 'Copyright 2026, Municipal Property Assessment Corporation'
+__credits__ = ['Eric Kutchukian, James Ellens, Micheal Boateng, James Bryan, James Gilbert, Mohammad Jaber']
+__license__ = 'GPL v3'
+__maintainer__ = '{Eric Kutchukian}'
+__email__ = '{eric.kutchukian@mpac.ca}'
+__status__ = '{Dev}'
+
+
+"""ratio_study — ratio-study analysis for real-property assessment.
+
+Quick start
+-----------
+>>> from ratio_study import ratios, IAAO_RESIDENTIAL
+>>> results = ratios(df, "assessed_value", "sale_price", config=IAAO_RESIDENTIAL)
+"""
+
+from ._version import __version__
+from ratio_study._data import load_sample_dataset, sample_dataset_path
+
+__all__ = ["load_sample_dataset", "sample_dataset_path", ...]
+
+__all__ = [
+    "load_sample_dataset", 
+    "sample_dataset_path",
+    'rts_calculator', 
+    'ratios',
+    'ratios_report',
+    'gini_stats',
+    'gini_decomp',
+    'gini_factors',
+    'gini_lorenz_plot',
+    'compare_ratios',
+    'vei_boxplot',
+    'vei_analysis',
+    'asr_median',
+    'asr_mean',
+    'cod',
+    'cod_residual',
+    'prd',
+    'prb',
+    'rmse',
+    'mae',
+    'mape',
+    'mdmape',
+    'fsd',
+    'CoV_adj',
+    'CoC',
+    'compute_median_ci',
+    'compute_median_ci_on_binomial',
+    'bo_decompose',
+    'bo_multi_decomposition',
+    'bo_format_table',
+    'bo_coefficient_plot',
+    'bo_decomposition_plot',
+    'bo_detail_plot',
+]
+
+
+def __getattr__(name):
+    if name == "ratios_calculator":
+        from .ratio_study import ratios_calculator
+        return ratios_calculator
+
+    if name == "ratios":
+        from .ratio_study import ratios
+        return ratios
+
+    if name == "ratios_report":
+        from .ratio_study import ratios_report
+        return ratios_report
+
+    if name == "gini_stats":
+        from .gini import gini_stats
+        return gini_stats
+
+    if name == "gini_decomp":
+        from .gini import gini_decomp
+        return gini_decomp
+
+    if name == "gini_factors":
+        from .gini import gini_factors
+        return gini_factors
+
+    if name == "gini_lorenz_plot":
+        from .gini import gini_lorenz_plot
+        return gini_lorenz_plot
+
+    if name == "compare_ratios":
+        from .reporting import compare_ratios
+        return compare_ratios
+
+    if name == "vei_boxplot":
+        from .graphs import vei_boxplot
+        return vei_boxplot
+
+    if name == "vei_analysis":
+        from .indicators import vei_analysis
+        return vei_analysis
+
+    if name == "asr_median":
+        from .indicators import asr_median
+        return asr_median
+
+    if name == "asr_mean":
+        from .indicators import asr_mean
+        return asr_mean
+
+    if name == "cod":
+        from .indicators import cod
+        return cod
+
+    if name == "cod_residual":
+        from .indicators import cod_residual
+        return cod_residual
+
+    if name == "prd":
+        from .indicators import prd
+        return prd
+
+    if name == "prb":
+        from .indicators import prb
+        return prb
+
+    if name == "rmse":
+        from .indicators import rmse
+        return rmse
+
+    if name == "mae":
+        from .indicators import mae
+        return mae
+
+    if name == "mape":
+        from .indicators import mape
+        return mape
+
+    if name == "mdmape":
+        from .indicators import mdmape
+        return mdmape
+
+    if name == "fsd":
+        from .indicators import fsd
+        return fsd
+
+    if name == "CoV_adj":
+        from .indicators import CoV_adj
+        return CoV_adj
+
+    if name == "CoC":
+        from .indicators import CoC
+        return CoC
+
+    if name == "compute_median_ci":
+        from .confint import compute_median_ci
+        return compute_median_ci
+
+    if name == "compute_median_ci_on_binomial":
+        from .confint import compute_median_ci_on_binomial
+        return compute_median_ci_on_binomial
+
+    # ── Blinder-Oaxaca decomposition ──────────────────────────
+    if name == "bo_decompose":
+        from .blinder_oaxaca import bo_decompose
+        return bo_decompose
+
+    if name == "bo_multi_decomposition":
+        from .blinder_oaxaca import bo_multi_decomposition
+        return bo_multi_decomposition
+
+    if name == "bo_format_table":
+        from .blinder_oaxaca import bo_format_table
+        return bo_format_table
+
+    if name == "bo_coefficient_plot":
+        from .blinder_oaxaca import bo_coefficient_plot
+        return bo_coefficient_plot
+
+    if name == "bo_decomposition_plot":
+        from .blinder_oaxaca import bo_decomposition_plot
+        return bo_decomposition_plot
+
+    if name == "bo_detail_plot":
+        from .blinder_oaxaca import bo_detail_plot
+        return bo_detail_plot
+
+    raise AttributeError(f"module {__name__} has no attribute {name}")
+
+
+# from __future__ import annotations
+
+# from ratio_study._version import __version__
+# from ratio_study.presets import (
+#     IAAO_INCOME_PRODUCING,
+#     IAAO_RESIDENTIAL,
+#     IAAO_VACANT_LAND,
+#     KNOWN_INDICATORS,
+#     MPAC_DEFAULT,
+#     STRICT,
+#     BootstrapConfig,
+#     ExcelConfig,
+#     GiniConfig,
+#     GraphsConfig,
+#     PdfConfig,
+#     RatioStudyConfig,
+# )
+
+# # Phase 2+ imports will be added here as modules are created.
+# # e.g.:
+# # from ratio_study.ratio_study import ratios, ratios_report, analyze
+# # from ratio_study.ratio_study import gini_stats, gini_decomp, vei_analysis
+
+# __all__ = [
+#     "__version__",
+#     # config models
+#     "RatioStudyConfig",
+#     "BootstrapConfig",
+#     "GiniConfig",
+#     "PdfConfig",
+#     "GraphsConfig",
+#     "ExcelConfig",
+#     "KNOWN_INDICATORS",
+#     # presets
+#     "IAAO_RESIDENTIAL",
+#     "IAAO_INCOME_PRODUCING",
+#     "IAAO_VACANT_LAND",
+#     "STRICT",
+#     "MPAC_DEFAULT",
+# ]

ratio_study/_data.py

@@ -0,0 +1,25 @@
+"""Internal helpers for accessing packaged data files."""
+from importlib import resources
+from pathlib import Path
+import pandas as pd
+
+
+def sample_dataset_path() -> Path:
+    """Return a filesystem path to the bundled sample dataset.
+
+    Works whether the package is installed normally, in editable mode,
+    or run from a wheel/zip.
+    """
+    # files() returns a Traversable; for parquet we need a real path
+    # because pyarrow/fastparquet read from disk
+    data_files = resources.files("ratio_study").joinpath(
+        "data", "ratio_study_sample_dataset.parquet"
+    )
+    # as_file() materializes to disk if needed (e.g., inside a zip)
+    with resources.as_file(data_files) as p:
+        return Path(p)
+
+
+def load_sample_dataset() -> pd.DataFrame:
+    """Load the bundled sample dataset as a pandas DataFrame."""
+    return pd.read_parquet(sample_dataset_path())

ratio_study/_version.py

@@ -0,0 +1,3 @@
+from __future__ import annotations
+
+__version__ = "0.3.0"