Metadata-Version: 2.4
Name: us-small-business-capital-access-atlas
Version: 0.3.0
Summary: Open-source geospatial research tools for U.S. small-business capital-access analysis using authoritative public data.
Author: Sakera Begum
License: MIT
Project-URL: Homepage, https://github.com/sakera023/us-small-business-capital-access-atlas
Project-URL: Demo, https://capital-access-atlas-sakera.streamlit.app/
Project-URL: Repository, https://github.com/sakera023/us-small-business-capital-access-atlas
Project-URL: PyPI, https://pypi.org/project/us-small-business-capital-access-atlas/
Project-URL: Issues, https://github.com/sakera023/us-small-business-capital-access-atlas/issues
Project-URL: Documentation, https://github.com/sakera023/us-small-business-capital-access-atlas/tree/main/docs
Project-URL: Data Source, https://data.sba.gov/dataset/state-small-business-statistics-2025
Project-URL: Census CBP, https://www.census.gov/data/datasets/2023/econ/cbp/2023-cbp.html
Project-URL: Citation, https://github.com/sakera023/us-small-business-capital-access-atlas/blob/main/CITATION.md
Project-URL: Google Scholar, https://scholar.google.com/citations?user=D4t4wxAAAAAJ
Keywords: small-business,capital-access,economic-development,entrepreneurship,geospatial-analysis,public-data,sba,data-science,streamlit,responsible-ai,census,county-business-patterns,research-software,geographic-inequality
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy<3,>=1.26
Requires-Dist: openpyxl<4,>=3.1
Requires-Dist: pandas<4,>=2.1
Requires-Dist: plotly<8,>=5.20
Requires-Dist: streamlit<2,>=1.40
Provides-Extra: dev
Requires-Dist: pytest<10,>=8; extra == "dev"
Requires-Dist: ruff<1,>=0.8; extra == "dev"
Dynamic: license-file

# U.S. Small Business Capital Access Atlas

[![CI](https://github.com/sakera023/us-small-business-capital-access-atlas/actions/workflows/ci.yml/badge.svg)](https://github.com/sakera023/us-small-business-capital-access-atlas/actions/workflows/ci.yml)
[![Public Data Validation](https://github.com/sakera023/us-small-business-capital-access-atlas/actions/workflows/data-validation.yml/badge.svg)](https://github.com/sakera023/us-small-business-capital-access-atlas/actions/workflows/data-validation.yml)
[![Live App](https://img.shields.io/badge/Live%20App-Streamlit-FF4B4B?logo=streamlit&logoColor=white)](https://capital-access-atlas-sakera.streamlit.app/)
[![GitHub Release](https://img.shields.io/github/v/release/sakera023/us-small-business-capital-access-atlas)](https://github.com/sakera023/us-small-business-capital-access-atlas/releases/latest)
[![PyPI](https://img.shields.io/pypi/v/us-small-business-capital-access-atlas.svg)](https://pypi.org/project/us-small-business-capital-access-atlas/)
[![Citation](https://img.shields.io/badge/Citation-CFF-blue)](CITATION.md)
[![Google Scholar](https://img.shields.io/badge/Google%20Scholar-Profile-4285F4?logo=googlescholar&logoColor=white)](https://scholar.google.com/citations?user=D4t4wxAAAAAJ)
![Python](https://img.shields.io/badge/Python-3.11%2B-3776AB?logo=python&logoColor=white)
![License](https://img.shields.io/badge/License-MIT-green)

An open-source **geospatial research platform for integrating, validating, mapping, and
comparing U.S. small-business and capital-access context using authoritative public data**.

The Atlas is designed for researchers, economic-development practitioners, educators,
data scientists, and policy analysts who need a reproducible way to examine how business
activity, employment, payroll, entrepreneurial scale, and capital-support context vary
across U.S. geographies.

## Latest versioned release

**v0.3.0 — County, CDFI, Robustness & Archival Release**

- GitHub release: https://github.com/sakera023/us-small-business-capital-access-atlas/releases/tag/v0.3.0
- Includes a Python wheel and source distribution as release assets
- Release was created only after automated linting, tests, and package validation passed

Install the published PyPI package:

```bash
pip install us-small-business-capital-access-atlas
```

Import it in Python:

```python
import capital_access_atlas
```

PyPI project:
https://pypi.org/project/us-small-business-capital-access-atlas/

For exact source reproducibility, the tagged GitHub version can also be installed with:

```bash
pip install "git+https://github.com/sakera023/us-small-business-capital-access-atlas.git@v0.3.0"
```

## Python package

The Atlas is published on PyPI as:

`us-small-business-capital-access-atlas`

Install:

```bash
pip install us-small-business-capital-access-atlas
```

Python import namespace:

```python
import capital_access_atlas
```

This makes the data-retrieval, geography, index, and validation utilities reusable outside
the Streamlit application.

## Live public Atlas

**Application:** https://capital-access-atlas-sakera.streamlit.app/

The public dashboard provides:

- official SBA state-level small-business measures;
- official U.S. Census County Business Patterns state and county data;
- state-to-county geographic drill-down with Census TIGERweb boundaries;
- county establishments, employment, payroll, and industry-concentration analysis;
- current Certified CDFI organization geography;
- state and county comparison workflows;
- downloadable map-ready data;
- an exploratory Capital Access Opportunity Index Lab;
- alternative normalization, weight, omission, and missing-data sensitivity diagnostics;
- data-quality reports and reproducible validation artifacts.

No login or API key is required for the currently integrated public-data layers.

## Research objective

The project examines a national-scale question:

> **Where do small-business activity, economic opportunity, and capital-support context
> appear to diverge across U.S. geographies, and how robust are those patterns to data and
> methodological choices?**

The Atlas focuses on **place-based public-data measurement**, not applicant-level
underwriting.

## Authoritative public data

| Source | Current use | Status |
| --- | --- | --- |
| U.S. Small Business Administration, Office of Advocacy | State small-business counts, employment, job creation, ownership and related profile measures | **Integrated** |
| U.S. Census Bureau, County Business Patterns 2023 | State and county establishments, employment, payroll, and industry structure | **Integrated** |
| U.S. Census Bureau, TIGERweb 2023 | Generalized county geometries for state-to-county mapping | **Integrated** |
| CDFI Fund — Currently Certified CDFIs | State-level organization geography and a CBP-relative intensity proxy | **Integrated** |
| U.S. Census Annual Business Survey | Employer-firm and owner-characteristic context | Planned |
| Bureau of Labor Statistics | Labor-market context | Planned |
| Bureau of Economic Analysis | Regional income and output context | Planned |

See [Data Sources](docs/DATA_SOURCES.md) and
[Data Governance](docs/DATA_GOVERNANCE.md).

## Core research capabilities

### Public-data engineering

- direct retrieval from official U.S. government distribution endpoints;
- ZIP/Excel ingestion;
- state and county FIPS normalization;
- numeric-field cleaning;
- state and county aggregation;
- Census ZIP, SBA Excel, and CDFI workbook ingestion;
- resilient CDFI workbook-link discovery;
- source metadata preservation; and
- downloadable clean extracts.

### Certified CDFI validation guard

The live CDFI integration now explicitly prefers the institution-level certification
worksheet over state-summary sheets and rejects suspiciously small institution lists.
This prevents a state summary from being misreported as the full Certified CDFI roster.

### Geographic analysis

- U.S. state choropleths;
- 2023 Census TIGERweb county choropleths;
- state-to-county drill-down;
- county industry-concentration HHI;
- interactive metric selection;
- state rankings and multi-state comparison;
- Certified CDFI state geography; and
- explicit source/vintage labels.

### Transparent composite-index research

The **Capital Access Opportunity Index Lab** supports:

- percentile, z-score, winsorized z-score, and robust median/MAD normalization;
- user-defined non-negative weights;
- inverse-direction metrics;
- data-coverage reporting;
- leave-one-metric-out rank sensitivity;
- one-component weight-emphasis sensitivity; and
- deterministic missing-data stress testing.

A composite score is never presented without its component inputs and methodology.

### Validation and reproducibility

The repository includes:

- Python 3.11 and 3.12 CI;
- unit tests for geography, public-data parsing, index logic, and validation;
- Streamlit smoke testing;
- a dedicated public-data validation workflow;
- machine-readable state, county, industry-concentration, and robustness artifacts;
- reproducible Jupyter examples;
- documented case studies;
- an independent-review package; and
- an external-use evidence guide.

See [Validation and Robustness](docs/VALIDATION.md) and
[Reproducible Public-Data Validation](docs/VALIDATION_REPORT.md).

## Architecture

```text
Authoritative U.S. Public Sources
          |
          v
   Retrieval / Provenance
          |
          v
Geographic + Numeric Cleaning
       /          \
      v            v
Map-Ready Data   Index Components
      |            |
      +------v-----+
             |
             v
     Validation Diagnostics
             |
       +-----+-----+
       |           |
       v           v
Interactive Maps  Rankings / Exports
       |
       v
 Public Streamlit Atlas
```

See [Architecture](docs/ARCHITECTURE.md).

## Reproducible examples

Four notebooks demonstrate the research workflow:

1. [SBA State Atlas](examples/01_sba_state_atlas.ipynb)
2. [Census CBP State Context](examples/02_census_cbp_state_context.ipynb)
3. [Index Sensitivity](examples/03_index_sensitivity.ipynb)
4. [Data Quality and Provenance](examples/04_data_quality_and_provenance.ipynb)

See the [examples guide](examples/README.md).

## Documented case studies

The repository includes methodological case studies that demonstrate how to use the Atlas
without making unsupported causal or applicant-level claims:

1. [Mid-Atlantic State Comparison](docs/case-studies/01_mid_atlantic_comparison.md)
2. [Rural and Appalachian Research Workflow](docs/case-studies/02_rural_appalachian_workflow.md)
3. [High-Growth State Business Context](docs/case-studies/03_high_growth_state_context.md)

See the [case study index](docs/case-studies/README.md).

## Quick start

Clone and install:

```bash
git clone https://github.com/sakera023/us-small-business-capital-access-atlas.git
cd us-small-business-capital-access-atlas
python -m venv .venv
pip install -r requirements.txt
```

Run the public-data dashboard locally:

```bash
streamlit run app.py
```

Development setup:

```bash
pip install -r requirements-dev.txt
ruff check src tests scripts app.py
python -m pytest -q
```

Run the reproducible Census validation workflow locally:

```bash
python scripts/run_cbp_validation.py
```

## Research and responsible-use boundary

The Atlas analyzes **aggregate geographic data**.

It does **not**:

- determine whether an individual or business should receive credit;
- estimate a real applicant's approval probability;
- infer protected characteristics;
- prove discrimination or causation from map differences;
- establish policy effectiveness from descriptive correlations; or
- treat a composite score as a legal, regulatory, or underwriting finding.

Geographic and index results are only as reliable as their source definitions, vintage,
coverage, transformations, and sensitivity to analytical choices.

## Academic citation and research metadata

The repository includes:

- [CITATION.cff](CITATION.cff) for GitHub's **Cite this repository** feature;
- [CITATION.md](CITATION.md) with a recommended citation and BibTeX;
- [codemeta.json](codemeta.json) for machine-readable research-software metadata; and
- explicit instructions to cite the underlying SBA and Census datasets separately.

No DOI is claimed unless a verified DOI is minted through an external research-software
archive. The repository is prepared for Zenodo archival; see
[Software DOI and Archival Plan](docs/DOI.md).

## External milestones that cannot be self-certified

Two research milestones intentionally remain external:

- **Independent methodology review:** the repository now provides a structured
  [review package](docs/INDEPENDENT_REVIEW.md), but completion requires a genuine
  third-party reviewer.
- **Verified outside use:** the repository provides an
  [evidence guide](docs/EXTERNAL_USE_EVIDENCE.md), but adoption is recorded only when
  real users, organizations, courses, or researchers provide verifiable evidence.

The maintainer does not self-create independent reviews or fabricate adoption evidence.

## External use and research impact

Genuine outside use is encouraged through:

- public forks and derivative repositories;
- research/adoption issue reports;
- external pull requests;
- independent replication;
- citations;
- public teaching use; and
- documented organizational testing.

See [ADOPTION.md](ADOPTION.md),
[Independent Replication Protocol](docs/REPLICATION_PROTOCOL.md),
[Verified External Use Log](docs/ADOPTION_LOG.md),
[Research Outreach Kit](docs/OUTREACH_KIT.md), and
[Research Impact and Adoption Framework](docs/RESEARCH_IMPACT.md).

The project does not manufacture stars, users, citations, testimonials, or adoption claims.

## Research roadmap

The roadmap progresses from the current state-level atlas toward:

1. county-level Census business structure;
2. CDFI/community-finance geography;
3. rural and metropolitan comparisons;
4. a validated state/county Capital Access Opportunity Index; and
5. independent replication and public research dissemination.

See [Research Roadmap](docs/RESEARCH_ROADMAP.md).

## Repository structure

```text
.
├── app.py
├── src/capital_access_atlas/
│   ├── analysis.py
│   ├── cdfi.py
│   ├── census_cbp.py
│   ├── geography.py
│   ├── indicators.py
│   └── public_data.py
├── scripts/
│   └── run_cbp_validation.py
├── examples/
├── tests/
├── docs/
│   ├── case-studies/
│   ├── ARCHITECTURE.md
│   ├── DATA_GOVERNANCE.md
│   ├── DATA_SOURCES.md
│   ├── INDEX_METHODOLOGY.md
│   ├── RESEARCH_IMPACT.md
│   ├── RESEARCH_ROADMAP.md
│   ├── INDEPENDENT_REVIEW.md
│   ├── EXTERNAL_USE_EVIDENCE.md
│   ├── REPLICATION_PROTOCOL.md
│   ├── ADOPTION_LOG.md
│   ├── OUTREACH_KIT.md
│   ├── DOI.md
│   ├── VALIDATION.md
│   └── VALIDATION_REPORT.md
├── .github/workflows/
├── ADOPTION.md
├── CITATION.cff
├── CITATION.md
├── codemeta.json
├── CODE_OF_CONDUCT.md
├── CONTRIBUTING.md
├── SECURITY.md
└── LICENSE
```

## Related research software

This Atlas complements
[Equitable Capital Optimization AI](https://github.com/sakera023/equitable-capital-optimization-ai),
which focuses on predictive modeling, explainability, fairness auditing, and simulated
capital allocation. The Atlas remains methodologically separate and focuses on public,
place-based geographic evidence.

## Contributing

Contributions are welcome in public-data integration, geographic validation, methodology,
documentation, accessibility, and independent replication.

See [CONTRIBUTING.md](CONTRIBUTING.md) and
[CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).

## License

MIT License. See [LICENSE](LICENSE).

## Maintainer

**Sakera Begum**
