condepe 0.1.0__tar.gz

condepe-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,41 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  schedule:
+    # Weekly, after the Saturday publication cycle of the Observatory.
+    - cron: "0 12 * * 0"
+  workflow_dispatch:
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        # macOS left out: the code is OS-independent and GitHub's macOS arm64
+        # runners were unavailable (jobs cancelled after 15 min in the queue).
+        os: [ubuntu-latest, windows-latest]
+        python: ["3.10", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - run: pip install -e ".[dev]"
+      - run: ruff check .
+      - run: pytest -q
+
+  # The ADR 0006 acceptance check: from a runner outside Brazil, the package
+  # must return Recife's population (canonical endpoint or the mirror).
+  live:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - run: pip install -e ".[dev]"
+      - run: pytest -q -m live

condepe-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,21 @@
+# Builds the site from the precompiled pages (no network needed) and
+# publishes it to the gh-pages branch. Manual until the repository is made
+# public: GitHub Pages of a private repository would still be public.
+name: docs
+
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - run: pip install -e ".[docs]"
+      - run: mkdocs gh-deploy --force --strict

condepe-0.1.0/.github/workflows/pypi.yml

@@ -0,0 +1,51 @@
+# Publishes condepe to PyPI via trusted publishing (OIDC, no token).
+# Runs on tags v* (e.g. v0.1.0) or manually. Register once on pypi.org
+# (Publishing -> pending publisher): owner StrategicProjects, repository
+# condepe-py, workflow pypi.yml, environment pypi. Do not rename this file.
+name: pypi
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Tag matches the declared version
+        if: startsWith(github.ref, 'refs/tags/v')
+        run: |
+          declared=$(grep -m1 '^version' pyproject.toml | cut -d'"' -f2)
+          test "v$declared" = "$GITHUB_REF_NAME" || { echo "tag $GITHUB_REF_NAME, pyproject $declared"; exit 1; }
+      - run: pip install build twine
+      - run: python -m build
+      - run: twine check dist/*
+      - run: pip install dist/*.whl && python -I -c "import condepe; print(condepe.__version__)"
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      # A Docker action: pin the release tag, not a commit SHA.
+      - uses: pypa/gh-action-pypi-publish@v1.14.2
+        with:
+          skip-existing: true

condepe-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.py[cod]
+.venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+site/

condepe-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 condepe authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

condepe-0.1.0/NEWS.md

@@ -0,0 +1,6 @@
+# condepe 0.1.0
+
+* First version: `condepe_catalog()`, `condepe_indicators()`, `condepe_data()`,
+  `condepe_series()` and `condepe_localities()`, reading the Observatory open data
+  (canonical endpoint, Hugging Face mirror as fallback) with a disk cache per
+  catalogue version and sha256 verification.

condepe-0.1.0/PKG-INFO

@@ -0,0 +1,133 @@
+Metadata-Version: 2.5
+Name: condepe
+Version: 0.1.0
+Summary: Access the open data of the Pernambuco Observatory (Condepe/Fidem) from Python
+Project-URL: Homepage, https://strategicprojects.github.io/condepe-py/
+Project-URL: Data, https://cf.pe.gov.br/observatorio
+Project-URL: Repository, https://github.com/StrategicProjects/condepe-py
+Project-URL: Issues, https://github.com/StrategicProjects/condepe-py/issues
+Project-URL: Changelog, https://github.com/StrategicProjects/condepe-py/blob/main/NEWS.md
+Author-email: André Leite <leite@castlab.org>, Marcos Wasiliew <marcos.wasiliew@gmail.com>, Hugo Vasconcelos <hugo.vasconcelos@ufpe.br>, Carlos Amorim <carlos.agaf@ufpe.br>, Diogo Bezerra <diogo.bezerra@ufpe.br>, Júlia Nascimento Barreto <juliabarreto@gd.seplag.pe.gov.br>
+License: MIT License
+        
+        Copyright (c) 2026 condepe authors
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: Brazil,Condepe/Fidem,Pernambuco,municipalities,open-data,pandas,statistics
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.10
+Requires-Dist: pandas>=1.3
+Requires-Dist: platformdirs>=3
+Requires-Dist: pyarrow>=10
+Requires-Dist: requests>=2.25
+Provides-Extra: dev
+Requires-Dist: build>=1.0; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: responses>=0.23; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: matplotlib>=3.5; extra == 'docs'
+Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
+Requires-Dist: mkdocstrings[python]>=0.26; extra == 'docs'
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == 'test'
+Requires-Dist: responses>=0.23; extra == 'test'
+Description-Content-Type: text/markdown
+
+# condepe <img src="docs/assets/logo.svg" align="right" height="139" alt="condepe hex logo" />
+
+Python access to the open data of the **Observatório de Pernambuco**, published by
+[Condepe/Fidem](https://cf.pe.gov.br) (the Pernambuco State Agency for Planning and
+Research): municipal series on population, economy, public finance, labour,
+education, health, security, transport and environment for the 185
+municipalities of Pernambuco, Brazil.
+
+Every source is published in the same long format (one observation per row, 15
+columns), so one set of functions covers all of them.
+
+## Installation
+
+```bash
+pip install condepe
+# development version:
+pip install git+https://github.com/StrategicProjects/condepe-py
+```
+
+## Usage
+
+```python
+import condepe
+
+# Sources available (one row each), with the catalogue version
+cat = condepe.condepe_catalog()
+cat.attrs["version"]
+
+# Indicators of a source
+condepe.condepe_indicators("sidra_populacao_estimada")
+
+# A series: Recife (IBGE 2611606), 2020 onwards
+condepe.condepe_series(
+    "sidra_populacao_estimada",
+    "Populacao residente estimada",
+    code="2611606",
+    years=range(2020, 2027),
+)
+
+# A whole source, and the municipality list
+condepe.condepe_data("datasus_sinasc")
+condepe.condepe_localities()
+```
+
+Column names are kept in Portuguese, as published, so results stay traceable to
+the official files: `cd_municipio_ibge`, `nm_municipio`, `ano`, `mes`,
+`indicador`, `indicador_base`, `valor`, `unidade`, `natureza`, `id_fonte`,
+`eixo`, `tema`, `assunto`, `fonte_original`, `arquivo_origem`. Monthly series
+carry the period in `indicador` (`"… [MM/YYYY]"`) and `mes`; `indicador_base` is
+the label without it.
+
+## Where the data come from
+
+- **Canonical:** <https://cf.pe.gov.br/observatorio/dados/atual/>
+- **Mirror (fallback):** the Hugging Face dataset
+  [`mlkwy/observatorio-pernambuco`](https://huggingface.co/datasets/mlkwy/observatorio-pernambuco),
+  with the same relative paths.
+
+Files are cached on disk per catalogue version (`condepe_cache_dir()`) and
+checked against the sha256 published in the catalogue. The catalogue itself is
+trusted for 6 hours. Set `CONDEPE_URL`, `CONDEPE_MIRROR_URL` or
+`CONDEPE_CACHE_DIR` to override the defaults.
+
+Documentation: <https://strategicprojects.github.io/condepe-py/>.
+
+## Citation and license
+
+Data: Condepe/Fidem, *Observatório de Pernambuco — Base de Dados do Estado*,
+[CC BY 4.0](https://creativecommons.org/licenses/by/4.0/). The citation with the
+version in use is in `condepe_catalog().attrs["citation"]`.
+
+Code: MIT. To read or write *private* buckets on `s3.pe.gov.br` with an
+access key, see [`s3pe`](https://github.com/StrategicProjects/s3pe); `condepe`
+needs no key, since the Observatory open data are public. An R package with the same functions is
+[`condepe` for R](https://github.com/StrategicProjects/condepe-r).

condepe-0.1.0/README.md

@@ -0,0 +1,75 @@
+# condepe <img src="docs/assets/logo.svg" align="right" height="139" alt="condepe hex logo" />
+
+Python access to the open data of the **Observatório de Pernambuco**, published by
+[Condepe/Fidem](https://cf.pe.gov.br) (the Pernambuco State Agency for Planning and
+Research): municipal series on population, economy, public finance, labour,
+education, health, security, transport and environment for the 185
+municipalities of Pernambuco, Brazil.
+
+Every source is published in the same long format (one observation per row, 15
+columns), so one set of functions covers all of them.
+
+## Installation
+
+```bash
+pip install condepe
+# development version:
+pip install git+https://github.com/StrategicProjects/condepe-py
+```
+
+## Usage
+
+```python
+import condepe
+
+# Sources available (one row each), with the catalogue version
+cat = condepe.condepe_catalog()
+cat.attrs["version"]
+
+# Indicators of a source
+condepe.condepe_indicators("sidra_populacao_estimada")
+
+# A series: Recife (IBGE 2611606), 2020 onwards
+condepe.condepe_series(
+    "sidra_populacao_estimada",
+    "Populacao residente estimada",
+    code="2611606",
+    years=range(2020, 2027),
+)
+
+# A whole source, and the municipality list
+condepe.condepe_data("datasus_sinasc")
+condepe.condepe_localities()
+```
+
+Column names are kept in Portuguese, as published, so results stay traceable to
+the official files: `cd_municipio_ibge`, `nm_municipio`, `ano`, `mes`,
+`indicador`, `indicador_base`, `valor`, `unidade`, `natureza`, `id_fonte`,
+`eixo`, `tema`, `assunto`, `fonte_original`, `arquivo_origem`. Monthly series
+carry the period in `indicador` (`"… [MM/YYYY]"`) and `mes`; `indicador_base` is
+the label without it.
+
+## Where the data come from
+
+- **Canonical:** <https://cf.pe.gov.br/observatorio/dados/atual/>
+- **Mirror (fallback):** the Hugging Face dataset
+  [`mlkwy/observatorio-pernambuco`](https://huggingface.co/datasets/mlkwy/observatorio-pernambuco),
+  with the same relative paths.
+
+Files are cached on disk per catalogue version (`condepe_cache_dir()`) and
+checked against the sha256 published in the catalogue. The catalogue itself is
+trusted for 6 hours. Set `CONDEPE_URL`, `CONDEPE_MIRROR_URL` or
+`CONDEPE_CACHE_DIR` to override the defaults.
+
+Documentation: <https://strategicprojects.github.io/condepe-py/>.
+
+## Citation and license
+
+Data: Condepe/Fidem, *Observatório de Pernambuco — Base de Dados do Estado*,
+[CC BY 4.0](https://creativecommons.org/licenses/by/4.0/). The citation with the
+version in use is in `condepe_catalog().attrs["citation"]`.
+
+Code: MIT. To read or write *private* buckets on `s3.pe.gov.br` with an
+access key, see [`s3pe`](https://github.com/StrategicProjects/s3pe); `condepe`
+needs no key, since the Observatory open data are public. An R package with the same functions is
+[`condepe` for R](https://github.com/StrategicProjects/condepe-r).

condepe-0.1.0/docs/api.md

@@ -0,0 +1,33 @@
+# API reference
+
+## Discover
+
+::: condepe.condepe_catalog
+
+::: condepe.condepe_indicators
+
+::: condepe.condepe_localities
+
+## Retrieve data
+
+::: condepe.condepe_series
+
+::: condepe.condepe_data
+
+## Cache and settings
+
+::: condepe.condepe_cache_dir
+
+::: condepe.condepe_cache_clear
+
+::: condepe.set_timeout
+
+::: condepe.set_verbose
+
+## Errors
+
+::: condepe.CondepeError
+
+::: condepe.HttpError
+
+::: condepe.IntegrityError

condepe-0.1.0/docs/assets/extra.css

@@ -0,0 +1,12 @@
+/* Institutional blue of Pernambuco (#0C2856) with the cyan accent of the
+   official palette, as in the R package site. */
+:root {
+  --md-primary-fg-color: #0c2856;
+  --md-primary-fg-color--light: #1f4f9a;
+  --md-primary-fg-color--dark: #06183a;
+  --md-accent-fg-color: #0068ff;
+}
+[data-md-color-scheme="slate"] {
+  --md-primary-fg-color: #0c2856;
+  --md-accent-fg-color: #00b7ff;
+}

condepe-0.1.0/docs/assets/logo.svg

@@ -0,0 +1,49 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg viewBox="0 0 200 231" width="200" height="231" version="1.1" role="img"
+     aria-label="condepe for Python" xmlns="http://www.w3.org/2000/svg">
+  <title>condepe (Python)</title>
+  <!-- Hexagon in the institutional blue of Pernambuco (#0C2856); the motif is
+       the state outline (IBGE mesh, Fernando de Noronha left out) under a
+       time series, the two things the package delivers: places and series. -->
+  <defs>
+    <linearGradient id="fundo" x1="0" y1="0" x2="0" y2="1">
+      <stop offset="0" stop-color="#1f4f9a"/>
+      <stop offset="1" stop-color="#0c2856"/>
+    </linearGradient>
+    <linearGradient id="estado" x1="0" y1="0" x2="1" y2="0">
+      <stop offset="0" stop-color="#ffb000" stop-opacity="0.95"/>
+      <stop offset="1" stop-color="#ffce00" stop-opacity="0.95"/>
+    </linearGradient>
+    <clipPath id="hex"><polygon points="100,2 198,58.5 198,172.5 100,229 2,172.5 2,58.5"/></clipPath>
+  </defs>
+  <polygon points="100,2 198,58.5 198,172.5 100,229 2,172.5 2,58.5" fill="url(#fundo)"/>
+  <g clip-path="url(#hex)">
+    <line x1="30" y1="46" x2="170" y2="46" stroke="#ffffff" stroke-opacity="0.08" stroke-width="0.6"/>
+    <line x1="30" y1="62" x2="170" y2="62" stroke="#ffffff" stroke-opacity="0.08" stroke-width="0.6"/>
+    <line x1="30" y1="78" x2="170" y2="78" stroke="#ffffff" stroke-opacity="0.12" stroke-width="0.8"/>
+    <path d="M32.0,115.9 33.7,116.4 37.1,115.8 37.3,117.4 40.3,118.7 42.6,121.0 43.2,123.6 46.3,125.8 44.3,131.2 45.4,131.3 47.3,132.0 51.6,129.3 52.9,129.8 54.6,123.7 55.9,123.3 57.6,124.2 60.2,123.2 60.7,123.1 62.9,120.6 62.5,118.4 67.1,117.5 67.7,114.9 71.2,113.5 73.7,112.5 75.4,113.3 76.4,115.9 79.8,116.4 82.1,117.9 84.1,117.5 87.2,119.1 87.5,120.2 89.2,121.1 90.1,118.4 92.2,119.1 91.2,121.1 93.5,122.7 95.2,121.7 95.4,125.0 97.0,128.8 98.7,127.2 100.0,125.5 101.7,125.2 102.9,124.0 105.6,120.5 107.0,118.7 108.2,120.6 109.5,122.0 111.8,121.2 112.0,121.3 114.5,122.5 117.0,125.1 118.0,126.7 118.6,126.4 119.2,127.5 121.6,128.6 121.6,128.3 123.2,129.4 124.1,129.8 125.3,127.7 127.0,127.8 129.0,128.0 130.6,128.9 133.2,127.4 135.2,126.6 136.2,126.5 137.5,125.6 139.5,122.9 141.1,122.5 141.3,122.3 140.9,121.1 142.9,120.0 143.8,119.9 144.6,119.7 146.8,119.3 147.2,119.2 149.4,120.1 150.8,119.5 152.3,118.7 152.5,118.7 153.2,118.2 155.9,118.6 157.1,119.0 159.5,119.5 161.2,120.2 161.7,119.1 162.3,117.5 162.6,115.5 163.4,113.8 165.2,108.8 165.9,105.8 166.3,104.3 167.3,102.0 168.0,100.3 167.7,97.9 167.6,97.3 167.6,94.6 167.9,91.7 167.5,91.5 164.7,90.7 164.7,89.9 161.2,88.5 158.6,88.4 157.5,88.9 157.3,89.1 156.9,89.5 155.4,90.1 154.1,90.4 154.0,91.0 153.4,93.7 151.5,94.1 150.3,94.9 148.0,95.7 147.2,95.9 146.1,96.3 144.8,96.7 143.5,97.2 143.1,97.2 141.0,96.6 139.1,96.2 138.1,97.6 135.3,97.2 134.3,99.4 132.4,99.1 131.7,99.8 130.5,103.4 129.3,104.4 127.2,105.1 124.7,106.4 123.7,107.3 122.3,107.2 119.4,104.7 119.8,103.7 119.7,101.6 115.5,100.0 119.2,97.0 119.6,96.5 119.6,95.2 119.4,94.8 118.6,93.5 121.1,91.0 122.2,90.6 122.2,90.6 123.1,90.2 122.5,88.7 121.7,88.2 119.1,86.7 117.3,86.0 116.2,86.3 114.7,87.7 113.8,87.7 111.9,89.4 110.9,90.5 109.9,91.2 107.5,92.7 107.2,93.0 107.1,93.3 106.8,94.0 104.0,94.8 102.8,96.2 101.9,96.5 100.5,96.4 99.4,97.3 99.2,96.9 97.3,97.4 95.5,95.7 94.5,94.4 92.9,95.3 92.4,95.2 89.6,96.0 87.0,93.2 87.0,93.3 83.3,95.9 81.9,97.9 81.8,97.9 80.7,97.2 79.2,98.2 79.0,96.3 78.1,95.2 75.6,94.1 73.4,93.2 73.0,93.0 71.8,92.2 71.5,90.1 69.7,90.4 68.6,89.2 65.7,87.1 62.6,87.4 62.3,87.3 57.0,88.0 55.2,86.9 53.1,87.1 51.3,87.9 49.4,86.9 48.9,88.5 46.7,89.3 45.4,90.3 47.3,94.0 46.3,96.2 48.7,97.3 49.0,100.3 48.6,101.1 48.3,101.8 48.3,101.8 47.7,103.3 44.4,106.2 44.0,107.3 42.3,108.8 41.0,110.4 39.9,109.4 36.3,112.2 35.2,114.3Z" fill="url(#estado)" stroke="#ffffff" stroke-width="1.2" stroke-linejoin="round"/>
+    <polyline points="42,78 70,64 100,70 128,58 154,50" fill="none" stroke="#06183a" stroke-opacity="0.35" stroke-width="4"
+              stroke-linecap="round" stroke-linejoin="round" transform="translate(0,2)"/>
+    <polyline points="42,78 70,64 100,70 128,58 154,50" fill="none" stroke="#ffffff" stroke-width="2.5"
+              stroke-linecap="round" stroke-linejoin="round"/>
+    <circle cx="42" cy="78" r="4" fill="#ffffff"/>
+    <circle cx="42" cy="78" r="2" fill="#ffce00"/>
+    <circle cx="70" cy="64" r="4" fill="#ffffff"/>
+    <circle cx="70" cy="64" r="2" fill="#ffce00"/>
+    <circle cx="100" cy="70" r="4" fill="#ffffff"/>
+    <circle cx="100" cy="70" r="2" fill="#ffce00"/>
+    <circle cx="128" cy="58" r="4" fill="#ffffff"/>
+    <circle cx="128" cy="58" r="2" fill="#ffce00"/>
+    <circle cx="154" cy="50" r="4" fill="#ffffff"/>
+    <circle cx="154" cy="50" r="2" fill="#ffce00"/>
+  </g>
+  <polygon points="100,2 198,58.5 198,172.5 100,229 2,172.5 2,58.5" fill="none" stroke="#06183a" stroke-width="3"/>
+  <text x="100" y="164" text-anchor="middle"
+        font-family="'Fira Code', 'Courier New', monospace"
+        font-size="24px" font-weight="700" fill="#ffffff" letter-spacing="1">condepe</text>
+  <g transform="translate(100,190)">
+    <rect x="-17" y="-11" width="34" height="18" rx="9" fill="#ffce00"/>
+    <text x="0" y="3.5" text-anchor="middle" font-family="'Fira Code', 'Courier New', monospace"
+          font-size="12px" font-weight="700" fill="#0c2856">py</text>
+  </g>
+</svg>

condepe-0.1.0/docs/examples.md

@@ -0,0 +1,129 @@
+# Worked examples
+
+Plots use matplotlib, which is not a dependency of the package
+(`pip install matplotlib`).
+
+## Infant mortality in the largest cities
+
+Deaths under one year per thousand live births, by municipality of
+residence, for Recife, Jaboatão dos Guararapes, Caruaru and Petrolina:
+
+```python
+cidades = ["2611606", "2607901", "2604106", "2611101"]
+
+tmi = condepe.condepe_series(
+    "datasus_mortalidade_infantil",
+    "Taxa de mortalidade infantil (por mil nascidos vivos)",
+    code=cidades,
+)
+
+largo = tmi.pivot(index="ano", columns="nm_municipio", values="valor")
+
+largo
+```
+
+```text
+nm_municipio  Caruaru  Jaboatão dos Guararapes  Petrolina  Recife
+ano                                                              
+2017            11.98                    10.63      15.30   10.83
+2018            10.73                    12.08      15.20   10.53
+2019             9.62                    11.59      18.07   11.50
+2020             9.74                    12.19      14.02   11.20
+2021            10.62                    12.12      15.40   10.03
+2022            13.17                    13.96      14.86   10.93
+2023            12.64                    13.41      14.28   12.32
+2024            11.35                    13.87      16.36   11.85
+```
+
+
+
+```python
+ax = largo.plot(
+    marker="o",
+    color=["#0c2856", "#0068ff", "#00b7ff", "#ff6700"],
+    figsize=(7, 4),
+    title="Infant mortality",
+)
+
+ax.set_xlabel("")
+
+ax.set_ylabel("per 1,000 live births")
+
+print(fig("tmi"))
+```
+
+![tmi](assets/tmi.png)
+
+## Cargo at the port of Suape
+
+Monthly gross cargo handled at Suape (Ipojuca), in million tonnes:
+
+```python
+suape = condepe.condepe_series("porto_suape_carga", "Porto de Suape - Carga bruta total")
+
+suape["data"] = pd.to_datetime(dict(year=suape["ano"], month=suape["mes"], day=1))
+
+ax = (suape.set_index("data")["valor"] / 1e6).plot(
+    color="#0c2856", figsize=(7, 4), title="Port of Suape, gross cargo"
+)
+
+ax.set_xlabel("")
+
+ax.set_ylabel("million t")
+
+print(fig("suape"))
+```
+
+![suape](assets/suape.png)
+
+## IDEB of the municipal schools
+
+The Basic Education Development Index of the early years of elementary
+school, municipal network, in Recife:
+
+```python
+ideb = condepe.condepe_series(
+    "inep_ideb_anos_iniciais", "IDEB observado - Municipal", code="2611606"
+)
+
+ideb[["ano", "valor"]]
+```
+
+```text
+     ano  valor
+0   2005    3.2
+1   2007    3.8
+2   2009    4.1
+3   2011    4.1
+4   2013    4.2
+5   2015    4.6
+6   2017    5.0
+7   2019    5.2
+8   2021    5.3
+9   2023    5.5
+10  2025    5.8
+```
+
+## All municipalities in one year
+
+Live births by municipality of residence in 2024, the ten largest:
+
+```python
+nasc = condepe.condepe_series("datasus_sinasc", "Nascidos vivos por residência - Total", years=2024)
+
+nasc.nlargest(10, "valor")[["nm_municipio", "valor"]]
+```
+
+```text
+                nm_municipio    valor
+131                   Recife  16116.0
+87   Jaboatão dos Guararapes   7284.0
+125                Petrolina   6175.0
+44                   Caruaru   5285.0
+110                   Olinda   3879.0
+121                 Paulista   3284.0
+30   Cabo de Santo Agostinho   2435.0
+66                 Garanhuns   1965.0
+36                Camaragibe   1711.0
+183   Vitória de Santo Antão   1622.0
+```