Worked examples for phe_sii function

Introduction

This vignette provides examples of how to use the phe_sii function with different kinds of indicators.

The following packages must be installed and loaded if not already available

# source functions required
library(PHEindicatormethods)
library(dplyr)

Function and inputs

phe_sii is an aggregate function, returning the slope index of inequality (SII) statistic for each grouping set in the inputted dataframe, with lower and upper confidence limits based on the specified confidence. The user can choose whether to return the Relative Index of Inequality (RII) via an optional argument in the function.

Each grouping set in the input data should have a row for each quantile, labelled with the quantile number, which contains the associated population, indicator value and 95% confidence limits. The user has the option to provide the standard error instead of the 95% confidence limits, in which case this is used directly rather than being calculated by the function.

The user can also specify the indicator type from “0 - default”, “1 - rate” or “2 - proportion”, where different transformations are applied to the input indicator value and confidence limits in the case of a rate or proportion. Examples are provided below for the three cases.

Example 1 - default (normal) distribution

The example below calculates the SII on some life expectancy data. This is assumed to have symmetric confidence intervals around the indicator values, so default standard error calculations would be done (involving no prior transformations).

The relevant fields in the input dataset are specified for the arguments quantile, population and value. value_type is kept equal to 0 (default), and the number of repetitions set to 100 for faster running of the function as a demonstration.

The standard error (se) has been provided here in the input dataset, meaning this will be used directly and lower/upper 95% confidence limits of the indicator values are not needed.

# Pass data through SII function ---------------------------------------
LE_data_SII <- LE_data %>%
# Group the input dataframe to create subgroups to calculate the SII for
group_by(Sex, GeoCode) %>%
# Run SII function on grouped dataset
phe_sii(quantile = Decile,
population = Pop ,
value = LifeExp,
value_type = 0, # specify default indicator type
se = SE,
repetitions = 100,
type = "full") # use smaller no. of repetitions e.g. for testing
## Warning in phe_sii(., quantile = Decile, population = Pop, value =
## LifeExp, : some records have been removed due to incomplete or invalid data
# View first 10 rows of results
knitr::kable(head(LE_data_SII, 10))  
Sex GeoCode SII SII_lowerCL SII_upperCL indicator_type multiplier CI_confidence CI_method
1 E06000001 11.68886 9.643975 13.59137 normal 1 0.95 simulation 100 reps
1 E06000002 12.54785 10.125113 14.83525 normal 1 0.95 simulation 100 reps
1 E06000003 10.05084 7.983078 12.25088 normal 1 0.95 simulation 100 reps
1 E06000004 14.85223 13.154147 16.57802 normal 1 0.95 simulation 100 reps
1 E06000005 11.68095 9.442326 13.80477 normal 1 0.95 simulation 100 reps
1 E06000006 12.27526 10.110775 14.31905 normal 1 0.95 simulation 100 reps
1 E06000007 11.59893 10.252163 13.21483 normal 1 0.95 simulation 100 reps
1 E06000008 10.72510 8.853470 12.53142 normal 1 0.95 simulation 100 reps
1 E06000009 13.59387 11.394201 15.35652 normal 1 0.95 simulation 100 reps
1 E06000010 11.20094 9.667580 12.48005 normal 1 0.95 simulation 100 reps

Note that some areas are missing quantiles in the dataset, and these are subsequently excluded from the function output with a warning given.

Example 2 - rate

The example below calculates both the SII and RII on Directly Standardised Rate (DSR) data. The value_type argument is set to 1 to specify this indicator is a rate; this means a log transformation will be applied to the value, lower_cl and upper_cl fields before calculating the standard error.

As the number of repetitions is not specified, the function will run on the default 100,000. To return the RII, the rii argument is set to TRUE.

Finally, setting reliability_stat = TRUE will run additional sample sets of the SII/RII confidence limits and return a Mean Average Difference (MAD) value for each subgroup. See below for guidance on how to use this.

# Pass data through SII function ---------------------------------------
DSR_data_SII <- DSR_data %>%
# Group the input dataframe to create subgroups to calculate the SII for
group_by(Period) %>%
# Run SII function on grouped dataset
phe_sii(quantile = Quintile,
population = total_pop ,
value = value,
value_type = 1, # specifies indicator is a rate
lower_cl = lowercl,
upper_cl = uppercl,
rii = TRUE, # returns RII as well as SII (default is FALSE)
reliability_stat = TRUE) # returns reliability stats (default is FALSE)
## For guidance on how to interpret the Mean Average Difference (MAD) figures, see the phe_sii accompanying vignette
# View results
knitr::kable(DSR_data_SII)  
Period SII SII_lowerCL SII_upperCL SII_MAD RII RII_lowerCL RII_upperCL RII_MAD indicator_type multiplier CI_confidence CI_method
2010 -14.848683 -18.97062 -10.727059 0.02254 0.8956758 0.8688048 0.9234444 0.0001493 rate 1 0.95 simulation 1e+05 reps
2011 -13.528326 -17.63573 -9.502213 0.03464 0.9039924 0.8767989 0.9314941 0.0002364 rate 1 0.95 simulation 1e+05 reps
2012 -11.680045 -15.70463 -7.640824 0.01643 0.9159389 0.8887357 0.9441142 0.0001026 rate 1 0.95 simulation 1e+05 reps
2013 -10.544273 -14.55623 -6.548138 0.01918 0.9232984 0.8957498 0.9516066 0.0001393 rate 1 0.95 simulation 1e+05 reps
2014 -10.591214 -14.53562 -6.653285 0.02160 0.9226440 0.8954533 0.9506494 0.0001403 rate 1 0.95 simulation 1e+05 reps
2015 -9.042367 -12.94810 -5.144393 0.01477 0.9332670 0.9059155 0.9614295 0.0001044 rate 1 0.95 simulation 1e+05 reps

Example 3 - proportion

This example calculates the SII for a prevalence indicator. Proportions need to be between 0 and 1 - this formatting is done in the mutate command below, before passing the grouped dataset to the phe_sii function.

The value_type argument is set to 2 to specify the indicator is a proportion, and a logit transformation is applied to the value, lower_cl and upper_cl fields.

The function will again run on the default 100,000 reps, and neither the RII or MAD values will be returned.

There is the option to specify a numeric multiplier in the arguments, which will scale the SII, SII_lowerCL, SII_upperCL (and SII_MAD) before outputting. This could be used if an absolute (i.e. positive) slope is desired for an indicator, where the “high is bad” polarity would otherwise give negative SII results.

Below, a multiplier of -100 is used, to output absolute prevalence figures that are expressed on a scale between 0 and 100.

# Pass data through SII function ---------------------------------------
prevalence_SII <- prevalence_data %>%
# Group the input dataframe to create subgroups to calculate the SII for
group_by(Period, SchoolYear, AreaCode) %>%
# Format prevalences to be between 0 and 1
mutate(Rate = Rate/100,
LCL = LCL/100,
UCL = UCL/100) %>%
# Run SII function on grouped dataset
phe_sii(quantile = Decile,
population = Measured,
value = Rate,
value_type = 2, # specifies indicator is a proportion
lower_cl = LCL,
upper_cl = UCL,
multiplier = -100) # negative multiplier to scale SII outputs

# View first 10 rows of results
knitr::kable(head(prevalence_SII,10)) 
Period SchoolYear AreaCode SII SII_lowerCL SII_upperCL indicator_type multiplier CI_confidence CI_method
607 6 E92000001 10.720032 10.221777 11.221837 proportion -100 0.95 simulation 1e+05 reps
607 R E92000001 5.818547 5.417105 6.218426 proportion -100 0.95 simulation 1e+05 reps
708 6 E92000001 11.025821 10.648074 11.404128 proportion -100 0.95 simulation 1e+05 reps
708 R E92000001 6.048249 5.757379 6.338892 proportion -100 0.95 simulation 1e+05 reps
809 6 E92000001 11.528301 11.162230 11.892766 proportion -100 0.95 simulation 1e+05 reps
809 R E92000001 6.734782 6.459549 7.008675 proportion -100 0.95 simulation 1e+05 reps
910 6 E92000001 12.186004 11.819482 12.552518 proportion -100 0.95 simulation 1e+05 reps
910 R E92000001 6.959414 6.686945 7.233204 proportion -100 0.95 simulation 1e+05 reps
1011 6 E92000001 12.781047 12.411014 13.148995 proportion -100 0.95 simulation 1e+05 reps
1011 R E92000001 6.953482 6.691292 7.216921 proportion -100 0.95 simulation 1e+05 reps

Interpreting the Mean Average Difference (MAD)

If reliability_stat is set to TRUE in the function, a MAD value is returned for each subgroup as a measure of how much the SII (or RII) confidence limits vary.

Note: this option will increase the runtime of the function, as the MAD calculation involves an additional 9 sample sets of the confidence limits to be taken.

A MAD of 0.005 implies that, on rerunning the phe_sii function, the confidence limits can be expected to change by approximately 0.005. The more repetitions the function is run on, the smaller this statistic should be. The tolerance will depend on the level of accuracy to which the user wishes to present the confidence limits - ideally, to display them to 1 d.p., the MAD should be smaller than 0.01. To 2 d.p., smaller than 0.001, etc.