Allotaxonometer

Rust

get /storywrangler/allotax

Compares two type-frequency systems using the allotaxonometer (rank-turbulence divergence).

Each system is defined by a dataset, an optional entity, a date range, and optional filter values. The two systems may differ on any combination of axes:

entity vs entity — e.g. US Wikipedia vs UK Wikipedia
dates vs dates — e.g. October vs November
filter-only — e.g. sex=M vs sex2=F (skipping entity registry)

Filter dimensions — look up a dataset's available filter dimensions via GET /registry/{domain}/{dataset_id} (transform.filter_dimensions). Pass them as extra query params using the dim / dim2 suffix convention: ?sex=M&sex2=F compares boy vs girl babynames, ?geo=US&geo2=CA compares countries. Entity registration is optional when a filter dimension serves as the comparison axis.

Query Parameters

domain string

Domain owning the dataset

dataset string

Dataset ID within the domain

entity

Global entity ID for system 1, e.g. 'wikidata:Q30' (United States). Optional — omit for datasets using filter_dimensions as the comparison axis.

entity2

Global entity ID for system 2, e.g. 'wikidata:Q145' (United Kingdom). Optional — omit for datasets using filter_dimensions as the comparison axis.

dates

Date/year range for system 1. Single value '2024-10-01' or range '2024-10-01,2024-10-31'. Omit to load all time.

dates2

Date/year range for system 2. Omit to load all time.

alpha string

RTD alpha parameter (number or 'inf')

alphas

Comma-separated alphas for multi-alpha mode, e.g. '0.5,1.0,inf'

ngram_limit integer

Max types to load per system before computing

wordshift_limit integer

Truncate wordshift output to top N entries

Available Datasets

Pass these as additional query parameters using the actual column names from each dataset.

babynames/ngrams

Baby names by popularity, year, and location with entity mappings

No filter dimensions.

reddit/ngrams

Reddit ngrams

n default: 1 · 1, 2

lang default: af · af, als, am, an, ar …and 162 more

vt-zoning-atlas/ngrams

Vermont zoning bylaw word frequencies by town.

No filter dimensions.

wikimedia/ngrams

Wikipedia n-grams by frequency, date, and location with entity mappings and ranks

ngram_size default: 1 · 1, 2

granularity default: daily · daily, monthly, weekly

Response

normalization number

Normalization constant for the rank-turbulence divergence

delta_sum number

Sum of normalized divergence elements — the actual D_alpha^R value

diamond_counts array

2D rank-space histogram used to render the diamond plot

max_delta_loss number

Maximum delta-loss value (used for color-scale normalization)

ncells integer

Number of cells along one side of the diamond grid; use to size the band scale

maxlog10 number

Largest log10(rank) across both systems, rounded up to at least 1; use to label diamond axes

alpha number

Alpha parameter used in the computation

balance number

Balance measure between the two systems (0.5 = equal, >0.5 = system 2 dominates)

wordshift array

Top contributing types, sorted by absolute divergence contribution.

meta object

Request metadata echoed back

curl -X GET http://localhost:8000/storywrangler/allotax \