1 Overview

To use a tool, you need to:

  1. Make sure you have the required skills. If you don’t but would like to learn, do not hesitate to request the necessary training from your CFP/HQ.
  2. Pick the tool you need from the list of available tools
  3. Install the package
  4. Load it
  5. Read the essential documentation / Vignettes provided by the developer.

If you still get stuck, there are multiple ways to get help

2 Required Skills

All IMPACT R tools are built to be usable by anyone who completed the certified ‘user’ training. Generally you should have R and RStudio installed, be familiar with the RStudio interface, understand variables, basic data types, subsetting, installing/loading packages as well as reading/writing data to/from files.

3 Available Tools

name                                                                description authors status repository maintainer
hypegrammaR An implementation of the quantitative analysis guidelines Martin Barner, Eliora Henzler under development mabafaba/hypegrammaR martin.barner@impact-initiatives.org
koboquest Using the kobo tool to identify data types, evaluate skiplogic and apply labels Martin Barner, Eliora Henzler validated mabafaba/hypegrammaR martin.barner@impact-initiatives.org
mergekobodata Merging data from different variations of a tool Martin Barner, Eliora Henzler validated mabafaba/mergekobodata martin.barner@impact-initiatives.org
surveyweights calculate survey weights from sampling frames; combine stratum and cluster weights Martin Barner, Eliora Henzler beta mabafaba/surveyweights martin.barner@impact-initiatives.org

4 Getting Started with an IMPACT R Package

4.1 Installation

any of the above tools can be installed by running the following command inside the R console:

devtools::install_github("REPOSITORY_NAME",build_opts = c())

where REPOSITORY_NAME should be replaced by the repository column in the “Available Tools” table above; for example to install the hypegrammaR package:

devtools::install_github("mabafaba/hypegrammaR",build_opts = c())

4.2 Loading

Once the package is installed, load it with

library(PACKAGE_NAME)

example:

library("hypegrammaR")

4.3 accessing the documentation

You can find the main information that you need by running:

browseVignettes("PACKAGE_NAME")

where PACKAGE_NAME should be replaced by the actual name of the package, e.g.:

browseVignettes("hypegrammaR")

5 Getting Help

5.1 Prerequisites

If you don’t know how to follow the instructions in this guide, you probably don’t have the required skills.

If you do, and managed to install the package, you will probably get stuck unless you have read the developer’s documentation of the specific tool.

5.2 Questions on specific functions

Once you’ve checked the two prerequisites above, you might still have questions regarding specific functions. Each function has its own detailed help page, which is usually the first place to go for help. You can access it with:

?PACKAGE_NAME::FUNCTION_NAME

For example:

?hypegrammaR::analyse_indicator

5.3 Dealing with error messages

Generally there are two types of error messages:

  • planned error messages
  • unplanned error messages

Planned error messages were generated on purpose by the tool developer. While they are likely accompanied by a bit of jibberish junk, you should find among it a clear message about what went wrong, why it went wrong and what you need to change. Actually reading the error message and looking for useful hints might give you the solution straight away.

If you can not find anything useful in there, you are probably dealing with an unplanned error message, a problem that the developer of the tool did not anticipate. In that case:

  • If the error was thrown by a function in one of the IMPACT tools, you may want to contact the maintainer (see the list of tools).
  • If the error was thrown by any other function
    1. Google for the error message
    2. Google for the error message together with the name of the package/function
    3. Ask someone in your team for help
    4. Ask someone remote for help; In that case you need to follow the best practices on how to ask questions on code

6 Asking Questions: best practices

When asking a question remotely (i.e.: the person helping you can’t physically sit down on your computer), you should make it as easy as possible for the other person to help you. This applies both when asking within IMPACT or online (e.g. on StackOverflow).

At the very least, you should provide:

  • the code that produced the error
  • the error message
  • what you tried already

Unless the issue is trivial, the person will not be able to help you without running the code themselves and recreating the problem. The best way to help them do that as to produce what is called a minimal, complete, and verifiable example.

7 Contributing to / adding packages

These tools are a collaborative effort across IMPACT teams. Contributing to and adding IMPACT tools is the greatest honour anyone can achieve in life in general. If you would like to learn how to build R packages or have a specific tool in mind that you would like to build, please contact the data unit - They may be able to help you get the free time you need.

For contributions to be effective (and to be acceptable in the official toolbox), contributors need to follow specific processes and standards. Please visit the How to contribute to Impact Packages page and follow the instructions there.