This vignette provides an overview for extracting targets and other
data using tameDP. You’ll learn about the different
parameters to extract different components of the COP Target Setting
Tool.
If you haven’t installed R or tameDP, you should first
refer to the Setup vignette.
Once you have everything installed, you will want to launch R or
RStudio (an IDE for R). To use tameDP you will need to load
it into your working environment. Enter the line below into your console
to initiate the package.
The first thing you will want to do after your load
tameDP is to tell R where your Target Setting Tool (TST) is
located on your computer. In your Windows Explorer (outside of R),
navigate to your Target Setting Tool file, and hold the SHIFT key while
you right click on the file name. Doing this gives you an additional
option to “Copy as path”, which you want to click.
Now you have the path saved to your clipboard. Open your R up and
paste the copied filepath into the Console or a script. Before you hit
enter, you will need to store this path as an object in R using the
assignment operator <-. This let’s us store information
to use at a later point to pass into different functions. We will call
the object, tst_filepath. It is important to note
that Windows filepaths have their slash in the wrong direction. You will
need to replace all backslashes (“/") in your filepath with forward
slashes (”/“). The command to store the file path object will
look like the code below, where you have replaced the file path with the
path to your own file.
There are a few different forms of data we can get out of the Target Setting Tool. The first is extracting all the targets from their relevant tabs. The data here will be at the PSNU level, broken out by the relevant disagregates (e.g. Age/Sex/HIVStatus). In the function below, we have used the filepath we stored above to pass that into the function. This function will take a few seconds or minutes to run depending on the size of your Target Setting Tool.
The data that has been extracted from the Target Setting Tool will
stored in an objected called df_tst. If you browse the data
frame (df) using a function like View(df_tst) or
dplyr::glimpse(df_tst), you’ll see the structure is very
similar to a MER Structured Dataset (MSD). You have the following
columns:
operatingunit, countryname, snu1, psnu, psnuuid, fiscal_year, indicator, standardizeddisaggregate, numeratordenom, ageasentered, sex, modality, statushiv, otherdisaggregate, targets.
The output is a bit more manageable to work with than using it in the
Target Setting Tool.
If you are comfortable working in R, you can use the
df_tst object to munge, analyze, or visualize your data. If
you would prefer to get the data out to work with in Excel, Tableau, or
another program, we can export the data from the data frame it’s stored
in to a csv file using the readr package. We will need to
tell R which object we want to export; for this we can use
df_tst which we got by running
tame_dp(tst_filepath) in the Extracting Targets section. You will want
to change the file path and name in the chunk below.
In the function above, we provided the filepath and the function
returned the the data frame of targets from the Target Setting Tool.
Function in R often have multiple parameters. Take a minute to look at
the help file for tame_dp().
We can see that there are different parameter that will allow us to return different things.
By default, the function is returning a specific type
and is FALSE for the other two parameters. If you look in
the help file, you will see there are three options for
type - “PSNUxIM”, “SUBNAT”, “ALL” (the default) or a
specific tab. The option for using “ALL” is giving us all the targets
from the tabs. But you will see that you could change this option to
“SUBNAT”. If you do, it will return NAT_SUBNAT data including PLHIV from
the Cascade tab of the Target Setting Tool. The function will be the
same structure as above, but we are adding the type
parameter and specifying “SUBNAT” in order to return the PLHIV and
NAT_SUBNAT data instead of targets. You can also utilize
tame_subnat(), which is just a wrapper function around
tame_dp()
#return IMPATT/SUBNAT data
df_subnat <- tame_dp(tst_filepath, type = "SUBNAT")
#which is equivalent to tame_subnat
df_subnat2 <- tame_subnat(tst_filepath)
#return data from a specific tab - TB
df_tb <- tame_dp(tst_filepath, type = "TB")The structure of the data frame is the same as when we ran it for
targets, but the difference is in the indicators returned
(indicator).
Last but not least we have the option to return
type = "PSNUxIM", which will pull data from the PSNUxIM tab
of the Target Setting Tool (or OPU). This tab no longer exists within
the main TST, but is generated within Target Setting Tool Validation
App and is its own separte tool. You will need to change the
type parameter to type = "PSNUxIM" to pull the
PSNU by mechanism information from this tab. If you keep the defaul
setting (type = ALL), the code will still run, but will
kick back a warning message.
This last type option returns the mech_code
in the Target Setting Tool with the targets assigned to it. The Target
Setting Tool doesn’t include the mechanism name or prime partner so
these columns are left blank. To include this info, you can set
map_names = TRUE in your function. When you run the
function, there will be a pop-up window asking you to type your DATIM
user name and password to pull this information down from DATIM.
Previously, this had been public information, but after a DHIS2 update,
the data became password protected.
The final parameter in the function is psnu_lvl which
gives the user the option to aggregate the data up to the PSNU level (if
working with PSNUxIM). Since tame_dp can pull from the
target tabs which are at the PSNU level, this isn’t as useful now, but
it can be useful if you are only working with the PSNUxIM tab, such as
with an OPU.
You can use one of the map() functions from
purrr package to read in multiple Target Setting Tools and
combine rather than working with one off. This may be more relevant if
you’re reviewing a regional operating unit or in Washington. You will
get a pop up each time to provide your DATIM credentials if you don’t
have stored in the session. We recommend using
getPass::getPass() when storing your credentials so you
don’t type into your script or into your console (and visual under
history).
#load package
library(purrr)
library(getPass)
#identify all the Target Setting Tool files
files <- list.files("../Downloads/TSTs", full.names = TRUE)
#read in all DPs and combine into one data frame
df_combo <- map_dfr(.x = files,
.f = ~ tame_dp(.x))
#store DATIM credentials
dtm_usr <- "spower" #replace with your credentials
dtm_pwd <- getPass() #pop up prompting for your password
#apply mech_name and primepartner names from DATIM
df_combo <- get_names(df_combo, datim_user = dtm_usr, datim_password = dtm_pwd)