hypegrammaR: Instructions v1

Dataset

Questionnaire

The questionnaire needs to be included in the toolbox so that hypegrammaR can distinguish between multiple and single choice questions, and lookup the corresponding labels of the variables. Simply save the two tabs from your KoBo tool as ‘choices.csv’ and ‘questions.csv’, respectively, and put the files in the ‘input’ folder.

Sampling Frame

Extended Analysis Plan (EAP)

Last but not least, the toolbox requires an extended analysis plan (EAP) in order to work. The EAP is an extended version of the data analysis plan (DAP) and lists all the indicators you wish to analyze, and defines how indicators are disaggregated. Without it, the script does not know what to calculate.

1. Load Package

The first step is to simply call for R to load the hypegrammaR package.

library(hypegrammaR)

2. Load Files

Next you load in all the input files using the following hypegrammaR functions:

assessment_data <- load_data(file = "input/data.csv")
sampling_frame  <- load_samplingframe("input/sampling_frame.csv")
questionnaire   <- load_questionnaire(data = assessment_data,
                                      questions = "input/questions.csv",
                                      choices = "input/choices.csv",
                                      choices.label.column.to.use = "label::English"
                                      )
analysisplan    <- load_analysisplan(file = "input/eap.csv")

3. Define Stratification Variable

You then define a variable that includes the strata names by pasting together the character strings from the variables you stratify by. Make sure the strata names in the sampling frame follow the exact same logic (same spelling, divided by “.” etc.).

In the example below, strata were defined along three variables (location, population group & camp status). Change/add/remove variables as needed.

assessment_data$strata <- paste(assessment_data$dist_location,
                                assessment_data$idp_ref,
                                assessment_data$camp_no_camp,
                                sep = "."
                                )

4. Apply Weights from Stratification

In the next step, you map the weights from the sampling frame to the dataset:

weights <- map_to_weighting(sampling.frame = sampling_frame,
                            data.stratum.column = "strata",
                            sampling.frame.population.column = "population",
                            sampling.frame.stratum.column = "strata.names"
                            )

Unweighted calculations: If your assessment is not stratified/weighted, there is no need to load in a sampling frame in step 2. You would also need to delete steps 3 and 4, and remove the ‘weighting’ line in step 5.

Additional code: You may add additional code to your script before running the analysis (step 5) if you wish to do so (e.g. filter dataset, create additional variables etc.) See Annex below for guidance on how to filter your dataset or add additional variables.

5. Run Analysis

Now, you are all set to run the analysis, like so:

resultlist <- from_analysisplan_map_to_output(data = assessment_data,
                                              analysisplan = analysisplan,
                                              weighting = weights,
                                              #labeled = TRUE,
                                              questionnaire = questionnaire
                                              )

You may include the line labeled = TRUE, if you want your output to display variable labels rather than names.

Depending on the size of your EAP, running the analysis may take up to a couple of minutes. The progress is displayed in the console.

6. Export Results

Once R has gone through all the rows in the EAP and calculated the results, you then only need to export them as a table in a .csv file.

map_to_master_table(resultlist$results, "output/results.csv")

Results

The results file includes 11 columns, and however many rows depending on your EAP and choice list. It follows the structure of the EAP. Each line from the EAP is calculated and then saved in the results table one after the other.

Filter Dataset

Let’s say you want to filter your dataset and only include surveys with a certain attribute (e.g. only IDP households, or only answered phone calls). This can easily be done by calling the filter() function from the mighty dplyr package.

First, install the dplyr package (if you have not already done so) by typing the following:

install.packages("dplyr")

You only have to install the package on your computer once. However, whenever you use it in one of your R sessions you have to ‘activate’ it before using any of its formulas, like so:

library(dplyr)

Let’s say you want to filter your dataset (let’s call it data) by a variable indicating population group (let’s call it pop_group), and only include IDPs (cell value idp):

data <- data %>% filter(pop_group == "idp")

Here is how you read this line of code: Define object data as (<-) data and (%>%) filter it (filter()) by variable pop_group, only keeping surveys that have the value idp.

Other examples of filtering your data:

data <- data %>% filter(pop_group == "idp" | pop_group == "refugee")
data <- data %>% filter(pop_group == "idp" & gov == "al-basrah")

• If you want to include IDPs and refugees (refugee), add an OR operator (|).
• If you want the dataset to only include IDPs from governorate (gov) Al-Basrah (al-basrah), use the AND operator (&).
• Other logical operators you may find useful:
  • != : is not (opposite of ==)
  • >= or < : is larger or equal / is smaller
  • is.na('variable') : variable value is not available
• You may combine logical statements (using parentheses) as needed.

Add New Variables

You want to create additional variables to do analysis with. You may use the mutate() function from the dplyr package to do that.

Let’s assume you want to create an additional indicator, called exp_total, which is the sum of different expenditure categories (exp_food, exp_rent and exp_nfi):

data <- data %>% mutate(exp_total = exp_food + exp_rent + exp_nfi)

You could insert any function after the = sign depending on what you want. Here is an example of how to create the stratification variable as in step 3, but with mutate() from the dplyr package:

data <- data %>%
  mutate(stratification = paste(assessment_data$dist_location,
                                assessment_data$idp_ref,
                                assessment_data$camp_no_camp,
                                sep = "."
                                )
         )

You may even combine the filter() and the mutate() functions with the %>% operator:

data <- data %>%
  mutate(stratification = paste(assessment_data$dist_location,
                                assessment_data$idp_ref,
                                assessment_data$camp_no_camp,
                                sep = "."
                                )
         ) %>%
  filter(pop_group == "idp")

back to top