africatic/africa-world-bank-energy-mining-time-series

Africa World Bank Energy and Mining Labeled Time Series Data

This repository is part of the Africa Temporal Intelligence Corpus (ATIC). It contains sector-specific temporal corpus packages for African countries.

ATIC sector repositories are designed for machine consumption first: Parquet tables, stable IDs, reproducible metadata, explicit provenance, review status, and separable semantic layers.

Sector Scope

Temporal energy indicators for African countries, including access, consumption, clean cooking, and energy-mix transition signals.

Technical scope:

• —electricity access
• —clean cooking access
• —energy consumption per capita
• —alternative and nuclear share of energy use
• —collection-guided source grouping: Africa · World Bank Indicators

Repository Layout

README.md
sector_manifest.yaml
packages/
  <package_id>/
    raw.parquet
    labels.parquet
    events.parquet
    relationships.parquet
    reasoning.jsonl
    metadata.yaml
    quality_report.json
    README.md
    LICENSE
    CHANGELOG.md
schemas/
ontology/
sources/
docs/
tools/

Package Index

Table Contract

Each package follows the ATIC dataset package contract:

• —raw.parquet: source observations after light normalization.
• —labels.parquet: proposed or reviewed statistical and temporal annotations.
• —events.parquet: discrete events linked to evidence.
• —relationships.parquet: temporal relationships between observations, labels, and events.
• —reasoning.jsonl: generated explanations kept separate from approved labels.
• —metadata.yaml: package identity, source provenance, schema version, license, review status, and evidence catalog.
• —quality_report.json: row counts, source columns, parse failures, coverage gaps, label distributions, thresholds, quality flags, quality score, and review priority.

The canonical schema files are included under schemas/.

Required raw.parquet columns:

observation_id, timestamp, country_iso3, domain, indicator, value, unit,
source_provider, source_dataset, source_record_id, observation_status,
ingestion_version

Required labels.parquet columns:

label_id, observation_id, timestamp, country_iso3, domain, indicator,
annotation_level, label_type, label_value, confidence, evidence_id,
review_status, annotator, annotation_version, created_at

Annotation Semantics

ATIC separates source observations from interpretation.

Current seed packages include:

• —annotation_level = 2: statistical labels such as year-over-year delta anomalies.
• —annotation_level = 3: temporal state labels such as increasing, decreasing, and stable.
• —review_status = proposed: automatically generated, not yet human-approved.

Confidence values are bounded from 0.0 to 1.0. They are scoring hints for review priority, not truth guarantees.

Loading Examples

Use huggingface_hub and pyarrow:

from huggingface_hub import hf_hub_download
import pyarrow.parquet as pq

repo_id = "africatic/africa-world-bank-energy-mining-time-series"
path = hf_hub_download(
    repo_id=repo_id,
    repo_type="dataset",
    filename="packages/somalia_eg_elc_accs_ru_zs_v0_1/raw.parquet",
)
raw = pq.read_table(path).to_pandas()
print(raw.head())

Query with DuckDB:

import duckdb
from huggingface_hub import hf_hub_download

labels_path = hf_hub_download(
    repo_id="africatic/africa-world-bank-energy-mining-time-series",
    repo_type="dataset",
    filename="packages/somalia_eg_elc_accs_ru_zs_v0_1/labels.parquet",
)

duckdb.sql("""
    select timestamp, label_type, label_value, confidence
    from read_parquet(?)
    where review_status = 'proposed'
    order by timestamp
""", params=[labels_path]).show()

Validation

After downloading or cloning this repository, validate a package with:

python3 tools/validate_dataset.py packages/somalia_eg_elc_accs_ru_zs_v0_1

Validation checks:

• —required package files
• —metadata JSON Schema compatibility
• —required Parquet columns
• —broad Parquet type families
• —reasoning JSONL schema
• —quality report structure and parquet row-count agreement

Upstream Sources

Current upstream Electric Sheep Africa datasets:

• —electricsheepafrica/africa-world-bank-energy-and-mining-indicators-for-eswatini
• —electricsheepafrica/africa-world-bank-energy-and-mining-indicators-for-ethiopia
• —electricsheepafrica/africa-world-bank-energy-and-mining-indicators-for-federal-republic-of-somalia
• —electricsheepafrica/africa-world-bank-energy-and-mining-indicators-for-ghana
• —electricsheepafrica/africa-world-bank-energy-and-mining-indicators-for-guinea-bissau
• —electricsheepafrica/africa-world-bank-energy-and-mining-indicators-for-kenya
• —electricsheepafrica/africa-world-bank-energy-and-mining-indicators-for-somalia
• —electricsheepafrica/africa-world-bank-energy-and-mining-indicators-for-somalia-fed-rep
• —electricsheepafrica/africa-world-bank-energy-and-mining-indicators-for-south-africa
• —electricsheepafrica/africa-world-bank-energy-and-mining-indicators-for-south-sudan
• —electricsheepafrica/africa-world-bank-energy-and-mining-indicators-for-uganda
• —electricsheepafrica/africa-world-bank-energy-and-mining-indicators-for-zambia
• —electricsheepafrica/africa-world-bank-energy-and-mining-indicators-for-zimbabwe

Country information is preserved from source file paths where upstream rows do not include explicit country columns.

Provenance

Every package records:

• —upstream provider
• —Hugging Face dataset ID
• —source file path
• —source revision SHA
• —retrieval date
• —generation script
• —statistical method
• —evidence IDs
• —review status

This makes each annotation inspectable and reproducible.

Responsible Use

The seed labels in this repository are statistical proposals. They are useful for temporal retrieval, QA, prioritizing review, and building benchmark tasks. They should not be treated as expert-approved facts until their review_status changes to approved.