Verbs

A get_tossd()-shaped frame carrying {dimension}_code, {dimension}_name, and value.

The dimension to group by -- any prefix with a matching {dimension}_code/{dimension}_name column pair in df.

The amount column to sum and rank by.

Keep only the first top rows after ranking and sorting. None (the default) keeps every ranked row.

False (the default) drops is_aggregate rows (the provider_code == 0 pseudo-aggregates) before ranking.

One row per distinct ({dimension}_code, {dimension}_name) pair

(an observed=True groupby -- an unused category never appears),

sorted by summed value descending: {dimension}_code,

{dimension}_name, value, n_activities (only when df carries

tossd_id -- distinct tossd_id per group, excluding the "0000"

placeholder used for bundled lines with no activity identifier, so

those lines are never counted as activities; omitted entirely,

rather than raising, when tossd_id isn't present), share_pct

(of the summed total across every included row, 0-100 scale,

unrounded), and rank (competition ranking -- tied entries share

the lower rank number -- 1-based, descending). Truncation to top

happens after ranking, so the numbering on the entities that made

the cut always matches what a caller would see without top set.

The "0000" placeholder also lands on a small share of real

providers' own rows in 2023-24 (bundled lines belonging to a real

provider, not just pseudo-aggregates), so n_activities can

slightly undercount those providers even after aggregate exclusion.

df is missing {dimension}_code, {dimension}_name, or value; value is not numeric; or (when include_aggregates=False) df has no is_aggregate column.

A get_tossd()-shaped frame carrying year, provider_code, provider_name, and value.

The amount column to sum per year.

"consistent" (the default) restricts every year to the (provider_code, provider_name) pairs present in every year df covers, so a year's total isn't inflated by a provider that only reported in some years. "all" disables that restriction -- every row counts, whichever years its provider happens to appear in.

False (the default) drops is_aggregate rows before comparing years.

One row per year present in df: year, value, n_providers

(the cohort's size under "consistent"; the year's own distinct

provider-pair count under "all"), and pct_change (percent

change from the previous row's value, 0-100 scale, unrounded;

NA for the first -- or only -- year). `result.attrs

["structural_breaks"]carriesget_structural_breaks(years=...)`'s

rows intersecting the years covered, so a caller can flag a jump

against a known discontinuity instead of a real trend.

df is missing year, provider_code, provider_name, or value; value is not numeric; cohort is not "consistent"/"all"; (when include_aggregates=False) df has no is_aggregate column; or cohort="consistent" and no provider pair is present in every year.

A get_tossd()-shaped frame carrying sdg_codes_raw and value.

The amount column to sum.

"goal" (the default) groups by SDG goal (sdg_goal); "code" groups by the exact token published in sdg_codes_raw (sdg_code), keeping goals and targets apart. The publisher formats some goal-level tags as a trailing-.0 token (e.g. "5.0", no real SDG target is numbered .0); at level="code" each such token gets its own row, while level="goal" folds it into its goal like any other goal-level tag.

Keep only the first top rows after ranking and sorting. None (the default) keeps every row.

False (the default) drops is_aggregate rows before exploding.

One row per distinct goal or code (matching level): sdg_goal

or sdg_code, value (the weighted sum), share_pct (of the

SDG-tagged total across every included row, 0-100 scale,

unrounded), and rank (competition ranking, descending,

1-based). Truncation to top happens after ranking.

value is missing or not numeric; level is not "goal"/"code"; df is missing sdg_codes_raw or already carries explode_sdg's own output columns (both raised by sdg_totals() itself, naming sdg_totals() -- not a delegated explode_sdg message); or (when include_aggregates=False) df has no is_aggregate column.

A get_tossd()-shaped frame carrying keywords_raw and value.

One marker name, an iterable of them, or None (the default) for all 12 packaged markers. Each name is matched with or without its kw_ prefix ("gender" and "kw_gender" both match); an unrecognised name raises, naming the closest matches.

The amount column to sum.

False (the default) drops is_aggregate rows before summing.

One row per requested marker, in the order given (packaged order

when markers=None), plus a final "Combined" row: marker,

value, n_rows (a row count of the marker's mask, not a

distinct-tossd_id count -- the publisher's pre-split rows can

spread one activity across several rows, and those rows can

genuinely carry different keyword tags from each other, so a

multi-row activity counts once per matching row rather than once

overall, and no distinct-ID count is offered here). "Combined"'s

mask is the union of every requested marker's mask, so the

individual marker rows sum to at least "Combined"'s total, never

less -- a row tagged with more than one requested marker is

counted once per marker row but only once in "Combined", which

is the double count the union row exists to avoid.

df is missing keywords_raw (naming any already present kw_* columns as the likely cause) or value; value is not numeric; a markers= name isn't recognised; or (when include_aggregates=False) df has no is_aggregate column.

A get_tossd()-shaped frame carrying year, tossd_pillar, tossd_subpillar, and value.

The amount column to sum.

False (the default) drops is_aggregate rows before splitting.

One row per (year, subpillar) pair -- every year present gets

all three bucket rows, even a bucket with nothing in it that year

year, subpillar, value,

share_pct (that row's share of its year's Pillar II total,

0-100 scale, unrounded), and coverage_pct (that year's combined

"II.A" + "II.B" share of the same total -- the same number

repeated on all three of that year's rows, since it describes the

year, not the bucket).

Sub-pillar tags only exist from 2023 (a 2022 trace appearance

aside, per get_structural_breaks); a year with "II.A"/"II.B"

both reading 0 and a near-zero coverage_pct means the year

predates tagging, not that Pillar II went unfunded. Read "II.A"/

"II.B" as real amounts only where coverage_pct is non-trivial.

df is missing year, tossd_pillar, tossd_subpillar, or value; value is not numeric; or (when include_aggregates=False) df has no is_aggregate column.

A frame carrying df.attrs["tossd_reader"].

A deep copy of the payload: {"package_version", "created_at", "query", "years"} for a

get_tossd()/get_tossd_raw() result ("query" holds the normalised call; "years"

maps each fetched year to {"etag", "retrieved_at", "url"}), or

{"package_version", "created_at", "years"} for a load_export() frame (no "query"

key -- an export is an unfiltered snapshot, not a query result; see that function's own

docstring for its "years" shape).

df.attrs carries no "tossd_reader" key -- naming the three functions that set it.

A get_tossd()-shaped frame carrying unit, is_aggregate, year, tossd_pillar, and usd_disbursement -- the one required column set, kept minimal. usd_disbursement_deflated, modality_code, source_name, and recipient_code are each optional: when one is missing, the entries that need it read pd.NA instead of raising.

A pandas.Series (object-dtype, one entry per check):

• unit: df's own unit value (a tuple of every distinct value present, when there's more than one).

• n_aggregate_rows, aggregate_value, aggregate_share_pct: the is_aggregate rows' own count and usd_disbursement share of df's total.

• usd_disbursement_total, usd_disbursement_deflated_total (pd.NA if usd_disbursement_deflated isn't in df): the two price bases' own totals, to match against whichever basis an external figure used.

• pillars_present: the sorted, distinct tossd_pillar values in df.

• year_min, year_max, n_years: df's own year coverage.

• has_provenance: whether df.attrs["tossd_reader"] is set (get_provenance(df) reads it).

• b02_core_contribution_value, b02_core_contribution_share_pct (pd.NA if modality_code isn't in df): usd_disbursement on modality_code == "B02" rows (core contributions to multilateral institutions).

• estimate_derived_value, estimate_derived_share_pct (pd.NA if source_name isn't in df): usd_disbursement on rows whose source_name contains "estimate" (case-insensitive) -- a heuristic naming convention, not a packaged flag.

• iso3_unmatched_value, iso3_unmatched_share_pct (pd.NA if recipient_code isn't in df): usd_disbursement on rows whose recipient_code has no add_iso3 match (regional/multi-country codes, TOSSD-only entities).

df is missing unit, is_aggregate, year, tossd_pillar, or usd_disbursement; or usd_disbursement isn't numeric.