Worked examples for phe_sii function

Emma Clegg

2019-05-15

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.207123 14.24374 normal 1 0.95 simulation 100 reps
1 E06000002 12.54785 10.316344 14.53931 normal 1 0.95 simulation 100 reps
1 E06000003 10.05084 7.972333 11.85524 normal 1 0.95 simulation 100 reps
1 E06000004 14.85223 13.293198 16.43013 normal 1 0.95 simulation 100 reps
1 E06000005 11.68095 9.043890 14.04501 normal 1 0.95 simulation 100 reps
1 E06000006 12.27526 10.077203 14.54594 normal 1 0.95 simulation 100 reps
1 E06000007 11.59893 10.320958 12.87348 normal 1 0.95 simulation 100 reps
1 E06000008 10.72510 8.901721 13.02836 normal 1 0.95 simulation 100 reps
1 E06000009 13.59387 11.729338 15.81771 normal 1 0.95 simulation 100 reps
1 E06000010 11.20094 9.664963 12.66451 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.94258 -10.777344 0.02315 0.8956758 0.8689668 0.9230885 0.0001452 rate 1 0.95 simulation 1e+05 reps
2011 -13.528326 -17.60190 -9.474470 0.01214 0.9039924 0.8771100 0.9317437 0.0001161 rate 1 0.95 simulation 1e+05 reps
2012 -11.680045 -15.74863 -7.699651 0.04116 0.9159389 0.8884207 0.9437109 0.0003015 rate 1 0.95 simulation 1e+05 reps
2013 -10.544273 -14.50908 -6.557454 0.01748 0.9232984 0.8961185 0.9515347 0.0001377 rate 1 0.95 simulation 1e+05 reps
2014 -10.591214 -14.58720 -6.640672 0.02331 0.9226440 0.8951193 0.9507644 0.0001772 rate 1 0.95 simulation 1e+05 reps
2015 -9.042367 -12.97192 -5.161861 0.02115 0.9332670 0.9057455 0.9612986 0.0001553 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.218095 11.225809 proportion -100 0.95 simulation 1e+05 reps
607 R E92000001 5.818547 5.415934 6.222057 proportion -100 0.95 simulation 1e+05 reps
708 6 E92000001 11.025821 10.650802 11.399967 proportion -100 0.95 simulation 1e+05 reps
708 R E92000001 6.048249 5.753244 6.342114 proportion -100 0.95 simulation 1e+05 reps
809 6 E92000001 11.528301 11.163894 11.892615 proportion -100 0.95 simulation 1e+05 reps
809 R E92000001 6.734782 6.458531 7.008887 proportion -100 0.95 simulation 1e+05 reps
910 6 E92000001 12.186004 11.821299 12.552790 proportion -100 0.95 simulation 1e+05 reps
910 R E92000001 6.959414 6.685076 7.230100 proportion -100 0.95 simulation 1e+05 reps
1011 6 E92000001 12.781047 12.410711 13.150465 proportion -100 0.95 simulation 1e+05 reps
1011 R E92000001 6.953482 6.690714 7.214564 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.