# earth-now.co
# Author:  Simon-Pierre Boucher
# Contact: contact@spboucher.ai
# File:    packages/registry/metrics/population.yaml
# Purpose: MVP population & demography metrics (catalog §1, all 🥇) — UN WPP driven

metrics:
  - id: world_population
    name: { fr: "Population mondiale", en: "World population" }
    domain: population
    priority: mvp
    kind: stock
    level: 2
    model: seasonal-spline-v2
    unit: people
    sources:
      - id: un_wpp_2024
        name: "UN World Population Prospects 2024"
        url: https://population.un.org/wpp/
        license: "CC BY 3.0 IGO"
        cadence: yearly
        variants: [low, median, high]
    refresh: on_source_update
    display:
      decimals: 0
      sigFigs: 7
      unit: { fr: "personnes", en: "people" }
    constraints: { maxAbsRatePerSec: 10, maxJumpOnRefit: 5000000 }
    windows: [total]

  - id: births_ytd
    name: { fr: "Naissances cette année", en: "Births this year" }
    domain: population
    priority: mvp
    kind: cumulative
    level: 1
    model: seasonal-ytd-v1
    unit: people
    sources:
      - id: un_wpp_2024
        name: "UN World Population Prospects 2024 (derived crude birth rate)"
        url: https://population.un.org/wpp/
        license: "CC BY 3.0 IGO"
        cadence: yearly
    refresh: on_source_update
    display:
      decimals: 0
      sigFigs: 6
      unit: { fr: "personnes", en: "people" }
    constraints: { maxAbsRatePerSec: 8, maxJumpOnRefit: 500000 }
    windows: [ytd, today, session]

  - id: births_today
    name: { fr: "Naissances aujourd'hui", en: "Births today" }
    domain: population
    priority: mvp
    kind: derived
    level: derived
    model: derived
    unit: people
    sources:
      - id: un_wpp_2024
        name: "UN World Population Prospects 2024 (derived)"
        url: https://population.un.org/wpp/
        license: "CC BY 3.0 IGO"
        cadence: yearly
    refresh: on_source_update
    display:
      decimals: 0
      sigFigs: 5
      unit: { fr: "personnes", en: "people" }
    windows: [today, session]
    derived:
      op: window
      window: today
      inputs: [{ id: births_ytd, weight: 1 }]

  - id: deaths_ytd
    name: { fr: "Décès cette année", en: "Deaths this year" }
    domain: population
    priority: mvp
    kind: cumulative
    level: 1
    model: seasonal-ytd-v1
    unit: people
    sources:
      - id: un_wpp_2024
        name: "UN World Population Prospects 2024 (derived crude death rate)"
        url: https://population.un.org/wpp/
        license: "CC BY 3.0 IGO"
        cadence: yearly
    refresh: on_source_update
    display:
      decimals: 0
      sigFigs: 6
      unit: { fr: "personnes", en: "people" }
    constraints: { maxAbsRatePerSec: 4, maxJumpOnRefit: 300000 }
    windows: [ytd, today, session]
    editorialNote:
      fr: "Compteur de mortalité : ton sobre, source et méthode affichées au clic, pas de gamification."
      en: "Mortality counter: sober tone, source and method shown on click, no gamification."

  - id: deaths_today
    name: { fr: "Décès aujourd'hui", en: "Deaths today" }
    domain: population
    priority: mvp
    kind: derived
    level: derived
    model: derived
    unit: people
    sources:
      - id: un_wpp_2024
        name: "UN World Population Prospects 2024 (derived)"
        url: https://population.un.org/wpp/
        license: "CC BY 3.0 IGO"
        cadence: yearly
    refresh: on_source_update
    display:
      decimals: 0
      sigFigs: 5
      unit: { fr: "personnes", en: "people" }
    windows: [today, session]
    derived:
      op: window
      window: today
      inputs: [{ id: deaths_ytd, weight: 1 }]
    editorialNote:
      fr: "Compteur de mortalité : ton sobre, source et méthode affichées au clic, pas de gamification."
      en: "Mortality counter: sober tone, source and method shown on click, no gamification."

  - id: heartbeats_ytd
    name: { fr: "Battements de cœur humains cette année", en: "Human heartbeats this year" }
    domain: population
    priority: v1
    kind: cumulative
    level: 0
    model: linear-ytd-v1
    unit: beats
    sources:
      - id: derived_heartbeats
        name: "Dérivé pédagogique — population ONU WPP × ~70 battements/min"
        url: https://population.un.org/wpp/
        license: "CC BY 3.0 IGO (population); heart-rate factor: physiology literature"
        cadence: yearly
    refresh: on_source_update
    display:
      decimals: 0
      sigFigs: 4
      unit: { fr: "battements", en: "beats" }
    constraints: { maxAbsRatePerSec: 20000000000, maxJumpOnRefit: 1000000000000000 }
    windows: [today, ytd, session]
    uncertaintyFraction: 0.1
    editorialNote:
      fr: "Compteur pédagogique : population mondiale × ~70 battements/min en moyenne — ordre de grandeur, intervalle affiché."
      en: "Pedagogical counter: world population × ~70 beats/min on average — order of magnitude, interval displayed."

  - id: heartbeats_today
    name: { fr: "Battements de cœur aujourd'hui", en: "Heartbeats today" }
    domain: population
    priority: v1
    kind: derived
    level: derived
    model: derived
    unit: beats
    sources:
      - id: derived_heartbeats
        name: "Dérivé pédagogique (derived)"
        url: https://population.un.org/wpp/
        license: "CC BY 3.0 IGO (population); heart-rate factor: physiology literature"
        cadence: yearly
    refresh: on_source_update
    display:
      decimals: 0
      sigFigs: 4
      unit: { fr: "battements", en: "beats" }
    windows: [today, session]
    derived:
      op: window
      window: today
      inputs: [{ id: heartbeats_ytd, weight: 1 }]
    uncertaintyFraction: 0.1

  - id: net_growth_today
    name: { fr: "Croissance nette aujourd'hui", en: "Net population growth today" }
    domain: population
    priority: mvp
    kind: derived
    level: derived
    model: derived
    unit: people
    sources:
      - id: un_wpp_2024
        name: "UN World Population Prospects 2024 (births − deaths)"
        url: https://population.un.org/wpp/
        license: "CC BY 3.0 IGO"
        cadence: yearly
    refresh: on_source_update
    display:
      decimals: 0
      sigFigs: 5
      unit: { fr: "personnes", en: "people" }
    windows: [today, ytd, session]
    derived:
      op: linear-combination
      inputs:
        - { id: births_ytd, weight: 1 }
        - { id: deaths_ytd, weight: -1 }