Documentation

Python packages / tossd-reader / How-to guides

Compare totals across years

Compare multi-year TOSSD disbursements in constant prices with df.tossd.compare_years(), which holds the provider cohort constant across years by default and reports structural breaks intersecting the analysis window.

Steps

  1. Query data across multiple years.

    import tossd_reader as tossd

df = tossd.get_tossd(years=range(2019, 2025), columns="analysis", units="usd_million")

  2. Calculate year-over-year changes in constant prices.

    result = df.tossd.compare_years()
print(result.to_string(index=False))

     year  usd_disbursement_deflated  n_providers  pct_change
 2019              251882.812493           91         NaN
 2020              309200.621817           91   22.755745
 2021              312727.827661           91    1.140750
 2022              367005.467426           91   17.356191
 2023              374116.328363           91    1.937535
 2024              359866.711668           91   -3.808873

    The value column defaults to usd_disbursement_deflated (constant 2024 prices). The n_providers column remains constant at 91 across all rows, representing the (provider_code, provider_name) cohort present in every year under cohort="consistent". The pct_change column shows the year-over-year percentage change for the deflated total. The initial year contains NaN as there is no prior year for comparison.

  3. Evaluate the effect of cohort filtering. Pass cohort="all" to include every reporting provider in each year regardless of historical presence.

    result_all = df.tossd.compare_years(cohort="all")
print(result_all.round(1).to_string(index=False))

     year  usd_disbursement_deflated  n_providers  pct_change
 2019                   256779.3           97         NaN
 2020                   320616.2          109        24.9
 2021                   328418.1          119         2.4
 2022                   401734.8          129        22.3
 2023                   408381.8          129         1.7
 2024                   398296.4          130        -2.5

    The n_providers count increases from 97 in 2019 to 130 in 2024 under cohort="all", whereas the default cohort="consistent" holds provider count steady at 91. Newly reporting providers add to the apparent growth rate under cohort="all". The cohort="consistent" setting isolates underlying trends in financial volume.

  4. Inspect structural breaks across the time window. The compare_years() method attaches matching entries from get_structural_breaks(years=...) to result.attrs["structural_breaks"], scoped to the queried years.

    breaks = result.attrs["structural_breaks"][["dimension", "break_year", "end_year"]]
print(breaks.to_string(index=False))

     dimension  break_year  end_year
sub_pillar        2022      2022
sub_pillar        2023      2023
  modality        2021      2021
 reporters        2019      2024

    Four structural breaks intersect the 2019 to 2024 window: the 2022 initial appearance of sub-pillars, the 2023 sub-pillar rollout, the 2021 introduction of modality code K02, and expansion of the reporter base across the entire period. A shift aligning with one of these entries reflects a change in reporting practices. See Why TOSSD totals rise for details on each structural break.

Verify it worked

Confirm that the provider cohort remains constant across all rows under default settings.

print(result["n_providers"].nunique())

1

See also

View as markdown