nmtc-mapper 0.1.0__tar.gz

nmtc_mapper-0.1.0/PKG-INFO

@@ -0,0 +1,130 @@
+Metadata-Version: 2.4
+Name: nmtc-mapper
+Version: 0.1.0
+Summary: Automated NMTC eligibility checker — geocode addresses and check Low-Income Community status using CDFI Fund and Census data
+License: MIT
+Project-URL: Homepage, https://github.com/Jaypatel1511/nmtc-mapper
+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
+Requires-Dist: openpyxl>=3.0.0
+
+# nmtc-mapper 🗺️
+
+**Automated NMTC eligibility checker for addresses and census tracts.**
+
+Pass a DataFrame of addresses and get back a boolean column for NMTC eligibility,
+distress level, poverty rate, AMI ratio, and more — using official CDFI Fund and
+Census Bureau data. No manual lookups required.
+
+---
+
+## Why nmtc-mapper?
+
+The CDFI Fund provides a manual web tool (CIMS) for checking NMTC eligibility
+one address at a time. nmtc-mapper automates this — pass 10,000 addresses and
+get results in seconds, using the same official data source.
+
+---
+
+## Installation
+
+    pip install nmtc-mapper
+
+---
+
+## Quickstart
+
+    from nmtcmapper import NMTCMapper
+
+    mapper = NMTCMapper()
+
+    # Single address (geocodes automatically)
+    result = mapper.check_address("1234 S Michigan Ave, Chicago, IL 60605")
+    result.summary()
+    print(result.nmtc_eligible)    # True
+    print(result.distress_level)   # "severe"
+    print(result.poverty_rate)     # 0.38
+
+    # Known census tract (no geocoding needed)
+    result = mapper.check_tract("17031840100")
+    print(result.nmtc_eligible)    # True
+
+    # Batch — enrich a DataFrame of addresses
+    import pandas as pd
+    df = pd.read_csv("projects.csv")   # must have 'address' column
+    df = mapper.enrich(df, address_col="address")
+    print(df["nmtc_eligible"].value_counts())
+    print(df["distress_level"].value_counts())
+
+    # If you already have census tract IDs
+    df = mapper.enrich(df, tract_col="tract_id")
+
+    # Summary stats
+    mapper.eligible_count(df)
+
+---
+
+## Eligibility Rules (2016-2020 ACS — mandatory since Sept 1, 2024)
+
+A census tract qualifies as a Low-Income Community (LIC) if it meets ANY of:
+
+- Poverty rate >= 20%
+- Median Family Income <= 80% of metro/state AMI
+- Median Family Income <= 85% of state AMI (high migration rural counties)
+
+Distress levels:
+
+- deep     — Poverty >= 40% OR AMI <= 50% OR unemployment >= 2x national rate
+- severe   — Poverty >= 30% OR AMI <= 60% OR unemployment >= 1.5x national rate
+- lic      — NMTC eligible (meets LIC criteria)
+- ineligible — Does not qualify
+
+---
+
+## Data Sources
+
+- CDFI Fund 2016-2020 ACS Low-Income Community Eligibility File
+  https://www.cdfifund.gov/research-data
+- US Census Bureau Geocoding API (free, no API key required)
+  https://geocoding.geo.census.gov
+
+---
+
+## Output Columns
+
+After running .enrich(), your DataFrame will have:
+
+- nmtc_eligible (bool)
+- distress_level (str: deep / severe / lic / ineligible)
+- poverty_rate (float)
+- ami_ratio (float)
+- unemployment_rate (float)
+- is_non_metro (bool)
+- severe_distress (bool)
+- deep_distress (bool)
+
+---
+
+## Running Tests
+
+    PYTHONPATH=. pytest tests/ -v
+
+24 tests across all modules.
+
+---
+
+## Who This Is For
+
+- CDEs screening project locations for NMTC eligibility
+- CDFI analysts qualifying borrower locations at scale
+- Researchers analyzing geographic distribution of LIC tracts
+- Anyone replacing manual CIMS lookups with automated Python
+
+---
+
+## License
+
+MIT 2026 Jaypatel1511

nmtc_mapper-0.1.0/README.md

@@ -0,0 +1,117 @@
+# nmtc-mapper 🗺️
+
+**Automated NMTC eligibility checker for addresses and census tracts.**
+
+Pass a DataFrame of addresses and get back a boolean column for NMTC eligibility,
+distress level, poverty rate, AMI ratio, and more — using official CDFI Fund and
+Census Bureau data. No manual lookups required.
+
+---
+
+## Why nmtc-mapper?
+
+The CDFI Fund provides a manual web tool (CIMS) for checking NMTC eligibility
+one address at a time. nmtc-mapper automates this — pass 10,000 addresses and
+get results in seconds, using the same official data source.
+
+---
+
+## Installation
+
+    pip install nmtc-mapper
+
+---
+
+## Quickstart
+
+    from nmtcmapper import NMTCMapper
+
+    mapper = NMTCMapper()
+
+    # Single address (geocodes automatically)
+    result = mapper.check_address("1234 S Michigan Ave, Chicago, IL 60605")
+    result.summary()
+    print(result.nmtc_eligible)    # True
+    print(result.distress_level)   # "severe"
+    print(result.poverty_rate)     # 0.38
+
+    # Known census tract (no geocoding needed)
+    result = mapper.check_tract("17031840100")
+    print(result.nmtc_eligible)    # True
+
+    # Batch — enrich a DataFrame of addresses
+    import pandas as pd
+    df = pd.read_csv("projects.csv")   # must have 'address' column
+    df = mapper.enrich(df, address_col="address")
+    print(df["nmtc_eligible"].value_counts())
+    print(df["distress_level"].value_counts())
+
+    # If you already have census tract IDs
+    df = mapper.enrich(df, tract_col="tract_id")
+
+    # Summary stats
+    mapper.eligible_count(df)
+
+---
+
+## Eligibility Rules (2016-2020 ACS — mandatory since Sept 1, 2024)
+
+A census tract qualifies as a Low-Income Community (LIC) if it meets ANY of:
+
+- Poverty rate >= 20%
+- Median Family Income <= 80% of metro/state AMI
+- Median Family Income <= 85% of state AMI (high migration rural counties)
+
+Distress levels:
+
+- deep     — Poverty >= 40% OR AMI <= 50% OR unemployment >= 2x national rate
+- severe   — Poverty >= 30% OR AMI <= 60% OR unemployment >= 1.5x national rate
+- lic      — NMTC eligible (meets LIC criteria)
+- ineligible — Does not qualify
+
+---
+
+## Data Sources
+
+- CDFI Fund 2016-2020 ACS Low-Income Community Eligibility File
+  https://www.cdfifund.gov/research-data
+- US Census Bureau Geocoding API (free, no API key required)
+  https://geocoding.geo.census.gov
+
+---
+
+## Output Columns
+
+After running .enrich(), your DataFrame will have:
+
+- nmtc_eligible (bool)
+- distress_level (str: deep / severe / lic / ineligible)
+- poverty_rate (float)
+- ami_ratio (float)
+- unemployment_rate (float)
+- is_non_metro (bool)
+- severe_distress (bool)
+- deep_distress (bool)
+
+---
+
+## Running Tests
+
+    PYTHONPATH=. pytest tests/ -v
+
+24 tests across all modules.
+
+---
+
+## Who This Is For
+
+- CDEs screening project locations for NMTC eligibility
+- CDFI analysts qualifying borrower locations at scale
+- Researchers analyzing geographic distribution of LIC tracts
+- Anyone replacing manual CIMS lookups with automated Python
+
+---
+
+## License
+
+MIT 2026 Jaypatel1511

nmtc_mapper-0.1.0/nmtc_mapper.egg-info/PKG-INFO

@@ -0,0 +1,130 @@
+Metadata-Version: 2.4
+Name: nmtc-mapper
+Version: 0.1.0
+Summary: Automated NMTC eligibility checker — geocode addresses and check Low-Income Community status using CDFI Fund and Census data
+License: MIT
+Project-URL: Homepage, https://github.com/Jaypatel1511/nmtc-mapper
+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
+Requires-Dist: openpyxl>=3.0.0
+
+# nmtc-mapper 🗺️
+
+**Automated NMTC eligibility checker for addresses and census tracts.**
+
+Pass a DataFrame of addresses and get back a boolean column for NMTC eligibility,
+distress level, poverty rate, AMI ratio, and more — using official CDFI Fund and
+Census Bureau data. No manual lookups required.
+
+---
+
+## Why nmtc-mapper?
+
+The CDFI Fund provides a manual web tool (CIMS) for checking NMTC eligibility
+one address at a time. nmtc-mapper automates this — pass 10,000 addresses and
+get results in seconds, using the same official data source.
+
+---
+
+## Installation
+
+    pip install nmtc-mapper
+
+---
+
+## Quickstart
+
+    from nmtcmapper import NMTCMapper
+
+    mapper = NMTCMapper()
+
+    # Single address (geocodes automatically)
+    result = mapper.check_address("1234 S Michigan Ave, Chicago, IL 60605")
+    result.summary()
+    print(result.nmtc_eligible)    # True
+    print(result.distress_level)   # "severe"
+    print(result.poverty_rate)     # 0.38
+
+    # Known census tract (no geocoding needed)
+    result = mapper.check_tract("17031840100")
+    print(result.nmtc_eligible)    # True
+
+    # Batch — enrich a DataFrame of addresses
+    import pandas as pd
+    df = pd.read_csv("projects.csv")   # must have 'address' column
+    df = mapper.enrich(df, address_col="address")
+    print(df["nmtc_eligible"].value_counts())
+    print(df["distress_level"].value_counts())
+
+    # If you already have census tract IDs
+    df = mapper.enrich(df, tract_col="tract_id")
+
+    # Summary stats
+    mapper.eligible_count(df)
+
+---
+
+## Eligibility Rules (2016-2020 ACS — mandatory since Sept 1, 2024)
+
+A census tract qualifies as a Low-Income Community (LIC) if it meets ANY of:
+
+- Poverty rate >= 20%
+- Median Family Income <= 80% of metro/state AMI
+- Median Family Income <= 85% of state AMI (high migration rural counties)
+
+Distress levels:
+
+- deep     — Poverty >= 40% OR AMI <= 50% OR unemployment >= 2x national rate
+- severe   — Poverty >= 30% OR AMI <= 60% OR unemployment >= 1.5x national rate
+- lic      — NMTC eligible (meets LIC criteria)
+- ineligible — Does not qualify
+
+---
+
+## Data Sources
+
+- CDFI Fund 2016-2020 ACS Low-Income Community Eligibility File
+  https://www.cdfifund.gov/research-data
+- US Census Bureau Geocoding API (free, no API key required)
+  https://geocoding.geo.census.gov
+
+---
+
+## Output Columns
+
+After running .enrich(), your DataFrame will have:
+
+- nmtc_eligible (bool)
+- distress_level (str: deep / severe / lic / ineligible)
+- poverty_rate (float)
+- ami_ratio (float)
+- unemployment_rate (float)
+- is_non_metro (bool)
+- severe_distress (bool)
+- deep_distress (bool)
+
+---
+
+## Running Tests
+
+    PYTHONPATH=. pytest tests/ -v
+
+24 tests across all modules.
+
+---
+
+## Who This Is For
+
+- CDEs screening project locations for NMTC eligibility
+- CDFI analysts qualifying borrower locations at scale
+- Researchers analyzing geographic distribution of LIC tracts
+- Anyone replacing manual CIMS lookups with automated Python
+
+---
+
+## License
+
+MIT 2026 Jaypatel1511

nmtc_mapper-0.1.0/nmtc_mapper.egg-info/SOURCES.txt

@@ -0,0 +1,22 @@
+README.md
+pyproject.toml
+setup.py
+nmtc_mapper.egg-info/PKG-INFO
+nmtc_mapper.egg-info/SOURCES.txt
+nmtc_mapper.egg-info/dependency_links.txt
+nmtc_mapper.egg-info/requires.txt
+nmtc_mapper.egg-info/top_level.txt
+nmtcmapper/__init__.py
+nmtcmapper/mapper.py
+nmtcmapper/data/__init__.py
+nmtcmapper/data/loader.py
+nmtcmapper/data/schema.py
+nmtcmapper/eligibility/__init__.py
+nmtcmapper/eligibility/checker.py
+nmtcmapper/geocoder/__init__.py
+nmtcmapper/geocoder/census.py
+tests/__init__.py
+tests/conftest.py
+tests/test_checker.py
+tests/test_loader.py
+tests/test_mapper.py

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

@@ -0,0 +1 @@
+

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

@@ -0,0 +1,4 @@
+pandas>=1.4.0
+numpy>=1.21.0
+requests>=2.27.0
+openpyxl>=3.0.0

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

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

nmtc_mapper-0.1.0/nmtcmapper/__init__.py

@@ -0,0 +1,10 @@
+from nmtcmapper.mapper import NMTCMapper
+from nmtcmapper.eligibility.checker import EligibilityResult
+from nmtcmapper.data.loader import load_eligibility_table
+from nmtcmapper.geocoder.census import geocode_address
+
+__version__ = "0.1.0"
+__all__ = [
+    "NMTCMapper", "EligibilityResult",
+    "load_eligibility_table", "geocode_address",
+]

nmtc_mapper-0.1.0/nmtcmapper/data/loader.py

@@ -0,0 +1,156 @@
+"""
+Download and cache the CDFI Fund NMTC eligibility file.
+Builds a lookup table of all eligible census tracts.
+"""
+import os
+import requests
+import pandas as pd
+from pathlib import Path
+
+from nmtcmapper.data.schema import (
+    CACHE_DIR, CDFI_FUND_LIC_URL_2020,
+    ELIGIBILITY_FILE_COLUMNS,
+    LIC_POVERTY_RATE_THRESHOLD,
+    LIC_AMI_RATIO_METRO_THRESHOLD,
+    LIC_AMI_RATIO_RURAL_THRESHOLD,
+    SEVERE_POVERTY_THRESHOLD, SEVERE_AMI_THRESHOLD,
+    SEVERE_UNEMPLOYMENT_MULTIPLIER, NATIONAL_UNEMPLOYMENT_RATE,
+    DEEP_POVERTY_THRESHOLD, DEEP_AMI_THRESHOLD,
+    DEEP_UNEMPLOYMENT_MULTIPLIER,
+)
+
+
+def get_cache_dir() -> Path:
+    path = Path(CACHE_DIR)
+    path.mkdir(parents=True, exist_ok=True)
+    return path
+
+
+def _cache_path(filename: str) -> Path:
+    return get_cache_dir() / filename
+
+
+def download_eligibility_file(force: bool = False) -> Path:
+    filename = "NMTC_LIC_Eligibility_2016_2020.xlsx"
+    path = _cache_path(filename)
+    if path.exists() and not force:
+        print(f"Using cached eligibility file: {path}")
+        return path
+    print("Downloading NMTC eligibility file from CDFI Fund...")
+    try:
+        response = requests.get(CDFI_FUND_LIC_URL_2020, stream=True, timeout=120)
+        response.raise_for_status()
+        with open(path, "wb") as f:
+            for chunk in response.iter_content(chunk_size=8192):
+                f.write(chunk)
+        print(f"Saved to {path}")
+        return path
+    except Exception as e:
+        print(f"Download failed: {e}")
+        return None
+
+
+def load_eligibility_table(force: bool = False) -> pd.DataFrame:
+    path = download_eligibility_file(force=force)
+    if path is None or not path.exists():
+        print("Using built-in sample eligibility data.")
+        return _build_sample_table()
+    print(f"Loading eligibility table from {path}...")
+    try:
+        df = pd.read_excel(path, dtype=str)
+        return _process_eligibility_table(df)
+    except Exception as e:
+        print(f"Error loading file: {e}. Using sample data.")
+        return _build_sample_table()
+
+
+def _process_eligibility_table(df: pd.DataFrame) -> pd.DataFrame:
+    df.columns = df.columns.str.strip().str.upper()
+    col_map = {k: v for k, v in ELIGIBILITY_FILE_COLUMNS.items() if k in df.columns}
+    df = df.rename(columns=col_map)
+    if "tract_id" not in df.columns:
+        if all(c in df.columns for c in ["state", "county", "tract"]):
+            df["tract_id"] = (
+                df["state"].str.zfill(2) +
+                df["county"].str.zfill(3) +
+                df["tract"].str.zfill(6)
+            )
+    for col in ["poverty_rate", "ami_ratio", "unemployment_rate"]:
+        if col in df.columns:
+            df[col] = pd.to_numeric(df[col], errors="coerce")
+    for col in ["is_non_metro", "is_high_migration_rural"]:
+        if col in df.columns:
+            df[col] = df[col].isin({"Y", "YES", "1", "True", "TRUE", "X"})
+    df = _compute_eligibility(df)
+    if "tract_id" in df.columns:
+        df = df.set_index("tract_id")
+    print(f"Eligibility table loaded: {len(df):,} census tracts")
+    return df
+
+
+def _compute_eligibility(df: pd.DataFrame) -> pd.DataFrame:
+    pr = df.get("poverty_rate", pd.Series(dtype=float))
+    ami = df.get("ami_ratio", pd.Series(dtype=float))
+    unemp = df.get("unemployment_rate", pd.Series(dtype=float))
+    non_metro = df.get("is_non_metro", pd.Series(False, index=df.index))
+
+    poverty_lic = pr >= LIC_POVERTY_RATE_THRESHOLD
+    ami_lic = (
+        (non_metro & (ami <= LIC_AMI_RATIO_RURAL_THRESHOLD)) |
+        (~non_metro & (ami <= LIC_AMI_RATIO_METRO_THRESHOLD))
+    )
+    df["nmtc_eligible"] = poverty_lic | ami_lic
+
+    sev_poverty = pr >= SEVERE_POVERTY_THRESHOLD
+    sev_ami = ami <= SEVERE_AMI_THRESHOLD
+    sev_unemp = unemp >= (NATIONAL_UNEMPLOYMENT_RATE * SEVERE_UNEMPLOYMENT_MULTIPLIER)
+    df["severe_distress"] = sev_poverty | sev_ami | sev_unemp
+
+    deep_poverty = pr >= DEEP_POVERTY_THRESHOLD
+    deep_ami = ami <= DEEP_AMI_THRESHOLD
+    deep_unemp = unemp >= (NATIONAL_UNEMPLOYMENT_RATE * DEEP_UNEMPLOYMENT_MULTIPLIER)
+    df["deep_distress"] = deep_poverty | deep_ami | deep_unemp
+
+    def distress_label(row):
+        if row.get("deep_distress"):
+            return "deep"
+        elif row.get("severe_distress"):
+            return "severe"
+        elif row.get("nmtc_eligible"):
+            return "lic"
+        return "ineligible"
+
+    df["distress_level"] = df.apply(distress_label, axis=1)
+    return df
+
+
+def _build_sample_table() -> pd.DataFrame:
+    sample_tracts = [
+        ("17031840100", 0.38, 0.55, 0.12, False, False),
+        ("17031839100", 0.42, 0.48, 0.15, False, False),
+        ("17031010100", 0.18, 0.92, 0.04, False, False),
+        ("36061015900", 0.35, 0.60, 0.11, False, False),
+        ("36061019100", 0.28, 0.72, 0.09, False, False),
+        ("36047052200", 0.14, 0.88, 0.05, False, False),
+        ("26163518300", 0.45, 0.45, 0.18, False, False),
+        ("26163520100", 0.32, 0.62, 0.13, False, False),
+        ("13121010400", 0.29, 0.68, 0.10, False, False),
+        ("48113010900", 0.22, 0.78, 0.07, False, False),
+        ("17019000100", 0.15, 0.95, 0.03, True,  True),
+        ("26001010100", 0.18, 0.88, 0.06, True,  False),
+    ]
+    rows = []
+    for tid, pr, ami, unemp, non_metro, high_migration in sample_tracts:
+        rows.append({
+            "tract_id": tid,
+            "state": tid[:2],
+            "poverty_rate": pr,
+            "ami_ratio": ami,
+            "unemployment_rate": unemp,
+            "is_non_metro": non_metro,
+            "is_high_migration_rural": high_migration,
+        })
+    df = pd.DataFrame(rows)
+    df = _compute_eligibility(df)
+    df = df.set_index("tract_id")
+    return df

nmtc_mapper-0.1.0/nmtcmapper/data/schema.py

@@ -0,0 +1,68 @@
+"""
+Column mappings, eligibility thresholds, and constants for NMTC eligibility.
+Based on 2016-2020 ACS data — mandatory for QLICIs closed on or after Sept 1, 2024.
+Source: https://www.cdfifund.gov/research-data
+"""
+
+# ── Eligibility Thresholds ────────────────────────────────────────────────────
+
+# Low-Income Community (LIC) criteria — Section 45D
+LIC_POVERTY_RATE_THRESHOLD     = 0.20   # >= 20% poverty rate
+LIC_AMI_RATIO_METRO_THRESHOLD  = 0.80   # <= 80% of metro/state AMI
+LIC_AMI_RATIO_RURAL_THRESHOLD  = 0.85   # <= 85% of state AMI (high migration rural)
+
+# Severe Distress thresholds
+SEVERE_POVERTY_THRESHOLD       = 0.30   # >= 30% poverty rate
+SEVERE_AMI_THRESHOLD           = 0.60   # <= 60% of AMI
+SEVERE_UNEMPLOYMENT_MULTIPLIER = 1.5    # >= 1.5x national unemployment rate
+
+# Deep Distress thresholds
+DEEP_POVERTY_THRESHOLD         = 0.40   # >= 40% poverty rate
+DEEP_AMI_THRESHOLD             = 0.50   # <= 50% of AMI
+DEEP_UNEMPLOYMENT_MULTIPLIER   = 2.0    # >= 2x national unemployment rate
+
+# National unemployment rate benchmark (2016-2020 ACS)
+NATIONAL_UNEMPLOYMENT_RATE     = 0.057  # 5.7%
+
+# ── CDFI Fund Eligibility File Column Mappings ────────────────────────────────
+# Source: 2016-2020 ACS Low-Income Community Eligibility file from cdfifund.gov
+
+ELIGIBILITY_FILE_COLUMNS = {
+    "GEOID":                    "tract_id",
+    "STATE":                    "state",
+    "COUNTY":                   "county",
+    "TRACT":                    "tract",
+    "POVERTY_RATE":             "poverty_rate",
+    "MFI_RATIO":                "ami_ratio",
+    "UNEMPLOYMENT_RATE":        "unemployment_rate",
+    "NON_METRO":                "is_non_metro",
+    "HIGH_MIGRATION_RURAL":     "is_high_migration_rural",
+    "LIC_ELIGIBLE":             "lic_eligible_raw",
+    "SEVERE_DISTRESS":          "severe_distress_raw",
+}
+
+# ── Download URLs ─────────────────────────────────────────────────────────────
+CDFI_FUND_LIC_URL_2020 = (
+    "https://www.cdfifund.gov/sites/cdfi/files/2024-08/"
+    "NMTC_LIC_Eligibility_2016_2020_ACS.xlsx"
+)
+
+# ── Cache ─────────────────────────────────────────────────────────────────────
+import os
+CACHE_DIR = os.path.join(os.path.expanduser("~"), ".nmtcmapper", "cache")
+
+# ── Census Geocoder API ───────────────────────────────────────────────────────
+CENSUS_GEOCODER_URL = (
+    "https://geocoding.geo.census.gov/geocoder/geographies/address"
+)
+CENSUS_GEOCODER_BATCH_URL = (
+    "https://geocoding.geo.census.gov/geocoder/geographies/addressbatch"
+)
+
+# ── Distress Levels ───────────────────────────────────────────────────────────
+DISTRESS_LEVELS = {
+    "deep":     "Deep Distress — highest need, strongest NMTC application score",
+    "severe":   "Severe Distress — qualifies for 85% investment commitment",
+    "lic":      "Low-Income Community — NMTC eligible",
+    "ineligible": "Not NMTC eligible",
+}