In SCIFoundation/sciCoverageR: Set of SCIF coverage survey functions

htmltools::img(src = knitr::image_uri("images/SCI_Foundation_RGB_Navy_Long_red.jpg"),  
               alt = 'logo', 
               style = 'position: absolute; top: 0; right: 0; margin-right: 75px; padding:1px; border:1px; width: 322px; height: 65px')

This vignette details how to obtain and amend the Equity Tool data and perform the calculation to obtain the equity score and equity quintile for each household, based on the questions posed during a coverage evaluation survey.

Obtaining data

The questions and answers to establish the equity scores vary from country to country as well as over time. The country specific details need to be downloaded from the Equity Tool website. This requires navigating to the country site and requesting the country file by filling out the form for Other platforms. Figure 1 shows the website with the form for Democratic Republic of the Congo (DRC).

knitr::include_graphics("images/et_website_drc.png")

Once filled out, you should quickly receive an email to the address provided with the Equity Tool information contained in an attached Excel file. This file contains four sheets. Relevant to our purposes is the last sheet named “Other software”. This sheet contains the questions to be posed to the household respondent, the possible answers as well as the associated scores. Figure 2 shows the Other software sheet for DRC.

knitr::include_graphics("images/Original_equity_tool_output_2.png")

Note that, at the cleaning and analysing stage, this document will already have been downloaded and the questions and answers coded into the survey forms used by the enumerators to collect the responses.

Scrolling down a bit further on the Other software sheet, you will find a vector of four values used to categorise equity scores into quintiles. Figure 3 shows this vector (next to the red arrow), referred to henceforth as the vector of quintiles for the case of Côte d’Ivoire.

knitr::include_graphics("images/Original_equity_tool_vector_of_quintiles.png")

For some countries, the equity tool will differentiate between national scores, urban scores, and rural scores. Which option to use (national, urban, or rural) will depend on the country and survey. The example followed here is based on the national scores and the national vector of quintiles.

Amending data

The data, as it is on the Other software sheet from Equity Tool, cannot be used directly as the questions are full sentences and do not have a variable name assigned. In addition, the language of the questions and answers may vary from one country to another.

You need to simplify these codes into a table of seven column and as many rows as there are questions (11 in the case of Côte d’Ivoire). The first column contains the names of the variable associated to each question, as defined in the survey forms. The second column contains the possible answer to the questions, while the third column holds the associated scores. The fourth and fifth columns have the same information for the second possible answer; the sixth and seventh columns contain the answers and scores for the third possible answer – whenever a third option was present.

Figure 4 shows the stripped-down question, answer, and score structure for Côte d’Ivoire, based on the information shown in Figure 2.

knitr::include_graphics("images/adapted_equity_tool_simple_drc.png")

Note that the order of the column (question, answer, score) needs to be followed for the calculation to work. The name of the columns (here: question, op1, op1_s, …) is irrelevant (i.e., names could be: super, duper, varnames, …)

Calculating the equity output

To calculate the equity scores and compute the equity quintiles we need three elements: the data containing the answers from the household respondents on the Equity Tool questions, the data containing the answer codes and associated scores and the vector of quintiles.

The previous step showed how to amend the Equity Tool information and save it. Once the stripped-down version of the Excel file has been stored, it needs to be read in.

# equity_answers <- readxl::read_xlsx( [::Pathfile::] )

This package contains an example of the file shown in Figure 4. If we call on it we can see the data frame contains the same information.

data(drc_equity_tool_codes, package = "sciCoverageR")
head(drc_equity_tool_codes)

This package further contains an example data frame for the household answers to the equity questions from a coverage survey using the WHO Coverage Evaluation Survey methodology. We can see, it contains 3282 rows and 10 columns.

data(example_equity, package = "sciCoverageR")
dim(example_equity)
names(example_equity)

Let us, for reasons that will become apparent soon, save example_equity_2, which by mistake also contains an imaginary column, where all households have respondend with "yes" to owning an ice cream machine (variable ice_cream). Finally, let us store the vector of quintiles (voq) from the Equity Tools document shown in Figure 3.

example_equity_2 <- example_equity
example_equity_2$ice_cream <- "yes"
voq <- c(-0.379487647, -0.286513899, -0.060301474, 0.653964958)

Now that we have all three elements, we can use the equity_calculation function. Figure 5 shows the function documentation. The function has the three arguments discussed. The first, data should be the data frame containing the household responses, thus example_equity in this example. The second input is the vector of quintiles, voq in this example. Finally, the equity_file argument is the information of the possible answers and their scores from Equity Tool, drc_equity_tool_codes in this example.

knitr::include_graphics("images/equity_help.jpg")

Before evaluating the response, let us go through some possible errors. If we call the function but use the wrong household response data frame (example_equity_2), the function will not work and alert us that the column names do not agree.

library(sciCoverageR)
result <- equity_calculation(data = example_equity_2, vectorOfQuintiles = voq, equity_file = drc_equity_tool_codes)

The function tells us that the error is that the column names of both data frames do not match since eq_2 has one column more.

The columns need to agree not only in number (example_equity_2 had one column more than example_equity) but also in the exact wording. For example, the names of the questions are the following:

names(example_equity)

If we change television to televisions the function would not work either. The same error message appears.

example_equity_wrong_names <- example_equity
names(example_equity_wrong_names)[names(example_equity_wrong_names) == "television"] <- "televisions"
result <- equity_calculation(data = example_equity_wrong_names, vectorOfQuintiles = voq, equity_file = drc_equity_tool_codes)

Another possible error is if the answer codes do not match. As an example, let us see what happens if the answer codes for the television questions was in French in the household respondents data frame, yet in English in the answer codes in the Equity Tool answers and scores data frame.

example_equity_french <- example_equity
example_equity_french$television <- ifelse(example_equity_french$television == "yes", "oui", "non")
result <- equity_calculation(data = example_equity_french, vectorOfQuintiles = voq, equity_file = drc_equity_tool_codes)

The function fails but alerts the user to the variable that is failing. Note that if more than one variable contains different answer codes, only the left-most column will be highlighted. Only after correcting that left-most column will the next error be highlighted.

Finally, if there are no errors, the function will create a data frame of as many rows there are respondents and two columns: scores, which contains the equity score and quintiles, which contains the equity quintile. This data frame respects the order from the respondents answers so the columns can just be added to the data frame to obtain the Equity Tool information.

result <- equity_calculation(data = example_equity, vectorOfQuintiles = voq, equity_file = drc_equity_tool_codes)
dim(result)
table(result$quintiles, useNA = "ifany")