Methods
Every value on the site can be traced from the number on the page back to the source's series ID, the fetch that retrieved it and the formula, if any, that transformed it. This page describes each step as it is implemented in the code, not as it is planned.
Trust model
The badge appears wherever a value appears. The kinds are never blended: an observed series is never mixed with a modeled fill, and a recommendation is never shown as a measurement.
A value published by the cited source and ingested without transformation.
Stored exactly as the source reports it, in the source's own unit, with the source series ID, the source's release label and the time we fetched it.
Example: Life expectancy at birth, World Bank series SP.DYN.LE00.IN.
A deterministic, versioned formula over observed values.
Recomputed after every ingestion of its components. Each value records the formula version and the component releases it was computed from, so it can be reproduced.
Example: Patent applications = resident + non-resident applications, version 1.0.
An estimate that depends on assumptions, statistical inference or a simulation.
Not yet used. When a modeled metric is added it will carry its assumptions and uncertainty on the metric page and will never be listed as observed.
Example: None in the catalog today.
A normative or strategic suggestion: what should be done, not what is.
Only the principles page carries recommended content today. Recommendations never appear as values in the catalog.
Example: The 25 proposed directions on the Principles page.
Direction is a separate attribute from kind. Each metric is declared higher_better, lower_better or contextual in the catalog. Contextual metrics (population, CO2 per person, capital formation share) are never read as improving or worsening.
Pipeline
Ingestion is a script run on a schedule against the production database. Each source has an adapter that knows how to fetch and parse that provider; the runner is the same for every source.
Create the run
One ingestion_runs row per source per run, with the adapter's parser version and the requested metric list.
Fetch
The source adapter requests one series at a time. A metric can list several series in priority order; the next is tried only when the first returns no usable values.
Snapshot
The raw response is hashed (sha256) and its byte size recorded in source_snapshots. Where the license permits, the raw file is also stored on disk so the derivation can be reproduced later.
Parse
Rows are mapped to the parsed observation shape: metric slug, geography code, period start, value, source series ID, source release label, unit.
Validate
Rows are rejected when the period is not a parseable date, the unit does not match the catalog unit, the value is not a finite number, or the value falls outside the plausibility bounds set for the metric in the catalog. Rejections are counted in the run and never written.
Resolve geography
Codes are matched to the canonical geography table (world, countries, source aggregates). Aggregates such as income groups are kept as aggregates and are never equated with continents. Unknown codes are inserted as unclassified rather than dropped.
Compare with the previous ingestion
Each row is compared with the current stored value for the same metric, geography and period. Unchanged values write nothing. Changed values are flagged as extreme revisions when they move more than 25 percent; the run records every such case.
Append
New and revised values are inserted as new rows. Nothing is updated or deleted. Null values from the source are not stored.
Run derived metrics
Every derived metric recomputes from the current values of its components using the latest methodology version, attributed to the Humanity Vector methodology source.
Close the run
Status, rows seen, rows written, an error summary and per-metric outcomes are written to the run. A failed fetch closes the run as failed and leaves every existing observation in place.
Units are not normalised in the database. The source unit is retained on every observation and the catalog declares the display unit; a mismatch is a validation failure, not a silent conversion. Every ingestion run, with its counts and outcomes, is listed on the source pages and on the home page.
History
The observation table is append-only. A refresh never updates or deletes a row. When a source revises a value, the new value arrives as a new row with a later ingestion time and the source’s own release label stored as the revision marker.
The value shown on a page is always the most recently ingested row for that metric, geography and period. Every earlier row for the same period is kept and listed under revisions on the metric page, so a visitor can see what the value used to be and when it changed.
A revision larger than 25 percent is flagged in the ingestion run as an extreme revision. It is still stored; the flag exists so that a source error or a methodology change at the provider is noticed rather than absorbed.
Derived values follow the same rule. When a component is revised the derivation reruns and writes a new row; the previous derived value stays in the revision history with the component releases it was built from.
Definitions as implemented
These are the exact rules the code applies. They operate on the current value for each period of one geography (world unless a page says otherwise). Periods with no value are ignored.
latest minus the value exactly one period earlier. One period is one year for annual series, three months for quarterly, one month for monthly, one day for daily. If that exact period has no value the change is null and the page says n/a; the nearest available period is not substituted. The relative change is the absolute change divided by the absolute earlier value, null when the earlier value is zero.(latest / value ten periods earlier) ^ (1/10) minus 1. Null if that period is missing or if either value is not positive. For annual series ten periods is ten years; every series in the catalog today is annual. The absolute and relative ten-period changes are computed the same way as the one-year figures.higher_better a positive change is improving and a negative one worsening; for lower_better the reverse. A change of exactly zero is flat. A contextual metric is always reported as contextual, never improving or worsening, whatever the sign. A null change is reported as flat (or contextual) with no percentage.higher_better metrics, its negative for lower_better, excluded for contextual. The five highest positive scores are the fastest improving; the five lowest negative scores are the fastest worsening. Modeled and recommended items can never appear in either list. No smoothing, no weighting, no five-year window and no acceleration is computed.Staleness
Freshness is a property of a source, not of an observation. It is the time elapsed since the last successful ingestion run for that source, in whole days. A source is stale when that age exceeds its threshold, or when it has never had a successful run. The last run’s status is shown alongside so a recent failure is visible even when the last success is within threshold.
The threshold comes from the source’s catalog entry (stale_after_days) when set. Otherwise it is inferred from the declared update cadence: daily sources 3 days, weekly 10, monthly 45, quarterly 120, anything else 400. Annual sources are polled weekly but are only stale after 400 days.
Freshness says when we last fetched successfully. The observation date on each value says what period the value describes. A fresh source can still publish values that are two years old; both facts are shown.
Sources in the catalog
| Source | Declared cadence | Stale after |
|---|---|---|
| Humanity VectorHumanity Vector documented derivations | recomputed after every ingestion of component series | 400 days |
| World BankWorld Development Indicators | annual, revised continuously | 400 days |
Formulas
Every metric carries a methodology version. Observed metrics are at version 1.0 unless their definition or source series changes. Derived metrics keep a table of method versions, each with an effective date, the formula, the component metrics and a methodology note in plain language, all shown on the metric page.
Changing a formula changes the metric. The change is recorded as a new version with its rationale; the derivation reruns under the new version; values written under the old version remain in the revision history labelled with the version they were computed under. Each derived observation names its version and the component releases it used, so it can be recomputed by anyone with the same inputs.
The same rule will apply to any future vector aggregate or bottleneck threshold: no aggregate is published until its formula, components and version are written down here first.
A derived value records
Public channel
Anyone can report a wrong value, a mis-stated definition, a licensing problem, or a formula they think is wrong. For now the channel is email: info@allcontrax.com. A public correction log with status and resolution will replace this once there is more than one source.
A useful report names:
Methodology challenges are handled by branching: a competing formula becomes a new version or a new metric, alongside the existing one, never by silently editing stored values.
A correction record will contain
Scope
A single civilization score
One number embeds large normative weights. The site publishes a vector of dimensions and, until formulas are implemented and versioned, no aggregate for any dimension either.
Direction arrows for vector dimensions
The arrows sketched in the design pack are illustrations of a future display, not findings. Each dimension shows only the computed change of its headline metric, or an honest empty state.
Bottleneck ratings
Severity labels must come from documented thresholds (utilization, reserve margin, lead time, concentration). Those thresholds are not written yet, so no bottleneck is rated.
Modeled metrics
No estimate depending on assumptions or inference is in the catalog. When one is added it will carry the modeled badge and its assumptions.
Recommendations attached to metrics
Normative content is confined to the Principles page and labelled as such.
AI-generated numbers
No value on the site is produced or filled in by a language model. Page rendering does not depend on any AI service.
User accounts, comments, weighting tools
The data system has to be trustworthy before social features are layered on it.
Five-year windows, acceleration, smoothing
Only the one-period and ten-period comparisons described above are computed. Acceleration (change in the rate of change) is not shown until a documented method exists.
Read the Vector page for component coverage per dimension and the Bottlenecks page for what a rated bottleneck will contain.