hmda-analyzer 0.1.0__py3-none-any.whl

hmda_analyzer-0.1.0.dist-info/METADATA

@@ -0,0 +1,125 @@
+Metadata-Version: 2.4
+Name: hmda-analyzer
+Version: 0.1.0
+Summary: HMDA mortgage lending disparity analyzer — denial rates, racial disparities, lending deserts, and lender benchmarking
+License: MIT
+Project-URL: Homepage, https://github.com/Jaypatel1511/hmda-analyzer
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: pandas>=1.4.0
+Requires-Dist: numpy>=1.21.0
+Requires-Dist: requests>=2.27.0
+
+# hmda-analyzer 📊
+
+**HMDA mortgage lending disparity analyzer.**
+
+Compute denial rate disparities by race, identify lending deserts, benchmark lenders
+against peers, and generate fair lending analysis reports — using CFPB HMDA LAR data.
+Free public API, no authentication required.
+
+---
+
+## Why hmda-analyzer?
+
+HMDA data covers 10+ million mortgage applications per year with borrower demographics,
+denial rates, loan amounts, and census tract locations. It is the most powerful public
+dataset for analyzing mortgage lending disparities — but it requires significant
+engineering to use. hmda-analyzer makes it accessible in Python.
+
+---
+
+## Installation
+
+    pip install hmda-analyzer
+
+---
+
+## Quickstart
+
+    from hmdaanalyzer import (
+        load_sample, denial_rate_by_race, disparity_ratio,
+        lending_by_tract, lender_summary, generate_disparity_report,
+    )
+
+    # Load sample data (no API required)
+    df = load_sample(n=5000)
+
+    # Or load from CFPB API (real data)
+    # df = load_from_api(year=2023, state="IL")
+
+    # Denial rates by race
+    rates = denial_rate_by_race(df)
+    print(rates)
+
+    # Disparity ratios vs White applicants
+    disparities = disparity_ratio(df)
+    print(disparities)
+
+    # Geographic analysis
+    tracts = lending_by_tract(df)
+    deserts = lending_by_tract(df)
+
+    # Lender analysis
+    summary = lender_summary(df, lei="LEI000001")
+
+    # Full disparity report
+    report = generate_disparity_report(df, title="Illinois Mortgage Market 2023")
+    print(report)
+
+---
+
+## Analyses Supported
+
+- Denial rate by race and ethnicity
+- Disparity ratios vs reference group (default: White applicants)
+- Denial rate by income band
+- Denial reasons by race
+- Lending activity by census tract, county, and state
+- Lending desert identification (low application volume tracts)
+- Lender vs market comparison
+- Top lenders by origination volume
+
+---
+
+## Disparity Ratio Thresholds
+
+Based on CFPB fair lending examination standards:
+
+- >= 2.0x — HIGH disparity (triggers regulatory scrutiny)
+- >= 1.5x — MODERATE disparity
+- < 1.5x — LOW disparity
+- < 1.0x — FAVORABLE (group has lower denial rate than reference)
+
+---
+
+## Data Sources
+
+CFPB HMDA Data Browser API — free, no API key required.
+2024 data covers 4,908 institutions and millions of loan applications.
+
+    https://ffiec.cfpb.gov/data-browser/
+
+---
+
+## Running Tests
+
+    PYTHONPATH=. pytest tests/ -v
+
+28 tests across all modules.
+
+---
+
+## Who This Is For
+
+- Fair lending analysts and compliance teams at banks and CDFIs
+- Community reinvestment researchers studying mortgage disparities
+- Journalists covering housing discrimination and redlining
+- Regulators and examiners analyzing lender performance
+- Academics studying racial wealth gaps and homeownership barriers
+
+---
+
+## License
+
+MIT 2026 Jaypatel1511

hmda_analyzer-0.1.0.dist-info/RECORD

@@ -0,0 +1,21 @@
+hmdaanalyzer/__init__.py,sha256=TJuAUuk9uX7UgW8pwqvTMF27bFbjqQL5WJCkRoWqrhs,1034
+hmdaanalyzer/analysis/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+hmdaanalyzer/analysis/disparity.py,sha256=0kxcvw3SIWP_SAnPGGD0bC7tb3aQTkJFNVHZO3byWW8,4165
+hmdaanalyzer/analysis/geographic.py,sha256=J5Mfd6mnAtO-wUCmLbFpyJqecZEuYC2aJ7g7YdmcKhY,4140
+hmdaanalyzer/analysis/lender.py,sha256=k5DYRIwLuCdn0TmhrahTWWIM898uCpWN99yNA5CJZ68,3336
+hmdaanalyzer/data/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+hmdaanalyzer/data/loader.py,sha256=XFx3_VeGfczfTCit1rkz2dVkfvGZ5ArVsCFM8bWpT_E,6219
+hmdaanalyzer/data/schema.py,sha256=3Voi5ZRk5LtZiyJcn4J_Q9u4s-QB1fxL863PXMYzMIw,4991
+hmdaanalyzer/report/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+hmdaanalyzer/report/generator.py,sha256=ogefRB-5FgMUDyIYcjZIEkZEZspbWGXzfPAwJx2T7YI,4633
+tests/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+tests/conftest.py,sha256=PksNnhkWPOyqsMP7Au4HVa7LAQsAS5g0Etq7BjuIeOE,211
+tests/test_disparity.py,sha256=OUUmGwtsSB7H4YBKgNGHjfgecIUZaV7KTSZO1NGw2Q8,1901
+tests/test_geographic.py,sha256=_Pj5LB2PRTwVbfX6t-xxotNzS-m5eF2CEpWW8ZQ3Iow,1157
+tests/test_lender.py,sha256=BStl8s1un1rENvZKzXFxebtJSTLBxrxnapeDCSYzRNg,1146
+tests/test_loader.py,sha256=LoBfXJmh64LFSc3qb6QFOKhckk4EW0R0qMSujQfaW2U,1329
+tests/test_report.py,sha256=HMbj707Jb7wfVdjhyZU9gtKJlmhLDiZ-yIMQ5gf0XAU,800
+hmda_analyzer-0.1.0.dist-info/METADATA,sha256=fdFw3qoUWOW6s4EbvQI8kBL-J8XzxXmJNR3MHgqjZic,3251
+hmda_analyzer-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+hmda_analyzer-0.1.0.dist-info/top_level.txt,sha256=co7d3qOb1t3FdKP69KBrETmXneiJ3zDhY9WijVeQ0cs,19
+hmda_analyzer-0.1.0.dist-info/RECORD,,

hmda_analyzer-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

hmda_analyzer-0.1.0.dist-info/top_level.txt

@@ -0,0 +1,2 @@
+hmdaanalyzer
+tests

hmdaanalyzer/__init__.py

@@ -0,0 +1,28 @@
+from hmdaanalyzer.data.loader import (
+    load_from_api, load_from_file, load_sample,
+)
+from hmdaanalyzer.analysis.disparity import (
+    denial_rate_by_race, disparity_ratio,
+    denial_rate_by_income_band, denial_reasons_by_race,
+)
+from hmdaanalyzer.analysis.geographic import (
+    lending_by_tract, lending_by_county, lending_by_state,
+    lending_desert_score, racial_composition_by_tract,
+)
+from hmdaanalyzer.analysis.lender import (
+    lender_summary, lender_vs_market, top_lenders_by_volume,
+)
+from hmdaanalyzer.report.generator import (
+    generate_disparity_report, summary_table,
+)
+
+__version__ = "0.1.0"
+__all__ = [
+    "load_from_api", "load_from_file", "load_sample",
+    "denial_rate_by_race", "disparity_ratio",
+    "denial_rate_by_income_band", "denial_reasons_by_race",
+    "lending_by_tract", "lending_by_county", "lending_by_state",
+    "lending_desert_score", "racial_composition_by_tract",
+    "lender_summary", "lender_vs_market", "top_lenders_by_volume",
+    "generate_disparity_report", "summary_table",
+]

hmdaanalyzer/analysis/disparity.py

@@ -0,0 +1,128 @@
+"""
+Denial rate disparity analysis.
+Computes disparate impact ratios between racial/ethnic groups.
+"""
+import pandas as pd
+import numpy as np
+from hmdaanalyzer.data.schema import DISPARITY_THRESHOLDS, REFERENCE_RACE
+
+
+def denial_rate_by_race(df: pd.DataFrame) -> pd.DataFrame:
+    """
+    Compute denial rates by race for a HMDA LAR DataFrame.
+
+    Args:
+        df: Cleaned HMDA LAR DataFrame with is_denied and derived_race columns
+
+    Returns:
+        DataFrame with denial rates by race
+    """
+    if "derived_race" not in df.columns or "is_denied" not in df.columns:
+        raise ValueError("DataFrame must have 'derived_race' and 'is_denied' columns")
+
+    actionable = df[df["action_taken"].isin([1, 2, 3])].copy()
+
+    result = actionable.groupby("derived_race").agg(
+        applications=("is_denied", "count"),
+        denials=("is_denied", "sum"),
+    ).reset_index()
+
+    result["denial_rate"] = result["denials"] / result["applications"]
+    result = result[result["applications"] >= 5]
+    result = result.sort_values("denial_rate", ascending=False)
+
+    return result
+
+
+def disparity_ratio(df: pd.DataFrame, reference: str = None) -> pd.DataFrame:
+    """
+    Compute disparity ratios relative to a reference group (default: White).
+
+    Disparity ratio = group denial rate / reference group denial rate
+    A ratio > 2.0 indicates high disparity (CFPB threshold).
+
+    Args:
+        df:        Cleaned HMDA LAR DataFrame
+        reference: Reference race group (default: "White")
+
+    Returns:
+        DataFrame with disparity ratios and severity flags
+    """
+    reference = reference or REFERENCE_RACE
+    denial_rates = denial_rate_by_race(df)
+
+    ref_row = denial_rates[denial_rates["derived_race"] == reference]
+    if ref_row.empty:
+        raise ValueError(f"Reference group '{reference}' not found in data.")
+
+    ref_rate = ref_row["denial_rate"].iloc[0]
+
+    result = denial_rates.copy()
+    result["reference_group"] = reference
+    result["reference_denial_rate"] = ref_rate
+    result["disparity_ratio"] = result["denial_rate"] / ref_rate if ref_rate > 0 else None
+
+    def classify(ratio):
+        if ratio is None or pd.isna(ratio):
+            return "N/A"
+        if ratio >= DISPARITY_THRESHOLDS["high"]:
+            return "HIGH"
+        elif ratio >= DISPARITY_THRESHOLDS["moderate"]:
+            return "MODERATE"
+        elif ratio < 1.0:
+            return "FAVORABLE"
+        return "LOW"
+
+    result["disparity_level"] = result["disparity_ratio"].apply(classify)
+    result = result.sort_values("disparity_ratio", ascending=False)
+
+    return result
+
+
+def denial_rate_by_income_band(df: pd.DataFrame) -> pd.DataFrame:
+    """
+    Compute denial rates by income band to identify income-based disparities.
+    """
+    df = df.copy()
+    df["income_band"] = pd.cut(
+        df["income"],
+        bins=[0, 50, 80, 120, 200, float("inf")],
+        labels=["<$50k", "$50-80k", "$80-120k", "$120-200k", "$200k+"],
+    )
+
+    actionable = df[df["action_taken"].isin([1, 2, 3])].copy()
+
+    result = actionable.groupby("income_band", observed=True).agg(
+        applications=("is_denied", "count"),
+        denials=("is_denied", "sum"),
+    ).reset_index()
+
+    result["denial_rate"] = result["denials"] / result["applications"]
+    return result
+
+
+def denial_reasons_by_race(df: pd.DataFrame) -> pd.DataFrame:
+    """
+    Analyze denial reasons broken down by race.
+    """
+    from hmdaanalyzer.data.schema import DENIAL_REASONS
+
+    denied = df[df["is_denied"] == True].copy()
+
+    if "denial_reason_1" not in denied.columns:
+        return pd.DataFrame()
+
+    denied["denial_reason_label"] = denied["denial_reason_1"].map(
+        lambda x: DENIAL_REASONS.get(int(x), "Unknown") if pd.notna(x) else "Unknown"
+    )
+
+    result = denied.groupby(
+        ["derived_race", "denial_reason_label"]
+    ).size().reset_index(name="count")
+
+    totals = denied.groupby("derived_race").size().reset_index(name="total")
+    result = result.merge(totals, on="derived_race")
+    result["pct"] = result["count"] / result["total"] * 100
+    result = result.sort_values(["derived_race", "pct"], ascending=[True, False])
+
+    return result

hmdaanalyzer/analysis/geographic.py

@@ -0,0 +1,125 @@
+"""
+Geographic analysis of HMDA lending patterns.
+Identifies lending deserts and maps activity by census tract.
+"""
+import pandas as pd
+import numpy as np
+
+
+def lending_by_tract(df: pd.DataFrame) -> pd.DataFrame:
+    """
+    Aggregate HMDA lending activity by census tract.
+
+    Returns:
+        DataFrame with application counts, denial rates, and loan volumes by tract
+    """
+    if "census_tract" not in df.columns:
+        raise ValueError("DataFrame must have 'census_tract' column")
+
+    actionable = df[df["action_taken"].isin([1, 2, 3])].copy()
+
+    result = actionable.groupby("census_tract").agg(
+        applications=("is_denied", "count"),
+        denials=("is_denied", "sum"),
+        originations=("is_approved", "sum"),
+        avg_loan_amount=("loan_amount", "mean"),
+        median_income=("income", "median"),
+    ).reset_index()
+
+    result["denial_rate"] = result["denials"] / result["applications"]
+    result["origination_rate"] = result["originations"] / result["applications"]
+
+    return result.sort_values("applications", ascending=False)
+
+
+def lending_by_county(df: pd.DataFrame) -> pd.DataFrame:
+    """
+    Aggregate HMDA lending activity by county.
+    """
+    if "county_code" not in df.columns:
+        raise ValueError("DataFrame must have 'county_code' column")
+
+    actionable = df[df["action_taken"].isin([1, 2, 3])].copy()
+
+    result = actionable.groupby("county_code").agg(
+        applications=("is_denied", "count"),
+        denials=("is_denied", "sum"),
+        originations=("is_approved", "sum"),
+        total_loan_volume=("loan_amount", "sum"),
+        avg_loan_amount=("loan_amount", "mean"),
+    ).reset_index()
+
+    result["denial_rate"] = result["denials"] / result["applications"]
+    result["state_code"] = result["county_code"].str[:2]
+
+    return result.sort_values("applications", ascending=False)
+
+
+def lending_desert_score(df: pd.DataFrame) -> pd.DataFrame:
+    """
+    Identify census tracts with abnormally low application volumes.
+    A 'lending desert' is a tract with very few mortgage applications
+    relative to its expected volume based on housing units.
+
+    Returns:
+        DataFrame with lending desert scores by census tract
+    """
+    tract_df = lending_by_tract(df)
+
+    # Percentile rank by application volume
+    tract_df["app_percentile"] = (
+        tract_df["applications"].rank(pct=True) * 100
+    ).round(1)
+
+    # Low denial rate + low application volume = potential lending desert
+    # (lenders may be avoiding the area entirely)
+    tract_df["desert_score"] = (
+        (100 - tract_df["app_percentile"]) * 0.6 +
+        tract_df["denial_rate"] * 100 * 0.4
+    ).round(1)
+
+    tract_df["is_lending_desert"] = (
+        (tract_df["app_percentile"] < 25) &
+        (tract_df["denial_rate"] > 0.15)
+    )
+
+    return tract_df.sort_values("desert_score", ascending=False)
+
+
+def racial_composition_by_tract(df: pd.DataFrame) -> pd.DataFrame:
+    """
+    Show racial composition of applicants by census tract.
+    Useful for identifying tracts where lending may differ by applicant race.
+    """
+    if "derived_race" not in df.columns or "census_tract" not in df.columns:
+        return pd.DataFrame()
+
+    result = df.groupby(
+        ["census_tract", "derived_race"]
+    ).agg(
+        applications=("is_denied", "count"),
+        denial_rate=("is_denied", "mean"),
+    ).reset_index()
+
+    return result.sort_values(["census_tract", "applications"], ascending=[True, False])
+
+
+def lending_by_state(df: pd.DataFrame) -> pd.DataFrame:
+    """
+    Aggregate lending activity by state.
+    """
+    state_col = "state_code" if "state_code" in df.columns else None
+    if state_col is None:
+        return pd.DataFrame()
+
+    actionable = df[df["action_taken"].isin([1, 2, 3])].copy()
+
+    result = actionable.groupby(state_col).agg(
+        applications=("is_denied", "count"),
+        denials=("is_denied", "sum"),
+        originations=("is_approved", "sum"),
+        total_volume=("loan_amount", "sum"),
+    ).reset_index()
+
+    result["denial_rate"] = result["denials"] / result["applications"]
+    return result.sort_values("applications", ascending=False)

hmdaanalyzer/analysis/lender.py

@@ -0,0 +1,109 @@
+"""
+Lender-level HMDA analysis.
+Compare a lender's performance against market peers.
+"""
+import pandas as pd
+from hmdaanalyzer.analysis.disparity import denial_rate_by_race, disparity_ratio
+
+
+def lender_summary(df: pd.DataFrame, lei: str = None) -> dict:
+    """
+    Compute summary statistics for a single lender.
+
+    Args:
+        df:  HMDA LAR DataFrame (filtered to lender or full market)
+        lei: Lender LEI to filter to (optional)
+
+    Returns:
+        Dict with key lender performance metrics
+    """
+    if lei and "lei" in df.columns:
+        df = df[df["lei"] == lei]
+
+    if df.empty:
+        return {}
+
+    actionable = df[df["action_taken"].isin([1, 2, 3])]
+    total = len(actionable)
+    if total == 0:
+        return {}
+
+    return {
+        "total_applications":   total,
+        "originations":         int(actionable["is_approved"].sum()),
+        "denials":              int(actionable["is_denied"].sum()),
+        "approval_rate":        round(actionable["is_approved"].mean() * 100, 2),
+        "denial_rate":          round(actionable["is_denied"].mean() * 100, 2),
+        "avg_loan_amount":      round(actionable["loan_amount"].mean(), 0),
+        "median_loan_amount":   round(actionable["loan_amount"].median(), 0),
+        "avg_applicant_income": round(actionable["income"].mean(), 0),
+        "unique_tracts":        actionable["census_tract"].nunique(),
+        "unique_counties":      actionable["county_code"].nunique(),
+    }
+
+
+def lender_vs_market(
+    df: pd.DataFrame,
+    lei: str,
+) -> pd.DataFrame:
+    """
+    Compare a lender's denial rates against the overall market
+    by racial group.
+
+    Args:
+        df:  Full market HMDA LAR DataFrame
+        lei: Lender LEI to compare
+
+    Returns:
+        DataFrame showing lender vs market denial rates by race
+    """
+    lender_df = df[df["lei"] == lei] if "lei" in df.columns else df
+
+    lender_rates = denial_rate_by_race(lender_df).rename(
+        columns={"denial_rate": "lender_denial_rate",
+                 "applications": "lender_applications",
+                 "denials": "lender_denials"}
+    )
+
+    market_rates = denial_rate_by_race(df).rename(
+        columns={"denial_rate": "market_denial_rate",
+                 "applications": "market_applications",
+                 "denials": "market_denials"}
+    )
+
+    result = lender_rates.merge(
+        market_rates[["derived_race", "market_denial_rate"]],
+        on="derived_race", how="left"
+    )
+
+    result["vs_market"] = (
+        result["lender_denial_rate"] - result["market_denial_rate"]
+    )
+    result["vs_market_pct"] = (result["vs_market"] * 100).round(2)
+
+    return result.sort_values("lender_denial_rate", ascending=False)
+
+
+def top_lenders_by_volume(
+    df: pd.DataFrame,
+    n: int = 10,
+    state: str = None,
+) -> pd.DataFrame:
+    """
+    Rank lenders by origination volume.
+    """
+    if state and "state_code" in df.columns:
+        df = df[df["state_code"] == state]
+
+    originated = df[df["action_taken"] == 1]
+
+    if "lei" not in originated.columns:
+        return pd.DataFrame()
+
+    result = originated.groupby("lei").agg(
+        originations=("loan_amount", "count"),
+        total_volume=("loan_amount", "sum"),
+        avg_loan=("loan_amount", "mean"),
+    ).reset_index()
+
+    return result.sort_values("originations", ascending=False).head(n)

hmdaanalyzer/data/loader.py

@@ -0,0 +1,186 @@
+"""
+Load HMDA LAR data from CFPB Data Browser API or local CSV.
+Free public API — no authentication required.
+"""
+import os
+import requests
+import pandas as pd
+from pathlib import Path
+from hmdaanalyzer.data.schema import (
+    HMDA_API_BASE, CACHE_DIR, ACTION_TAKEN,
+    APPROVED_ACTIONS, DENIED_ACTIONS,
+    RACE_CODES, ETHNICITY_CODES, LOAN_PURPOSE, LOAN_TYPE,
+)
+
+
+def get_cache_dir() -> Path:
+    path = Path(CACHE_DIR)
+    path.mkdir(parents=True, exist_ok=True)
+    return path
+
+
+def load_from_api(
+    year: int = 2023,
+    state: str = None,
+    lei: str = None,
+    county: str = None,
+    limit: int = 10_000,
+) -> pd.DataFrame:
+    """
+    Load HMDA LAR data from CFPB Data Browser API.
+
+    Args:
+        year:   Data year e.g. 2023
+        state:  Two-letter state code e.g. "IL"
+        lei:    Lender LEI identifier
+        county: County FIPS code e.g. "17031"
+        limit:  Max records to fetch
+
+    Returns:
+        Clean pandas DataFrame with standardized columns
+    """
+    params = {
+        "years": year,
+        "actions_taken": "1,2,3,4,5",
+        "limit": min(limit, 1_000_000),
+    }
+    if state:
+        params["states"] = state.upper()
+    if lei:
+        params["leis"] = lei
+    if county:
+        params["counties"] = county
+
+    url = f"{HMDA_API_BASE}/csv"
+
+    try:
+        print(f"Fetching HMDA data from CFPB API (year={year})...")
+        r = requests.get(url, params=params, timeout=120, stream=True)
+        r.raise_for_status()
+
+        from io import StringIO
+        content = r.content.decode("utf-8")
+        df = pd.read_csv(StringIO(content), dtype=str, low_memory=False)
+        print(f"Loaded {len(df):,} LAR records")
+        return _clean(df)
+
+    except Exception as e:
+        print(f"API error: {e}. Use load_sample() for testing.")
+        return pd.DataFrame()
+
+
+def load_from_file(path: str) -> pd.DataFrame:
+    """
+    Load HMDA LAR data from a local CSV file.
+    Compatible with CFPB modified LAR files.
+    """
+    print(f"Loading HMDA data from {path}...")
+    df = pd.read_csv(path, dtype=str, low_memory=False)
+    print(f"Loaded {len(df):,} LAR records")
+    return _clean(df)
+
+
+def load_sample(n: int = 5000, seed: int = 42) -> pd.DataFrame:
+    """
+    Generate synthetic HMDA LAR data for testing and demos.
+    Realistic distribution based on 2023 national HMDA statistics.
+    No internet connection required.
+    """
+    import numpy as np
+    rng = np.random.default_rng(seed)
+
+    states = ["IL", "NY", "CA", "TX", "GA", "NC", "OH", "PA", "FL", "MI"]
+    leis = [f"LEI{i:06d}" for i in range(1, 11)]
+
+    # Realistic denial rates by race (based on 2023 HMDA national data)
+    race_denial_rates = {
+        "White":                       0.095,
+        "Black or African American":   0.195,
+        "Asian":                       0.090,
+        "Hispanic or Latino":          0.145,
+        "American Indian or Alaska Native": 0.175,
+        "Native Hawaiian or Other Pacific Islander": 0.160,
+    }
+
+    races = list(race_denial_rates.keys())
+    race_weights = [0.65, 0.13, 0.07, 0.10, 0.02, 0.03]
+
+    records = []
+    for i in range(n):
+        race = rng.choice(races, p=race_weights)
+        denial_prob = race_denial_rates[race]
+
+        # Income and loan amount correlated
+        income = max(20, rng.normal(85, 45))
+        loan_amount = max(50, income * rng.uniform(2.5, 5.5))
+
+        # Action taken based on race denial probability
+        r = rng.random()
+        if r < denial_prob:
+            action = 3
+        elif r < denial_prob + 0.05:
+            action = 4
+        else:
+            action = 1
+
+        state = rng.choice(states)
+        county_num = rng.integers(1, 200)
+        state_fips = {
+            "IL": "17", "NY": "36", "CA": "06", "TX": "48",
+            "GA": "13", "NC": "37", "OH": "39", "PA": "42",
+            "FL": "12", "MI": "26",
+        }[state]
+        county_code = f"{state_fips}{county_num:03d}"
+        tract = f"{county_code}{rng.integers(100000, 999999)}"
+
+        records.append({
+            "action_taken": str(action),
+            "loan_type": str(rng.choice([1, 1, 1, 2, 3], p=[0.7, 0.1, 0.1, 0.05, 0.05])),
+            "loan_purpose": str(rng.choice([1, 31, 32, 2], p=[0.5, 0.3, 0.15, 0.05])),
+            "loan_amount": str(round(loan_amount)),
+            "income": str(round(income)),
+            "derived_race": race,
+            "derived_ethnicity": (
+                "Hispanic or Latino" if race == "Hispanic or Latino"
+                else "Not Hispanic or Latino"
+            ),
+            "derived_sex": rng.choice(["Male", "Female", "Joint"], p=[0.45, 0.3, 0.25]),
+            "census_tract": tract,
+            "county_code": county_code,
+            "state_code": state_fips,
+            "denial_reason_1": str(rng.choice([1, 3, 4, 9, 10], p=[0.3, 0.25, 0.2, 0.15, 0.1])) if action == 3 else "10",
+            "interest_rate": str(round(rng.uniform(5.5, 8.5), 2)) if action == 1 else "",
+            "rate_spread": str(round(rng.uniform(-0.5, 2.0), 2)) if action == 1 else "",
+            "lei": rng.choice(leis),
+            "activity_year": "2023",
+        })
+
+    df = pd.DataFrame(records)
+    return _clean(df)
+
+
+def _clean(df: pd.DataFrame) -> pd.DataFrame:
+    """Standardize and clean a raw HMDA LAR DataFrame."""
+    df.columns = df.columns.str.lower().str.strip()
+
+    numeric_cols = ["loan_amount", "income", "interest_rate", "rate_spread"]
+    for col in numeric_cols:
+        if col in df.columns:
+            df[col] = pd.to_numeric(df[col], errors="coerce")
+
+    int_cols = ["action_taken", "loan_type", "loan_purpose",
+                "denial_reason_1", "denial_reason_2"]
+    for col in int_cols:
+        if col in df.columns:
+            df[col] = pd.to_numeric(df[col], errors="coerce").astype("Int64")
+
+    if "action_taken" in df.columns:
+        df["is_approved"] = df["action_taken"].isin(APPROVED_ACTIONS)
+        df["is_denied"] = df["action_taken"].isin(DENIED_ACTIONS)
+
+    if "derived_race" not in df.columns and "applicant_race_1" in df.columns:
+        df["derived_race"] = df["applicant_race_1"].map(
+            lambda x: RACE_CODES.get(int(x), "Unknown") if pd.notna(x) else "Unknown"
+        )
+
+    return df.reset_index(drop=True)

hmdaanalyzer/data/schema.py

@@ -0,0 +1,124 @@
+"""
+Constants, field mappings, and dataclasses for HMDA LAR data analysis.
+Based on 2024 HMDA Filing Instruction Guide (FIG) and CFPB Data Browser API.
+"""
+
+# ── CFPB HMDA Data Browser API ────────────────────────────────────────────────
+HMDA_API_BASE = "https://ffiec.cfpb.gov/v2/data-browser-api/view"
+HMDA_AGG_BASE = "https://ffiec.cfpb.gov/v2/data-browser-api/view/aggregations"
+
+# ── Action Taken Codes ────────────────────────────────────────────────────────
+ACTION_TAKEN = {
+    1: "Loan originated",
+    2: "Application approved but not accepted",
+    3: "Application denied",
+    4: "Application withdrawn by applicant",
+    5: "File closed for incompleteness",
+    6: "Purchased loan",
+    7: "Preapproval request denied",
+    8: "Preapproval request approved but not accepted",
+}
+
+APPROVED_ACTIONS = {1, 2, 8}
+DENIED_ACTIONS   = {3, 7}
+WITHDRAWN_ACTIONS = {4, 5}
+
+# ── Race Codes ────────────────────────────────────────────────────────────────
+RACE_CODES = {
+    1: "American Indian or Alaska Native",
+    2: "Asian",
+    3: "Black or African American",
+    4: "Native Hawaiian or Other Pacific Islander",
+    5: "White",
+    6: "Not applicable",
+    7: "Information not provided",
+}
+
+# ── Ethnicity Codes ───────────────────────────────────────────────────────────
+ETHNICITY_CODES = {
+    1: "Hispanic or Latino",
+    2: "Not Hispanic or Latino",
+    3: "Information not provided",
+    4: "Not applicable",
+}
+
+# ── Sex Codes ─────────────────────────────────────────────────────────────────
+SEX_CODES = {
+    1: "Male",
+    2: "Female",
+    3: "Information not provided",
+    4: "Not applicable",
+    6: "Both male and female",
+}
+
+# ── Loan Type Codes ───────────────────────────────────────────────────────────
+LOAN_TYPE = {
+    1: "Conventional",
+    2: "FHA",
+    3: "VA",
+    4: "RHS/FSA",
+}
+
+# ── Loan Purpose Codes ────────────────────────────────────────────────────────
+LOAN_PURPOSE = {
+    1: "Home purchase",
+    2: "Home improvement",
+    31: "Refinancing",
+    32: "Cash-out refinancing",
+    4: "Other purpose",
+    5: "Not applicable",
+}
+
+# ── Denial Reason Codes ───────────────────────────────────────────────────────
+DENIAL_REASONS = {
+    1: "Debt-to-income ratio",
+    2: "Employment history",
+    3: "Credit history",
+    4: "Collateral",
+    5: "Insufficient cash (downpayment, closing costs)",
+    6: "Unverifiable information",
+    7: "Credit application incomplete",
+    8: "Mortgage insurance denied",
+    9: "Other",
+    10: "Not applicable",
+}
+
+# ── Key LAR Fields We Use ─────────────────────────────────────────────────────
+LAR_FIELDS = [
+    "action_taken",
+    "loan_type",
+    "loan_purpose",
+    "loan_amount",
+    "income",
+    "applicant_race_1",
+    "applicant_ethnicity_1",
+    "applicant_sex",
+    "derived_race",
+    "derived_ethnicity",
+    "derived_sex",
+    "census_tract",
+    "county_code",
+    "state_code",
+    "denial_reason_1",
+    "denial_reason_2",
+    "interest_rate",
+    "rate_spread",
+    "hoepa_status",
+    "lien_status",
+    "lei",
+    "activity_year",
+]
+
+# ── Cache Directory ───────────────────────────────────────────────────────────
+import os
+CACHE_DIR = os.path.join(os.path.expanduser("~"), ".hmdaanalyzer", "cache")
+
+# ── Disparity Thresholds ──────────────────────────────────────────────────────
+DISPARITY_THRESHOLDS = {
+    "high":     2.0,   # Denial rate ratio >= 2.0x = high disparity
+    "moderate": 1.5,   # Denial rate ratio >= 1.5x = moderate disparity
+    "low":      1.0,   # Below 1.0x = no disparity
+}
+
+# ── Reference Group for Disparity ────────────────────────────────────────────
+REFERENCE_RACE = "White"

hmdaanalyzer/report/generator.py

@@ -0,0 +1,147 @@
+"""
+Generate HMDA analysis reports.
+"""
+import pandas as pd
+from hmdaanalyzer.analysis.disparity import (
+    denial_rate_by_race, disparity_ratio, denial_rate_by_income_band
+)
+from hmdaanalyzer.analysis.geographic import (
+    lending_by_state, lending_by_county, lending_desert_score
+)
+from hmdaanalyzer.analysis.lender import lender_summary, lender_vs_market
+
+
+def generate_disparity_report(
+    df: pd.DataFrame,
+    title: str = "HMDA Disparity Analysis",
+    lei: str = None,
+) -> str:
+    """
+    Generate a full HMDA disparity analysis report as Markdown.
+    """
+    if lei and "lei" in df.columns:
+        analysis_df = df[df["lei"] == lei]
+        scope = f"Lender: {lei}"
+    else:
+        analysis_df = df
+        scope = "All Lenders"
+
+    total = len(analysis_df)
+    actionable = analysis_df[analysis_df["action_taken"].isin([1, 2, 3])]
+    year = analysis_df["activity_year"].iloc[0] if "activity_year" in analysis_df.columns else "N/A"
+
+    lines = [
+        f"# HMDA Lending Disparity Analysis Report",
+        f"## {title}",
+        "",
+        f"**Scope:** {scope}",
+        f"**Year:** {year}",
+        f"**Total Records:** {total:,}",
+        f"**Actionable Applications:** {len(actionable):,}",
+        "",
+        "---",
+        "",
+        "## Denial Rate by Race",
+        "",
+        "| Race/Ethnicity | Applications | Denials | Denial Rate |",
+        "|----------------|-------------|---------|-------------|",
+    ]
+
+    try:
+        rates = denial_rate_by_race(analysis_df)
+        for _, row in rates.iterrows():
+            lines.append(
+                f"| {row['derived_race']} | {row['applications']:,} | "
+                f"{int(row['denials']):,} | {row['denial_rate']*100:.1f}% |"
+            )
+    except Exception as e:
+        lines.append(f"| Error computing denial rates: {e} |")
+
+    lines += [
+        "",
+        "---",
+        "",
+        "## Disparity Ratios (vs White Applicants)",
+        "",
+        "A disparity ratio >= 2.0 indicates HIGH disparity (CFPB threshold).",
+        "A disparity ratio >= 1.5 indicates MODERATE disparity.",
+        "",
+        "| Race/Ethnicity | Denial Rate | Reference Rate | Disparity Ratio | Level |",
+        "|----------------|-------------|----------------|-----------------|-------|",
+    ]
+
+    try:
+        disp = disparity_ratio(analysis_df)
+        for _, row in disp.iterrows():
+            if row["derived_race"] == "White":
+                continue
+            ratio = f"{row['disparity_ratio']:.2f}x" if pd.notna(row.get("disparity_ratio")) else "N/A"
+            level_emoji = {
+                "HIGH": "🔴 HIGH",
+                "MODERATE": "🟡 MODERATE",
+                "LOW": "🟢 LOW",
+                "FAVORABLE": "✅ FAVORABLE",
+                "N/A": "—",
+            }.get(row.get("disparity_level", "N/A"), "—")
+
+            lines.append(
+                f"| {row['derived_race']} | "
+                f"{row['denial_rate']*100:.1f}% | "
+                f"{row['reference_denial_rate']*100:.1f}% | "
+                f"{ratio} | {level_emoji} |"
+            )
+    except Exception as e:
+        lines.append(f"| Error: {e} |")
+
+    lines += [
+        "",
+        "---",
+        "",
+        "## Denial Rate by Income Band",
+        "",
+        "| Income Band | Applications | Denial Rate |",
+        "|-------------|-------------|-------------|",
+    ]
+
+    try:
+        income_df = denial_rate_by_income_band(analysis_df)
+        for _, row in income_df.iterrows():
+            lines.append(
+                f"| {row['income_band']} | {row['applications']:,} | "
+                f"{row['denial_rate']*100:.1f}% |"
+            )
+    except Exception as e:
+        lines.append(f"| Error: {e} |")
+
+    lines += [
+        "",
+        "---",
+        "",
+        "## Key Findings",
+        "",
+    ]
+
+    try:
+        disp = disparity_ratio(analysis_df)
+        high = disp[disp.get("disparity_level", pd.Series()) == "HIGH"]
+        if not high.empty:
+            lines.append("**High Disparity Groups:**")
+            for _, row in high.iterrows():
+                if row["derived_race"] != "White":
+                    lines.append(
+                        f"- {row['derived_race']}: "
+                        f"{row['disparity_ratio']:.1f}x denial rate vs White applicants"
+                    )
+            lines.append("")
+    except Exception:
+        pass
+
+    return "\n".join(lines)
+
+
+def summary_table(df: pd.DataFrame) -> pd.DataFrame:
+    """Return denial rates and disparity ratios as a DataFrame."""
+    try:
+        return disparity_ratio(df)
+    except Exception:
+        return denial_rate_by_race(df)

tests/conftest.py

@@ -0,0 +1,12 @@
+import pytest
+from hmdaanalyzer.data.loader import load_sample
+
+
+@pytest.fixture
+def sample_df():
+    return load_sample(n=2000, seed=42)
+
+
+@pytest.fixture
+def small_df():
+    return load_sample(n=500, seed=42)

tests/test_disparity.py

@@ -0,0 +1,58 @@
+import pytest
+import pandas as pd
+from hmdaanalyzer.analysis.disparity import (
+    denial_rate_by_race, disparity_ratio,
+    denial_rate_by_income_band, denial_reasons_by_race,
+)
+
+
+def test_denial_rate_by_race_returns_df(sample_df):
+    result = denial_rate_by_race(sample_df)
+    assert isinstance(result, pd.DataFrame)
+    assert "denial_rate" in result.columns
+    assert "derived_race" in result.columns
+
+
+def test_denial_rate_by_race_values_valid(sample_df):
+    result = denial_rate_by_race(sample_df)
+    assert (result["denial_rate"] >= 0).all()
+    assert (result["denial_rate"] <= 1).all()
+
+
+def test_disparity_ratio_returns_df(sample_df):
+    result = disparity_ratio(sample_df)
+    assert isinstance(result, pd.DataFrame)
+    assert "disparity_ratio" in result.columns
+    assert "disparity_level" in result.columns
+
+
+def test_disparity_ratio_white_is_reference(sample_df):
+    result = disparity_ratio(sample_df, reference="White")
+    white_row = result[result["derived_race"] == "White"]
+    assert len(white_row) == 1
+    assert abs(white_row["disparity_ratio"].iloc[0] - 1.0) < 0.01
+
+
+def test_disparity_levels_valid(sample_df):
+    result = disparity_ratio(sample_df)
+    valid = {"HIGH", "MODERATE", "LOW", "FAVORABLE", "N/A"}
+    assert set(result["disparity_level"].unique()).issubset(valid)
+
+
+def test_black_disparity_high(sample_df):
+    result = disparity_ratio(sample_df)
+    black = result[result["derived_race"] == "Black or African American"]
+    if len(black) > 0:
+        assert black["disparity_ratio"].iloc[0] > 1.0
+
+
+def test_denial_rate_by_income_band(sample_df):
+    result = denial_rate_by_income_band(sample_df)
+    assert isinstance(result, pd.DataFrame)
+    assert "denial_rate" in result.columns
+    assert len(result) > 0
+
+
+def test_denial_reasons_by_race(sample_df):
+    result = denial_reasons_by_race(sample_df)
+    assert isinstance(result, pd.DataFrame)

tests/test_geographic.py

@@ -0,0 +1,38 @@
+import pytest
+import pandas as pd
+from hmdaanalyzer.analysis.geographic import (
+    lending_by_tract, lending_by_county, lending_by_state,
+    lending_desert_score,
+)
+
+
+def test_lending_by_tract_returns_df(sample_df):
+    result = lending_by_tract(sample_df)
+    assert isinstance(result, pd.DataFrame)
+    assert "denial_rate" in result.columns
+    assert "census_tract" in result.columns
+
+
+def test_lending_by_county_returns_df(sample_df):
+    result = lending_by_county(sample_df)
+    assert isinstance(result, pd.DataFrame)
+    assert "denial_rate" in result.columns
+
+
+def test_lending_by_state_returns_df(sample_df):
+    result = lending_by_state(sample_df)
+    assert isinstance(result, pd.DataFrame)
+    assert len(result) > 0
+
+
+def test_lending_desert_score_returns_df(sample_df):
+    result = lending_desert_score(sample_df)
+    assert isinstance(result, pd.DataFrame)
+    assert "desert_score" in result.columns
+    assert "is_lending_desert" in result.columns
+
+
+def test_denial_rates_between_0_and_1(sample_df):
+    result = lending_by_tract(sample_df)
+    assert (result["denial_rate"] >= 0).all()
+    assert (result["denial_rate"] <= 1).all()

tests/test_lender.py

@@ -0,0 +1,37 @@
+import pytest
+import pandas as pd
+from hmdaanalyzer.analysis.lender import (
+    lender_summary, lender_vs_market, top_lenders_by_volume,
+)
+
+
+def test_lender_summary_returns_dict(sample_df):
+    result = lender_summary(sample_df)
+    assert isinstance(result, dict)
+    assert "total_applications" in result
+    assert "denial_rate" in result
+
+
+def test_lender_summary_denial_rate_valid(sample_df):
+    result = lender_summary(sample_df)
+    assert 0 <= result["denial_rate"] <= 100
+
+
+def test_lender_vs_market_returns_df(sample_df):
+    lei = sample_df["lei"].iloc[0]
+    result = lender_vs_market(sample_df, lei)
+    assert isinstance(result, pd.DataFrame)
+    assert "lender_denial_rate" in result.columns
+    assert "market_denial_rate" in result.columns
+
+
+def test_top_lenders_by_volume_returns_df(sample_df):
+    result = top_lenders_by_volume(sample_df, n=5)
+    assert isinstance(result, pd.DataFrame)
+    assert len(result) <= 5
+
+
+def test_top_lenders_sorted_by_volume(sample_df):
+    result = top_lenders_by_volume(sample_df, n=10)
+    if len(result) > 1:
+        assert result["originations"].iloc[0] >= result["originations"].iloc[1]

tests/test_loader.py

@@ -0,0 +1,43 @@
+import pytest
+import pandas as pd
+from hmdaanalyzer.data.loader import load_sample
+
+
+def test_load_sample_returns_dataframe():
+    df = load_sample(n=100)
+    assert isinstance(df, pd.DataFrame)
+    assert len(df) == 100
+
+
+def test_load_sample_has_required_columns():
+    df = load_sample(n=100)
+    required = ["action_taken", "derived_race", "loan_amount",
+                "income", "is_denied", "is_approved"]
+    for col in required:
+        assert col in df.columns
+
+
+def test_load_sample_action_taken_valid():
+    df = load_sample(n=500)
+    valid = {1, 2, 3, 4, 5}
+    assert df["action_taken"].dropna().isin(valid).all()
+
+
+def test_load_sample_is_denied_bool():
+    df = load_sample(n=500)
+    assert str(df["is_denied"].dtype) in ("bool", "boolean")
+
+
+def test_load_sample_denial_rate_realistic():
+    df = load_sample(n=2000)
+    actionable = df[df["action_taken"].isin([1, 2, 3])]
+    overall_denial_rate = actionable["is_denied"].mean()
+    assert 0.05 < overall_denial_rate < 0.35
+
+
+def test_load_sample_race_disparity():
+    df = load_sample(n=3000)
+    actionable = df[df["action_taken"].isin([1, 2, 3])]
+    black = actionable[actionable["derived_race"] == "Black or African American"]
+    white = actionable[actionable["derived_race"] == "White"]
+    assert black["is_denied"].mean() > white["is_denied"].mean()

tests/test_report.py

@@ -0,0 +1,27 @@
+import pytest
+import pandas as pd
+from hmdaanalyzer.report.generator import generate_disparity_report, summary_table
+
+
+def test_generate_report_returns_string(sample_df):
+    report = generate_disparity_report(sample_df)
+    assert isinstance(report, str)
+    assert len(report) > 100
+
+
+def test_report_contains_sections(sample_df):
+    report = generate_disparity_report(sample_df)
+    assert "Denial Rate by Race" in report
+    assert "Disparity Ratios" in report
+    assert "Income Band" in report
+
+
+def test_report_contains_black_disparity(sample_df):
+    report = generate_disparity_report(sample_df)
+    assert "Black or African American" in report
+
+
+def test_summary_table_returns_df(sample_df):
+    df = summary_table(sample_df)
+    assert isinstance(df, pd.DataFrame)
+    assert len(df) > 0