Metadata-Version: 2.5
Name: mad-ssb
Version: 0.1.0
Summary: Turn municipal-level tables exported from Statistics Norway into tidy data frames for analysis.
Project-URL: Homepage, https://codeberg.org/divinemadman/mad-ssb
Project-URL: Repository, https://codeberg.org/divinemadman/mad-ssb
Author-email: Divine Madman <divinemadman@proton.me>
License-Expression: MIT
License-File: LICENSE
Keywords: data analysis,municipality,open data,pandas,ssb,statistics norway
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Requires-Dist: pandas>=3.0.5
Description-Content-Type: text/markdown

# mad-ssb

[![PyPI version](https://img.shields.io/pypi/v/mad-ssb.svg)](https://pypi.org/project/mad-ssb/)
[![Python versions](https://img.shields.io/pypi/pyversions/mad-ssb.svg)](https://pypi.org/project/mad-ssb/)
[![License](https://img.shields.io/pypi/l/mad-ssb.svg)](https://codeberg.org/divinemadman/mad-ssb/src/branch/main/LICENSE)

Turn municipal-level tables exported from Statistics Norway (Statistikkbanken / SSB)
into tidy `pandas.DataFrame`s that are ready for data analysis.

SSB Excel exports are formatted for humans rather than for computation: they
start with a banner of title/metadata rows, end with footnotes, lay out data
horizontally (one column per year) and encode missing values as the strings
`'.'` and `'..'`. `mad-ssb` returns a single long-format table, adds a municipal
ID number column, as well as does other basic clean up tasks to get to a decent
starting point for creating SSB datasets for analysis.

## Installation

```bash
pip install mad-ssb
```

or with `uv`:

```bash
uv add mad-ssb
```

Requires Python 3.11+ and pandas 3.0+.

## Quick start

```python
>>> from mad_ssb import read_ssb
>>> df = read_ssb("municipal_table.xlsx")
>>> df.head()
    MID  year  outcome
0  0301  2010      123
1  0301  2011      456
2  0302  2010       78
```

- Data columns (years) are stacked into a single `year`/`outcome` pair.
- The municipal ID is extracted into its own `MID` column.
- Optional: rename the index (metadata) columns with `non_year_col_names`,
  e.g. `read_ssb(path, non_year_col_names=["region"])`. Use
  `dtype="float"` when the table contains decimals or NA that integers
  cannot hold.

## How it works

`mad-ssb` is a small pipeline of composable helpers (all exposed as public API):

| Function                  | What it does                                             |
| ------------------------- | -------------------------------------------------------- |
| `find_ssb_table_header_row` | Find where the real table header starts (skip the banner) |
| `find_ssb_table_end`        | Find where the data stops (skip the footnotes)            |
| `find_non_year_columns`     | Identify the index/metadata columns left of the first year |
| `rank_non_year_cols`        | Order index columns coarse-to-fine for a clean hierarchy   |
| `centre_on_mid_col`         | Split `"0301 Oslo"` into `MID` (`0301`) and promote it     |
| `stack_ssb_table`           | Stack wide year columns into `year`/`outcome`              |
| `read_ssb`                  | Main entry point that drives the helpers above             |

## License

MIT