deciles-charts generates a table and a line chart for each measure table in an input directory. The table has date, percentile, and value columns. The line chart has date on the horizontal axis (x) and value on the vertical axis (y). Deciles are plotted as dashed lines; the median is plotted as a solid line. For example, the following deciles chart was generated from dummy data:

Using deciles to communicate variation has several advantages when compared to the alternatives. Consequently, deciles charts are used on OpenPrescribing.net and in several OpenSAFELY publications, such as Curtis et al. (2021).

In summary:

• Use cohort-extractor to extract several weekly or monthly cohorts.
• Use cohort-extractor to generate one or more measure tables from these cohorts.
• Use deciles-charts to generate a deciles chart for each measure table.

Let's walk through an example project.yaml.

The following cohort-extractor action extracts several monthly cohorts:

generate_cohort:
  run: >
    cohortextractor:latest generate_cohort
      --study-definition study_definition
      --index-date-range "2021-01-01 to 2021-06-30 by month"
  outputs:
    highly_sensitive:
      cohort: output/input_2021-*.csv

The following cohort-extractor action generates one or more measure tables from these cohorts:

generate_measures:
  run: >
    cohortextractor:latest generate_measures
      --study-definition study_definition
  needs: [generate_cohort]
  outputs:
    moderately_sensitive:
      measure: output/measure_*.csv

Finally, the following deciles-charts reusable action generates a deciles table and a deciles chart for each measure table. Remember to replace [version] with a deciles-charts version:

generate_deciles_charts:
  run: >
    deciles-charts:[version]
      --input-files output/measure_*.csv
      --output-dir output
  needs: [generate_measures]
  outputs:
    moderately_sensitive:
      deciles_charts: output/deciles_*_*.*

For each measure table, there will now be a deciles table and deciles chart. For example, given a measure table called measure_has_sbp_event_by_stp_code.csv, there will now be a deciles table called deciles_table_has_sbp_event_by_stp_code.csv and a deciles chart called deciles_chart_has_sbp_event_by_stp_code.png.

Pass configuration via the config property. For example:

generate_deciles_charts:
  run: >
    deciles-charts:[version]
      --input-files output/measure_*.csv
      --output-dir output
  config:
    show_outer_percentiles: false
    tables:
      output: true
    charts:
      output: true
  needs: [generate_measures]
  outputs:
    moderately_sensitive:
      deciles_charts: output/deciles_*_*.*

Measure table
Generated by cohort-extractor's generate_measures function; contains data for one measure for all index dates in a range (a partial measure table contains data for one measure for one index date in a range)

Deciles table
Derived from a measures table

Deciles chart
Derived from a deciles table

Please see DEVELOPERS.md.