-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathtutorial.qmd
171 lines (94 loc) · 10.4 KB
/
tutorial.qmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
---
title: "Show case of outbreak-tools usage"
---
Authors: Anton Camacho, Yves Amevoin, Marine Durthaler
<div align="center">
<p align="center">
Excercises and show-case of [outbreak-tools](https://github.com/epicentre-msf/outbreak-tools/) and [outbreak-tools-setup](https://github.com/epicentre-msf/outbreak-tools-setup/).
[](https://github.com/epicentre-msf/outbreak-tools-demo/raw/main/demo_materials.zip)
[](https://github.com/epicentre-msf/outbreak-tools-setup/raw/main/setup.xlsb)
[](https://github.com/epicentre-msf/outbreak-tools/raw/dev/misc/_ribbontemplate.xlsb)
[](https://github.com/epicentre-msf/outbreak-tools/raw/dev/src/bin/designer_dev.xlsb)
</p>
</div>
::: {.callout-note}
If you just want to focus on linelist usage, you can download materials for a short tutorial [here](https://github.com/epicentre-msf/outbreak-tools-demo/raw/main/demo_materials_usage.zip)
:::
## Introduction
Outbreak-tools is a set of tools to facilitate the creation and maintainance of Excel linelists. In particular, you can easily:
- define different types of variables (dropdown lists, Excel formulas) their format and data validation rules
- print a register book that perfectly match your linelist. Translate your linelist into several languages
- use pre-defined geo databases for patient origin
- display custom analyses (univariate, bivariate, temporal, spatial) as tables and graphs
- export the entire data or selected variables/lines
- migrate the data to an updated version of the linelist
The linelist is defined in a configuration file called *setup*. This *setup* file is then loaded into another file that designs the linelist (the *designer*). The designer creates the linelist, based on the configurations of the *setup*.
There are 3 steps to creating a linelist:
1. Open the setup file and define your needs. The configuration of the file is inspired from Kobo’s XLS forms. No in-depth knowledge of Excel is required. A setup file can be used to create linelists in several languages.
2. Download geographic data for the targeted area: there is a [Geo-App](https://reports.msf.net/secure/app/outbreak-tools-geoapp) available online to download the geobase for the region of interest (new users must [register](https://reports.msf.net/signup/)). The Geo-App is updated as new geographical information becomes available.
3. Open the designer, load the setup and geobase files, set the options (languages etc) and generate your linelist.
## Use-case
In this demo, you’ll familiarise yourself with the various features of the tool and simulate a scenario well known to epidemiologists in the field: upgrading a linelist that already contains data to a new version. This often happens when you want to collect new variables as the epidemic unfold and you need to answer new questions.
The folders contain all the materials needed to perform the exercises.
## Prepare the materials
### Download and unzip the materials
You can download the exercices bundled in a`zip` file for offline use [here](https://github.com/epicentre-msf/outbreak-tools-demo/raw/main/demo_materials.zip).
### Unlock files if necessary
Sometimes Excel files with macro downloaded from the web are automatically "blocked" for security reasons. You can unblock the files with the following steps:
1. Right click on the file
2. Select "Properties"
3. Check the *Unblock* box on the bottom right (if you don't see such a button on the bottom right it means that the file is already unprotected - for this level of protections).
### Activate macros before exercises
If you’re going to run the designer to build a linelist, you’ll need to enable VBA macros in Excel, as well as access to the VBA object model:
1. Open Excel
2. Display the *Developer* tab in Excel.
3. In the *Developer* tab, click on *Macro security*. Check the options as shown in the following image:
{fig-align="center"}
## Exercise 1: Getting started.
- Open the linelist `linelist_measles_en_ex1.xlsb` located in the `linelist` folder. The file password is 5678. It contains a mock measles dataset.
- Take a quick look at the different sheets to get an overview of the structure of the file.
- In the *Linelist patients* sheet, add one or two patients manually. In particular, use the geo-Helper to enter the patients' origin (see *Data table* section of the [OutbreakTools ribbon](reference/ribbons.qmd#sec-linelist-ribbon)).
- Explore univariate, bivariate, temporal and spatial analyses. Use button "Refresh analyses" in the [OutbreakTools ribbon](reference/ribbons.qmd#sec-linelist-ribbon) to update the analyses.
- In the temporal analysis, change the start/end dates as well as the time unit of the analysis.
- In the spatial analysis, change the administrative level and divide by the population size to get attack rates (note we don’t have population estimates below the health-zone level).
- Go back to the *Linelist patients* and use the filters to show only patients under 2 years of age. Then go back to the analyses sheets and recalculate (use button "Refresh analyses").
- Export the filtered data using the `anonymous export for MSF` (see *Export button* in the [OutbreakTools ribbon](reference/ribbons.qmd#sec-linelist-ribbon)). Open and browse the exported file.
- Finally, print a register book for the `Linelist patients` (see the *Register book* section of the [OutbreakTools ribbon](reference/ribbons.qmd#sec-linelist-ribbon)).
## Exercise 2: Adding new variables
Open the setup file `setup_measles_base_ex2.xlsb` in the `setup` folder. This setup file corresponds to the linelist you have been working with. Take a look at the different sheets and see how they relate to the linelist.
Now, we would like to add the following variables:
- In the *Admission* section of *Linelist patients* sheet, just before the *hospitalisation* sub-section: a variable called `muac` (MUAC) that can take three values: “Green (125+mm)”, “Yellow (115-124mm)”, “Red (\< 115mm)”
- In the *Vaccination* section of *Linelist patients* sheet, just after *Vaccination against measles*:
- A variable called `vacci_measles_doses` (Number of doses received) which is a numeric variable.
- Create a data validation rule to ensure that this variable remains between 0 and 4.
- Translate newly added labels into French (see the [Setup Options ribbon](reference/ribbons.qmd#sec-setup-ribbon) and the [Setup Translation sheet](reference/translations_sheet.qmd)).
- Check the setup for potential errors (see the [Setup Options ribbon](reference/ribbons.qmd#sec-setup-ribbon)).
::: {.callout-note}
You should normally have a configuration file identical to `setup_measles_exercise_two.xlsb` in the `setup` folder. You can also start from this file if you like.
:::
- Regenerate a new linelist named `linelist_measles_en_ex2` using the designer located in the `designer` folder. Save the linelist in the demo folder, making sure you have selected English as the language. You will use the file `geobase-cod-2023-03-13_20230612.xlsx` in the `geobase` folder as your geobase.
::: {.callout-warning}
## Warning for Mac users
Sometimes generating the linelist using a ribbon file can fail on Mac. In that case, it will default back to a linelist with buttons instead, but you should be able to pursue the exercices with this linelist. We are working to provide full support for Ribbon on Mac Os.
You might experience screen flickering during the linelist creation process.
:::
- You are now ready to migrate your data from the old to the new linelist. You need to proceed in 2 steps:
- First, go back to the linelist `linelist_measles_en_ex1.xlsb` and remove all filters (see the [linelist options ribbon](reference/ribbons.qmd#sec-linelist-ribbon)). Then, export the data (use the *Export data* button in the same ribbon) to a location of your choice. This migration file contains all your data.
- Second, go back to the new linelist `linelist_measles_en_ex2.xlsb` and import the migration file (see the button "Import data" from the [linelist options ribbon](reference/ribbons.qmd#sec-linelist-ribbon)). Look at the importation report and browse the data in the new linelist.
## Exercise 3: Adding new analyses
We have decided to add some analyses on the type of discharge (variable `outcome`) to the linelist.
- Open the setup file `setup_measles_base_ex3.xlsb` located in the `setup` folder.
- In the *Analyses* sheet, section *Univariate Analysis*, add a univariate table showing the number of patients by type of discharge. Add percentages and a graph for this table.
- In the *Analyses* sheet, section *Time Series Analysis*, add a temporal table showing the number of patient by type of discharge and notification date. Add percentages by row and add total.
- In the *Analyses* sheet, section *Labels for Time Series Graphs*, add a graph title *Deaths*. In the section *Graph on Time Series* graph specifications, add the number of deaths per notification date, in
bars.
- Translate newly added labels into French (see *Setup Options* ribbon).
- Check the setup for potential errors (see *Setup Options* ribbon).
::: {.callout-note}
You should get a configuration file identical to `setup_measles_exercise_three.xlsb` in the `setup` folder. You can also start from this file if you like.
:::
- Regenerate a new linelist named `linelist_measles_en_ex3` using the designer located in the `designer` folder. Save the linelist in the demo folder, making sure you have selected English as the language. You willl use the file `geobase-cod-2023-03-13_20230612.xlsx` in the `geobase` folder as your geobase.
- You are now ready to migrate your data from the old to the new linelist. You need to proceed in 2 steps:
- First, go back to the linelist `linelist_measles_en_ex1.xlsb` and remove all filters. Then, export
the data to a location of your choice. This migration file contains all your data.
- Second, go back to the new linelist `linelist_measles_en_ex3.xlsb` and import the migration file. Look at the importation report and browse the data in the new linelist.