Skip to content
imibare

Reference

Python package

Package: imibare Import: import imibare as imi Install: pip install imibare

imibare.load()

def load(
    dataset_id: str,
    start: int | str | None = None,
    end: int | str | None = None,
    engine: Literal["pandas", "polars"] = "pandas",
    version: str | None = None,
    force_download: bool = False,
) -> pd.DataFrame | pl.DataFrame

Loads a dataset. Returns a pandas DataFrame by default, or a polars DataFrame when engine="polars".

Parameters

dataset_id str (required)

Four-segment dataset identifier in the form {cc}.{institution}.{topic}.{frequency}. Example: "rw.nisr.cpi.monthly".

start int | str | None (default None)

Filter rows where the date column is on or after this value. Accepts:

  • An integer year: 2020 (treated as "2020-01-01")
  • An ISO date string: "2020-03-01"
  • None for no lower bound

end int | str | None (default None)

Filter rows where the date column is on or before this value. Same accepted forms as start. Use None for no upper bound.

engine Literal["pandas", "polars"] (default "pandas")

The DataFrame engine to return.

  • "pandas": returns pd.DataFrame. Always available.
  • "polars": returns pl.DataFrame. Requires polars installed (pip install polars).

version str | None (default None)

If given, loads the Iceberg snapshot on or before this date (format: "YYYY-MM-DD"). Requires R2 Iceberg catalog credentials. If None, loads the latest flat Parquet file from the R2 cache.

force_download bool (default False)

If True, bypasses the local Parquet cache at ~/.imibare/cache/ and re-downloads from R2. Has no effect when version is given (Iceberg path does not use the local cache).

Returns

pd.DataFrame when engine="pandas", pl.DataFrame when engine="polars".

Columns match the columns spec in pipeline/catalog/datasets.yaml for the given dataset. Date columns are returned as datetime64[ns] (pandas) or Datetime (polars).

Raises

ValueError if dataset_id is not in the catalog, or if dataset_id does not have exactly four dot-separated segments.

EnvironmentError if R2_ACCOUNT_ID, R2_ACCESS_KEY_ID, or R2_SECRET_ACCESS_KEY are not set when a download is required.

ValueError if version is given but no Iceberg snapshot exists on or before that date.

Examples

import imibare as imi


# Load all CPI data
df = imi.load("rw.nisr.cpi.monthly")


# Filter by year range
df = imi.load("rw.nisr.cpi.monthly", start=2020, end=2023)


# Exact date range
df = imi.load("rw.bnr.fx.daily", start="2024-01-01", end="2024-12-31")


# Polars engine
df = imi.load("rw.nisr.cpi.monthly", engine="polars")


# Historical version (Iceberg-backed datasets)
df = imi.load("rw.nisr.cpi.monthly", version="2025-06-01")


# Force fresh download
df = imi.load("rw.nisr.cpi.monthly", force_download=True)

imibare.catalog()

def catalog(
    country: str | list[str] | None = None,
    topic: str | None = None,
    frequency: str | None = None,
) -> list[DatasetMeta]

Returns a list of dataset metadata objects, optionally filtered.

Parameters

country str | list[str] | None (default None)

ISO 3166-1 alpha-2 country code(s). Case-insensitive.

  • "RW": Rwanda only
  • ["RW", "KE"]: Rwanda and Kenya (future)
  • None: all countries

topic str | None (default None)

Topic slug. Valid values: "macroeconomics", "prices", "labour", "budget", "trade", "demographics", "social-security", "monetary", "tax". Use None for all topics.

frequency str | None (default None)

Frequency slug. Valid values: "daily", "monthly", "quarterly", "annual". Use None for all frequencies.

Returns

list[DatasetMeta]. Returns an empty list if no datasets match the filters.

Examples

import imibare as imi


# All datasets
all_datasets = imi.catalog()


# Rwanda datasets only
rw = imi.catalog(country="RW")


# Price datasets
prices = imi.catalog(topic="prices")


# Monthly Rwanda monetary data
monthly = imi.catalog(country="RW", topic="monetary", frequency="monthly")


# Print summary
for d in imi.catalog(country="RW"):
    print(d.id, d.name)

DatasetMeta

@dataclass
class DatasetMeta:
    id: str                                          # "rw.nisr.cpi.monthly"
    country: str                                     # "RW"
    country_name: str                                # "Rwanda"
    name: str                                        # "Consumer Price Index (monthly)"
    institution: str                                 # "National Institute of Statistics of Rwanda"
    institution_slug: str                            # "nisr"
    topic: str                                       # "prices"
    frequency: str                                   # "monthly"
    coverage_start: str                              # "2009-01"
    coverage_end: str                                # "present" or "YYYY-MM"
    pipeline: Literal["automated", "curated", "stale"]
    source_url: str
    source_format: str                               # "excel" | "pdf" | "json" | "csv" | "html"
    formats: list[str]                               # ["csv", "json", "parquet"]
    license: str                                     # "CC-BY-4.0" | "not-stated" | "all-rights-reserved"
    license_basis: str                               # "publisher-terms" | "permission-granted" | "none-stated"
    columns: list[ColumnSpec]
    last_updated: str                                # ISO 8601 date
    version: str                                     # "YYYY-MM-DD"
    notes: str | None
    license_url: str | None                          # publisher's terms page, where one exists

ColumnSpec

@dataclass
class ColumnSpec:
    name: str           # Column name in the DataFrame
    type: str           # "date" | "string" | "float64" | "int64" | "boolean"
    description: str    # Human-readable description
    unit: str | None    # Unit of measurement, e.g. "index", "RWF", "percent"

imibare.version

imibare.__version__   # str, e.g. "0.2.0"

Environment variables

VariableRequiredDescription
R2_ACCOUNT_IDFor downloadCloudflare account ID
R2_ACCESS_KEY_IDFor downloadR2 API key ID
R2_SECRET_ACCESS_KEYFor downloadR2 API secret
R2_BUCKETNoR2 bucket name (default: "imibare-data")
R2_CATALOG_URLOnly for version=Iceberg catalog endpoint
R2_CATALOG_TOKENOnly for version=Iceberg catalog API token

Cache

Downloaded Parquet files are cached at:

~/.imibare/cache/{country}/{institution}/{topic}/{frequency}/latest.parquet

Specific versions:

~/.imibare/cache/{country}/{institution}/{topic}/{frequency}/{version}.parquet

Use force_download=True to bypass the cache.