hmda-analyzer 0.1.0__tar.gz

hmda_analyzer-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,113 @@
+# 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/hmda_analyzer.egg-info/PKG-INFO

@@ -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/hmda_analyzer.egg-info/SOURCES.txt

@@ -0,0 +1,25 @@
+README.md
+pyproject.toml
+setup.py
+hmda_analyzer.egg-info/PKG-INFO
+hmda_analyzer.egg-info/SOURCES.txt
+hmda_analyzer.egg-info/dependency_links.txt
+hmda_analyzer.egg-info/requires.txt
+hmda_analyzer.egg-info/top_level.txt
+hmdaanalyzer/__init__.py
+hmdaanalyzer/analysis/__init__.py
+hmdaanalyzer/analysis/disparity.py
+hmdaanalyzer/analysis/geographic.py
+hmdaanalyzer/analysis/lender.py
+hmdaanalyzer/data/__init__.py
+hmdaanalyzer/data/loader.py
+hmdaanalyzer/data/schema.py
+hmdaanalyzer/report/__init__.py
+hmdaanalyzer/report/generator.py
+tests/__init__.py
+tests/conftest.py
+tests/test_disparity.py
+tests/test_geographic.py
+tests/test_lender.py
+tests/test_loader.py
+tests/test_report.py

hmda_analyzer-0.1.0/hmda_analyzer.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

hmda_analyzer-0.1.0/hmda_analyzer.egg-info/requires.txt

@@ -0,0 +1,3 @@
+pandas>=1.4.0
+numpy>=1.21.0
+requests>=2.27.0

hmda_analyzer-0.1.0/hmda_analyzer.egg-info/top_level.txt

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

hmda_analyzer-0.1.0/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",
+]

hmda_analyzer-0.1.0/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

hmda_analyzer-0.1.0/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)