@digital4better/data 1.3.73 → 1.3.74

package/README.md

@@ -12,13 +12,13 @@ Available as **JSON and CSV** for analysts, sustainability teams, researchers an
 | --- | --- |
 | Compare AI models, capabilities and estimated sizes | [AI models](./data/ai/README.md) |
 | Identify cloud regions, VM hardware and manufacturing impacts | [Cloud infrastructure](./data/cloud/README.md) |
-| Convert electricity consumption into environmental impacts | [Electricity factors](./data/factor) |
-| Explore electricity generation by geography and period | [Electricity mixes](./data/mix) |
-| Compare electricity production technologies | [Energy impacts](./data/energy) |
+| Convert electricity consumption into environmental impacts | [Electricity factors](./data/factor/README.md) |
+| Explore electricity generation by geography and period | [Electricity mixes](./data/mix/README.md) |
+| Compare electricity production technologies | [Energy impacts](./data/energy/README.md) |
 | Estimate building energy impacts | [Facility factors](./data/facility/README.md) |
 | Estimate employee travel impacts | [Transport factors](./data/transport/README.md) |
-| Model equipment power and manufacturing impacts | [Equipment references](./data/equipment) |
-| Match countries, subdivisions and estimated distances | [Geographic references](./data/country) |
+| Model equipment power and manufacturing impacts | [Equipment references](./data/equipment/README.md) |
+| Match countries, subdivisions and estimated distances | [Geographic references](./data/country/README.md) |
 
 ## Highlights
 
@@ -36,9 +36,7 @@ Regions, VMs, CPUs, accelerators and modeled hosts for AWS, Azure, GCP, Oracle,
 
 **Sources:** official catalogs from [AWS](https://docs.aws.amazon.com/ec2/latest/instancetypes/instance-types.html), [Azure](https://learn.microsoft.com/en-us/azure/virtual-machines/sizes/overview), [GCP](https://docs.cloud.google.com/compute/docs/machine-resource), [Oracle](https://docs.oracle.com/en-us/iaas/Content/Compute/References/computeshapes.htm), [OVHcloud](https://www.ovhcloud.com/en/public-cloud/prices/) and [Scaleway](https://www.scaleway.com/en/docs/instances/reference-content/instances-datasheet/), together with manufacturer specifications.
 
-Region indicators use provider environmental disclosures, including [AWS](https://sustainability.aboutamazon.com/aws-wue-pue.csv), [Microsoft](https://datacenters.microsoft.com/sustainability/efficiency/), [Google](https://cloud.google.com/sustainability/region-carbon), [Oracle](https://www.oracle.com/a/ocom/docs/corporate/citizenship/oracle-corp-citizenship-report-3941904.pdf), [OVHcloud](https://www.ovhcloud.com/sites/default/files/external_files/kpis_fy25.pdf) and [Scaleway](https://www.scaleway.com/en/docs/environmental-footprint/additional-content/calculation-values-reference/).
-
-Read the [cloud guide](./data/cloud/README.md) for units, allocation and assumptions. Hosts are calculation profiles, not a verified server inventory. Regional indicators have different reporting boundaries; zero can be a dataset convention rather than a measured absence of impact.
+The [cloud guide](./data/cloud/README.md) documents environmental disclosures, capacity units, host allocation and provider-specific assumptions.
 
 ### Electricity Mix And Impact Factors
 
@@ -46,7 +44,7 @@ Monthly and yearly data at world, continent, country and subdivision levels, wit
 
 **Sources:** [Ember](https://ember-energy.org/data/yearly-electricity-data/), [UNECE life-cycle assessments](https://unece.org/sed/documents/2021/10/reports/life-cycle-assessment-electricity-generation-options) and [academic literature](https://www.sciencedirect.com/science/article/pii/S0196890422008159#b0530).
 
-Historical territories absent from current source exports retain their previous reference series, with later values carried forward. These are not new observations; see [electricity provenance](./data/electricity-provenance.json). A renewable-only scenario with no eligible generation is unavailable, not zero-impact electricity.
+Read the [mix guide](./data/mix/README.md) for scenarios and historical references, and the [factor guide](./data/factor/README.md) for per-kWh calculations.
 
 ### Facility And Transport
 
@@ -56,7 +54,7 @@ Historical territories absent from current source exports retain their previous
 
 ### Equipment Reference Data
 
-[Equipment references](./data/equipment) support simplified power and manufacturing-impact calculations. [Geographic references](./data/country) support location matching and approximate distance calculations.
+[Equipment references](./data/equipment/README.md) support simplified power and manufacturing-impact calculations. [Geographic references](./data/country/README.md) support location matching and approximate distance calculations.
 
 **Sources:** Digital4Better modeling inputs, life-cycle assessment literature and [ISO country/subdivision conventions](https://www.iso.org/iso-3166-country-codes.html). Distances and equipment factors are reference estimates, not measurements of a specific deployment. See the [usage reference](./llms-full.txt) for their interpretation.
 
@@ -72,7 +70,7 @@ Choose JSON for structured data or CSV for spreadsheets and BI tools. Download f
 | Estimates and sources | Public specifications, observed configurations and calculation hypotheses have different evidential strength. |
 | Availability | Historical cloud offers and AI models remain listed after retirement. |
 
-The [complete reference](./llms-full.txt) documents schemas, all environmental indicators and units, examples and limitations. Source observation dates differ from file modification and package release dates.
+Each dataset guide documents its files, columns, units, sources and limitations. The [usage reference](./llms-full.txt) explains cross-dataset selection and provides examples. Source observation dates differ from file modification and package release dates.
 
 ## Documentation for AI Assistants
 
@@ -85,3 +83,7 @@ Corrections and documented sources are welcome: see [CONTRIBUTING.md](https://gi
 Published under the [Open Database License (ODbL)](./LICENCE). Preserve upstream attribution and notices where applicable.
 
 [Digital4Better](https://digital4better.com) · [fruggr](https://www.fruggr.io) · [GitHub](https://github.com/digital4better/data)
+
+### Versioned AI and cloud sources
+
+The [source registry](sources/catalog.json) and [maintenance guide](sources/README.md) describe publisher references, collection hints, attribution and source lifecycle for AI and the six cloud providers. Read them at the same commit or package version as the datasets. Entries retain specific metadata; shared attribution and verification rules are documented once in the guide. The [schema](sources/catalog.schema.json) distinguishes mandatory catalog/discovery traversal from references checked when used as evidence, with explicit coverage by provider and topic. Active status does not guarantee current availability. Transient collection errors are not stored in the registry.

package/data/cloud/README.md

@@ -124,7 +124,20 @@ Capacity numbers retain their source convention: **GB and GiB are not interchang
 
 Azure GB RAM exceptions include Dnsv6, Dnlsv6, Ensv6, HBv5, Esv7, Ebsv6, Ebdsv6, Ecasv6 and Ecadsv6. Local storage is GB for Lsv4, Lasv4 and Lasv5/Laosv5; GiB for Ddsv7, Dldsv7, Daldsv7, Dcadsv6, Famdsv7 and Faldsv7. TB/TiB totals are reduced to GB/GiB respectively.
 
-Region `pue` is a ratio, `wue` is L/kWh and `ref` is a fraction. Reporting boundaries differ: Google's CFE fraction is not interchangeable with renewable-energy matching. AWS `ref = 0` and Oracle `wue = 0` are dataset conventions, not verified absence of renewable energy or water use. See the [full reference](https://digital4better.github.io/data/llms-full.txt) for provider-specific rules.
+Region `pue` is a ratio, `wue` is L/kWh and `ref` is a fraction. Reporting boundaries differ: Google's CFE fraction is not interchangeable with renewable-energy matching. AWS `ref = 0` and Oracle `wue = 0` are dataset conventions, not verified absence of renewable energy or water use.
+
+### Regional Environmental References
+
+| Provider | Source and interpretation |
+| --- | --- |
+| AWS | [Regional PUE/WUE disclosures](https://sustainability.aboutamazon.com/aws-wue-pue.csv); retained 2024 reference values. REF remains zero by convention. |
+| Azure | [Datacenter efficiency disclosures](https://datacenters.microsoft.com/sustainability/efficiency/) and regional fact sheets, including curated historical values whose original PDFs may no longer be retrievable. |
+| GCP | [Regional carbon data](https://cloud.google.com/sustainability/region-carbon); CFE is used as the REF proxy. Previously derived water values remain pending clearer regional disclosures. |
+| Oracle | [Environmental reporting](https://www.oracle.com/a/ocom/docs/corporate/citizenship/oracle-corp-citizenship-report-3941904.pdf); uniform PUE 1.07 and provisional WUE zero are reference assumptions. |
+| OVHcloud | [FY25 environmental KPIs](https://www.ovhcloud.com/sites/default/files/external_files/kpis_fy25.pdf). |
+| Scaleway | [Calculation reference](https://www.scaleway.com/en/docs/environmental-footprint/additional-content/calculation-values-reference/) and datacenter impact reports. |
+
+Compare reporting periods and regional versus global boundaries before comparing providers. Lower PUE alone does not imply a lower total environmental impact.
 
 ## Methodology
 
@@ -202,7 +215,7 @@ Hardware references also use manufacturer specifications and, where explicitly i
 
 The manufacturing coefficients adapt Teads / Benjamin Davy's [article](https://medium.com/teads-engineering/building-an-aws-ec2-carbon-emissions-dataset-3f0fd76c98ac) and [Scope 3 Ratios spreadsheet](https://docs.google.com/spreadsheets/d/1DqYgQnEDLQVQm5acMAhLgHLD8xXCG9BIrk-_Nv6jF3k/edit), CC BY 4.0. Extensions and allocation rules are Digital4Better assumptions, not vendor-certified LCAs.
 
-For reproducibility, see the [calculation inputs](https://github.com/digital4better/data/blob/main/sources/cloud/host-inputs.json), [calculator](https://github.com/digital4better/data/blob/main/scripts/cloud-hosts.ts) and [hardware source evidence](https://github.com/digital4better/data/blob/main/sources/cloud/host-evidence.json). Detailed changes remain in [Git history](https://github.com/digital4better/data/commits/main/data/cloud) and the [correction log](https://github.com/digital4better/data/blob/main/sources/cloud/hardware-corrections.json).
+For reproducibility, see the [calculation inputs](https://github.com/digital4better/data/blob/main/sources/cloud/host-inputs.json), [calculator](https://github.com/digital4better/data/blob/main/scripts/cloud-hosts.ts) and [hardware source evidence](https://github.com/digital4better/data/blob/main/sources/cloud/host-evidence.json). The inputs drive recalculation; the evidence archive preserves dated observations and source hashes supporting the assumptions. Expected hardware values and their official references are checked by the [regression tests](https://github.com/digital4better/data/blob/main/site/tests/cloud-reference.test.cjs). Detailed before/after changes remain in [Git history](https://github.com/digital4better/data/commits/main/data/cloud).
 
 ## Limitations
 

package/data/cloud/aws-regions.csv

@@ -3,7 +3,7 @@ af-south-1,af-south-1,aws,-33.93,18.42,Cape Town,za,,1.24,0.15,0
 ap-east-1,ap-east-1,aws,22.27,114.16,Hong Kong,hk,,1.15,0.15,0
 ap-south-1,ap-south-1,aws,19.08,72.88,Mumbai,in,,1.42,0.15,0
 ap-south-2,ap-south-2,aws,17.387,78.492,Hyderabad,in,,1.46,0.15,0
-ap-northeast-1,ap-south-1,aws,35.41,139.42,Tokyo,jp,,1.27,0.91,0
+ap-northeast-1,ap-northeast-1,aws,35.41,139.42,Tokyo,jp,,1.27,0.91,0
 ap-northeast-2,ap-northeast-2,aws,37.56,126.98,Seoul,kr,,1.15,0.15,0
 ap-northeast-3,ap-northeast-3,aws,34.69,135.49,Osaka,jp,,1.15,0.15,0
 ap-southeast-1,ap-southeast-1,aws,1.37,103.8,Singapore,sg,,1.32,1.68,0

package/data/cloud/aws-regions.json

@@ -49,7 +49,7 @@
   },
   {
     "id": "ap-northeast-1",
-    "name": "ap-south-1",
+    "name": "ap-northeast-1",
     "provider": "aws",
     "lat": 35.41,
     "lon": 139.42,

package/data/country/README.md

@@ -0,0 +1,50 @@
+# Geographic References
+
+Geographic identifiers, map geometry and approximate distances for joining and visualizing the reference datasets. A territory's presence here does not establish electricity-data coverage.
+
+## Files
+
+| Dataset | Downloads | Purpose |
+| --- | --- | --- |
+| `continents` | [JSON](./continents.json) / [CSV](./continents.csv) | Continent codes and names |
+| `countries` | [JSON](./countries.json) / [CSV](./countries.csv) | Country codes, names and continent membership |
+| `regions` | [JSON](./regions.json) / [CSV](./regions.csv) | Geographic records with type-specific identifiers, area and coordinates |
+| `regions-paths` | [JSON](./regions-paths.json) | SVG path strings keyed by territory identifier; no CSV |
+| `country-to-country-distances` | [JSON](./country-to-country-distances.json) / [CSV](./country-to-country-distances.csv) | Pairwise country distances |
+| `region-to-region-distances` | [JSON](./region-to-region-distances.json) / [CSV](./region-to-region-distances.csv) | Pairwise country/subdivision distances |
+| `user-to-datacenter-distances` | [JSON](./user-to-datacenter-distances.json) / [CSV](./user-to-datacenter-distances.csv) | Area-based distance proxy within each territory |
+
+## File Structure and Units
+
+`continents`, `countries` and `regions` are JSON arrays. Geometry and distance files are objects keyed by identifiers; pairwise distance keys concatenate origin and destination without a separator. Their CSV versions separate the identifiers into columns.
+
+| Field | Meaning / unit |
+| --- | --- |
+| `code` | Continent identifier |
+| `name` | Display name; preserve the source spelling |
+| `alpha-2`, `alpha-3` | Country identifiers where present |
+| `continent` | Continent **code** in `regions`, but continent **name** in `countries` |
+| `subdivision` | Subdivision suffix; combine with country alpha-2 using a hyphen |
+| `type` | Geographic record type; inspect before interpreting optional fields |
+| `area` | Reference area in km2 |
+| `lat`, `lon` | Reference latitude and longitude, decimal degrees |
+| `origin`, `destination` | Source identifiers for a distance pair (CSV) |
+| `distance` | Approximate distance in km |
+
+In `user-to-datacenter-distances.csv`, the historical column name `alpha-2` can also hold a complete subdivision identifier, not only a two-letter country code.
+
+## Using the Data
+
+Resolve identifiers against actual records rather than splitting every key into two-character segments. Prefer pairwise CSV files when separate origin/destination columns are needed. Electricity continent keys use names; cloud country identifiers may be lowercase. Map geometry is a visualization asset, not a factor or coverage list.
+
+## Methodology
+
+Pairwise distances use the spherical distance between reference coordinates, with Earth radius 6,371 km, rounded to three decimals. They are not road or network distances. User-to-datacenter distance uses `sqrt(area / pi)`, rounded to three decimals: the radius of a circle with the territory's area, not a measured path to a known datacenter.
+
+## Sources and Attribution
+
+Digital4Better maintains the geographic reference and derived distances using [ISO country/subdivision conventions](https://www.iso.org/iso-3166-country-codes.html). Record-level geographic and geometry source URLs are not supplied. Preserve identifiers and attribution under the [ODbL license](https://opendatacommons.org/licenses/odbl/1-0/).
+
+## Limitations
+
+Coordinates are representative locations, not site addresses. Distance proxies cannot establish internet routing, latency or actual user-to-server distance. Optional properties vary by geographic type. Historical names and identifiers remain as published; do not assume current administrative completeness.

package/data/energy/README.md

@@ -0,0 +1,40 @@
+# Electricity Generation Technologies
+
+Lifecycle impact factors for producing electricity, by technology. For a territory's electricity consumption, use the [electricity factors](../factor/README.md) instead.
+
+## Files
+
+| Dataset | Downloads |
+| --- | --- |
+| Impacts by generation technology | [JSON](./energy-impacts.json) / [CSV](./energy-impacts.csv) |
+
+## File Structure and Units
+
+JSON is an object keyed by technology name. CSV adds that key as `energy`, with one row per technology. Every indicator is **per kWh generated**; this denominator is not repeated in each record.
+
+| Field | Impact | Unit per kWh |
+| --- | --- | --- |
+| `gwp` | Climate change | kg CO2 eq/kWh |
+| `ap` | Acidification | mol H+ eq/kWh |
+| `ctue` | Freshwater ecotoxicity | CTUe/kWh |
+| `ctuh-c`, `ctuh-nc` | Human toxicity, cancer / non-cancer | CTUh/kWh |
+| `ir` | Ionising radiation | kBq U-235 eq/kWh |
+| `pm` | Particulate matter | disease incidence/kWh |
+| `wu` | Water use | m3 world eq/kWh |
+| `adpe` | Resource use, minerals and metals | kg Sb eq/kWh |
+
+## Using the Data
+
+Multiply generated electricity in kWh by the selected indicator. Match technology names exactly when joining to [electricity mixes](../mix/README.md). Do not add different impact categories together; `wu` is a characterized impact, not physical water consumption in litres.
+
+## Methodology
+
+These lifecycle references are inputs to the electricity-factor model. A mix-weighted impact is the sum of each technology's share multiplied by its factor. Generation technology impacts are distinct from the modeled consumption mix, which also accounts for imports.
+
+## Sources and Attribution
+
+References include [UNECE lifecycle assessments](https://unece.org/sed/documents/2021/10/reports/life-cycle-assessment-electricity-generation-options) and [published research](https://www.sciencedirect.com/science/article/pii/S0196890422008159#b0530). See the [Digital4Better methodology](https://digital4better.github.io/methodology/en/) for context. Preserve source attribution under the repository's [ODbL license](https://opendatacommons.org/licenses/odbl/1-0/).
+
+## Limitations
+
+These are technology-level references, not plant measurements or operational emissions alone. The files do not provide a per-field source mapping, uncertainty interval or regional plant specification. Missing indicators are unavailable, not zero.

package/data/equipment/README.md

@@ -0,0 +1,65 @@
+# Equipment Reference Data
+
+Operational power and allocated manufacturing impacts for generic equipment, virtual machines and network categories. These are modeling references, not product-specific measurements.
+
+## Files
+
+| Dataset | Downloads | Purpose |
+| --- | --- | --- |
+| `energy` | [JSON](./energy.json) / [CSV](./energy.csv) | Operational power or network electricity intensity |
+| `embodied` | [JSON](./embodied.json) / [CSV](./embodied.csv) | Allocated manufacturing impacts |
+
+## File Structure and Units
+
+Both JSON files are objects keyed by category. CSV adds the key as `equipment` and has one row per category.
+
+| Field | Meaning / unit |
+| --- | --- |
+| `equipment` | Category identifier (CSV); JSON object key |
+| `description` | Human-readable category description |
+| `value` | Operational power or electricity intensity, in the entry's `unit` (`energy` only) |
+| `unit` | `W` or `Wh/GB/km` for energy; `/s` or `/GB/km` for embodied impacts |
+
+Embodied indicator units below are **per second** for `/s`, or **per gigabyte-kilometre** for the published `/GB/km` convention.
+
+<details>
+<summary>Embodied impact indicators and numerator units</summary>
+
+| Field | Impact | Numerator unit |
+| --- | --- | --- |
+| `gwp`, `gwpt` | Climate change / total climate change | kg CO2 eq |
+| `gwpb`, `gwplu` | Biogenic / land-use climate change | kg CO2 eq |
+| `ap` | Acidification | mol H+ eq |
+| `ctue` | Freshwater ecotoxicity | CTUe |
+| `ctuh-c`, `ctuh-nc` | Human toxicity, cancer / non-cancer | CTUh |
+| `ir` | Ionising radiation | kBq U-235 eq |
+| `pm` | Particulate matter | disease incidence |
+| `wu` | Water use | m3 world eq |
+| `adpe` | Resource use, minerals and metals | kg Sb eq |
+| `adpf` | Resource use, fossils | MJ |
+| `epf`, `epm`, `ept` | Eutrophication, freshwater / marine / terrestrial | kg P eq / kg N eq / mol N eq |
+| `lu` | Land use, soil quality index | Pt (dimensionless) |
+| `odp` | Ozone depletion | kg CFC-11 eq |
+| `pocp` | Photochemical ozone formation | kg NMVOC eq |
+| `mips` | Material input per service unit | kg |
+
+</details>
+
+## Using the Data
+
+- For power in W: `electricity kWh = value / 1000 * operating hours`. Apply a separately selected [electricity factor](../factor/README.md) to calculate operational impacts.
+- For embodied impacts in `/s`: multiply the indicator by usage seconds. It is already time-allocated; do not divide by a device lifetime again.
+- Network entries use a traffic-and-distance convention: one GB transferred over one km. Keep traffic, distance and allocation assumptions explicit.
+- Do not add overlapping climate indicators such as `gwp`, `gwpt` and their components. Missing values are not zero.
+
+## Methodology
+
+The references separate operational electricity from manufacturing impacts allocated to use. Generic VM factors here are different from provider-specific [cloud VM references](../cloud/README.md): cloud `embodied_allocated` is in tCO2e before time amortization, not kg CO2 eq per second.
+
+## Sources and Attribution
+
+Digital4Better maintains these modeling inputs; see the [impact assessment methodology](https://digital4better.github.io/methodology/en/). Indicator conventions are described by the [European Commission Joint Research Centre](https://publications.jrc.ec.europa.eu/repository/bitstream/JRC130796/JRC130796_01.pdf). The files do not expose individual source URLs or lifetime assumptions for every category. Preserve attribution under the [ODbL license](https://opendatacommons.org/licenses/odbl/1-0/).
+
+## Limitations
+
+Values do not establish the footprint of a particular device, workload or network route. Category averages and historical allocation assumptions may differ from a real deployment. Only compare records with compatible units and boundaries; characterized water impacts are not physical litres.

package/data/factor/README.md

@@ -0,0 +1,52 @@
+# Electricity Impact Factors
+
+Lifecycle impacts per kWh of electricity consumed, by geography and period. These factors combine [electricity mixes](../mix/README.md) with [generation technology impacts](../energy/README.md).
+
+## Files
+
+Files follow `<geography>-<frequency>[-green].json`, each with a matching CSV. Every geography below has yearly/monthly and full/green variants.
+
+| Geography | Yearly full mix | Monthly full mix |
+| --- | --- | --- |
+| Country | [JSON](./country-yearly.json) / [CSV](./country-yearly.csv) | [JSON](./country-monthly.json) / [CSV](./country-monthly.csv) |
+| Subdivision | [JSON](./subdivision-yearly.json) / [CSV](./subdivision-yearly.csv) | [JSON](./subdivision-monthly.json) / [CSV](./subdivision-monthly.csv) |
+| Continent | [JSON](./continent-yearly.json) / [CSV](./continent-yearly.csv) | [JSON](./continent-monthly.json) / [CSV](./continent-monthly.csv) |
+| World | [JSON](./world-yearly.json) / [CSV](./world-yearly.csv) | [JSON](./world-monthly.json) / [CSV](./world-monthly.csv) |
+
+Add `-green` before the extension for the renewable-only variant, for example [country-yearly-green.json](./country-yearly-green.json) / [CSV](./country-yearly-green.csv).
+
+## File Structure and Units
+
+Territorial JSON uses `{ territory: { period: { indicator: value } } }`. World JSON uses `{ period: { indicator: value } }`, without a world wrapper. CSV has one row per territory/period, or per period for world files.
+
+| Field | Meaning / unit |
+| --- | --- |
+| `country`, `subdivision` | Source territory identifier, such as `FR` or `CA-QC` |
+| `continent` | Continent name, not its code |
+| `year`, `period` | Yearly `YYYY` / monthly `YYYY-MM` period |
+| `gwp` | Climate change, kg CO2 eq/kWh |
+| `ap` | Acidification, mol H+ eq/kWh |
+| `ctue` | Freshwater ecotoxicity, CTUe/kWh |
+| `ctuh-c`, `ctuh-nc` | Human toxicity, cancer / non-cancer, CTUh/kWh |
+| `ir` | Ionising radiation, kBq U-235 eq/kWh |
+| `pm` | Particulate matter, disease incidence/kWh |
+| `wu` | Water use, m3 world eq/kWh |
+| `adpe` | Resource use, minerals and metals, kg Sb eq/kWh |
+
+## Using the Data
+
+`impact = consumed kWh * selected factor`. For example, a fictional factor of 0.05 kg CO2 eq/kWh gives 5 kg CO2 eq for 100 kWh.
+
+Select the exact geography, period, scenario and indicator. Check subdivisions before concluding that only national data exists, but do not assume every subdivision is covered. Missing properties, `null` and empty CSV cells are unavailable, not zero. Do not add different impact categories or interpret `wu` as physical litres.
+
+## Methodology
+
+Factors are technology-share-weighted lifecycle impacts for the modeled consumption mix. The [mix guide](../mix/README.md#methodology) defines import processing, volume-weighted geographic aggregation, renewable-only scenarios, missing-period fallbacks and historical-series retention. These rules apply to factor files as well; the `-green` suffix is not proof of zero-carbon electricity or a supplier contract.
+
+## Sources and Attribution
+
+Generation and import inputs are documented in the [mix sources](../mix/README.md#sources-and-attribution); lifecycle inputs come from the [energy references](../energy/README.md#sources-and-attribution), including Ember and UNECE respectively. Preserve source attribution under the [ODbL license](https://opendatacommons.org/licenses/odbl/1-0/).
+
+## Limitations
+
+Factors are not instantaneous or marginal emission measurements. Filled or carried-forward periods are not necessarily new observations. Country/continent/world values cannot silently replace missing local data; record any substitution. For fuel energy rather than grid electricity, use the separately scoped [facility factors](../facility/README.md).

package/data/mix/README.md

@@ -0,0 +1,57 @@
+# Electricity Mixes
+
+Modeled electricity technology shares by geography and period, with full-mix and renewable-only scenarios. Use [electricity factors](../factor/README.md) to convert electricity consumption into environmental impacts.
+
+## Files
+
+Files follow `<geography>-<frequency>[-green].json`, each with a matching CSV. Every geography below has yearly/monthly and full/green variants.
+
+| Geography | Yearly full mix | Monthly full mix |
+| --- | --- | --- |
+| Country | [JSON](./country-yearly.json) / [CSV](./country-yearly.csv) | [JSON](./country-monthly.json) / [CSV](./country-monthly.csv) |
+| Subdivision | [JSON](./subdivision-yearly.json) / [CSV](./subdivision-yearly.csv) | [JSON](./subdivision-monthly.json) / [CSV](./subdivision-monthly.csv) |
+| Continent | [JSON](./continent-yearly.json) / [CSV](./continent-yearly.csv) | [JSON](./continent-monthly.json) / [CSV](./continent-monthly.csv) |
+| World | [JSON](./world-yearly.json) / [CSV](./world-yearly.csv) | [JSON](./world-monthly.json) / [CSV](./world-monthly.csv) |
+
+Add `-green` before the extension for the renewable-only variant, for example [country-yearly-green.json](./country-yearly-green.json) / [CSV](./country-yearly-green.csv).
+
+## File Structure and Units
+
+Territorial JSON uses `{ territory: { period: { technology: share } } }`. World JSON uses `{ period: { technology: share } }`, without a world wrapper. CSV has one row per territory/period, or per period for world files.
+
+| Field | Meaning / unit |
+| --- | --- |
+| `country` | Country identifier, such as `FR` |
+| `subdivision` | Subdivision identifier, such as `CA-QC` |
+| `continent` | Continent name, not its code |
+| `year` | Yearly period, `YYYY` |
+| `period` | Monthly period, `YYYY-MM` |
+| `Bioenergy`, `Coal`, `Gas`, `Hydro`, `Nuclear`, `Other Fossil`, `Other Renewables`, `Solar`, `Wind` | Technology shares, dimensionless fractions from 0 to 1 |
+
+## Using the Data
+
+Multiply a share by 100 to display a percentage. Preserve technology spelling when joining to [generation impacts](../energy/README.md). Shares may not sum to exactly one because of rounding. Missing or `null` values are unavailable, not zero.
+
+Choose geography, period and scenario explicitly. One subdivision file does not imply coverage of every subdivision. Broader geographic averages are substitutions, not equivalent observations.
+
+## Methodology
+
+Source generation shares, volumes and net imports feed a modeled consumption mix. Continent/world aggregation is volume-weighted, not a simple average of country shares.
+
+The `-green` scenario keeps **Bioenergy, Hydro, Solar and Wind**, renormalized to one. It excludes Nuclear and Other Renewables. If no eligible source is available, the scenario is unavailable. This is a hypothetical mix, not a territory's actual supply or proof of a green electricity contract.
+
+### Missing Periods and Historical References
+
+Missing periods can reuse earlier values. Without an earlier value, monthly series can use annual values; geographic fallbacks can use country, continent or world references. Not every filled value is individually flagged, and a current-year series need not represent complete observations.
+
+Territories entirely absent from current Ember exports retain their previously published country series across both mix and factor variants. Later periods carry the last reference forward. These are **historical references, not new observations**. Current upstream data takes precedence when a territory returns. Preserved series are restored after aggregation: historical raw energy volumes are unavailable, so those series must not be used to invent world/continent weights.
+
+The [provenance metadata](https://digital4better.github.io/data/electricity-provenance.json) records the pinned snapshot, territories and period coverage. In the repository and npm package it is stored at `scripts/electricity-provenance.json`, alongside the history script rather than among datasets. Original observation dates are unknown; release dates are not measurement dates.
+
+## Sources and Attribution
+
+Global series use [Ember electricity data](https://ember-energy.org/data/yearly-electricity-data/). Subnational inputs also use [Statistics Canada](https://www150.statcan.gc.ca/t1/tbl1/en/tv.action?pid=2510001501) and the [US EIA](https://www.eia.gov/opendata/browser/electricity/electric-power-operational-data). See the [Digital4Better methodology](https://digital4better.github.io/methodology/en/) and preserve upstream attribution with the [ODbL license](https://opendatacommons.org/licenses/odbl/1-0/).
+
+## Limitations
+
+These are modeled temporal references, not real-time grid measurements. Coverage, source periods and import assumptions vary. Do not infer marginal electricity, hourly matching or a supplier's physical delivery from these shares. A fresh file timestamp does not imply a fresh observation for every value.