class: center, middle, inverse, title-slide .title[ # Survey Data Analysis with {Kobocruncher} ] .subtitle[ ## Session 1 - Your first report ] .author[ ### <a href="https://edouard-legoupil.github.io/kobocruncher/">Link to Documentation</a> – <a href="00-Intro.html">Link to Previous Session</a> – <a href="02-Relabeling.html">Link to Next Session</a> ] .date[ ### Training Content as of 02 November 2023 ] --- ## Setting up the environment 2 options: - Start with Rstudio Cloud for training and testing - Then install your own Rstudio on your computer for production stage .bg-blue[ Recall that all slides and code for this training are available on GitHub: https://edouard-legoupil.github.io/kobocruncher/tutorial/00-Intro.html ] --- ## Option 1: RStudio Cloud .pull-left[ Good option if you are a __first time user__ and in order to get a first introduction! - Sign-up for a free RStudio Cloud account (https://rstudio.cloud/) - Click "START" to open the project and get started - RStudio Cloud has the same features and appearance as RStudio for ease of use ] .pull-right[  ] ??? Github repo is for future reference, all material on RStudio cloud --- ## Option 2: Use your own RStudio environment .bg-blue[ For data Protection reason, this needs to be done as soon as you are working with production data ] .pull-left[ Install Software 1. [Install R](https://cran.r-project.org/): follow instruction from the installer. 2. __Only for windows user__ [Install RTools](https://cran.r-project.org/bin/windows/Rtools): This executable is needed to install the package from github. Follow instruction from the installer. 3. [Install R Studio](https://www.rstudio.com/products/rstudio/download/#download) : follow instruction from the installer You can now Launch __R Studio__ and open a new project. You may check the list of common issues in the [Common Troubleshooting](articles/Troubleshooting.html) article. ] .pull-right[ Create project * In R Studio, select File, click New project. A box opens * Choose New Directory * Choose Empty project * Type the name of the folder where you want to put your data * Select where you want to put this folder * Click Create project ] --- ## Exploring Rstudio Interface  --- ## Package installation from Github .left-column[  ] .right-column[ Create an R script and paste the following command: ```r # Run package installation if you don't have these packages already # As a reminder, installing takes package from internet to your computer # and only needs to be done once, not each session install.packages("devtools") ### Install Key unhcRverse packages in order to get the corporate style & brand devtools::install_github('vidonne/unhcrdown') devtools::install_github('vidonne/unhcrthemes') devtools::install_github('galalH/riddle') ## Now get kobocruncher devtools::install_github("edouard-legoupil/kobocruncher") ``` you can then click on the Run button to `execute` the command one by one ] ??? GitHub has a rate limit of 60 requests per hour for unauthenticated requests, but 5000 an hour for authenticated requests. So the easiest solution is to create a GitHub PAT, with `usethis::browse_github_pat()` and add it to your `.Renviron` file with `usethis::edit_r_environ()`. one for the training in case... GITHUB_PAT="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" --- ## Screenshot from Rstudio cloud <img src="data:image/png;base64,#../../inst/rstudio1.png" width="70%" /> --- ## Check the package is installed after you run the package installation command .pull-left[ See the package tab in the right-down panel You can search for the package name `kobocruncher` You can click on the blue link to access the documentation ] .pull-right[  ] --- ## R Markdown: how to combines __R code with text__ ? .pull-left[ Rmarkdown files have an `.Rmd` extension. 1. Embed your data processing code within `snippet` 2. Knit to different __output format__: PDF, DOCX, HTML, PPTX, and more 3. Don't copy/paste output to your manuscript/report. __Make your manuscript/report with R Markdown__ 4. __Automatic styling__ table, figure numbering, colors, font, etc.. 5. Can create __parameterized reports__. Example: run an analysis for each state and each state gets a report For beginners: https://rmarkdown.rstudio.com/lesson-1.html. Actually this presentation is built from an [Rmd file](https://github.com/Edouard-Legoupil/kobocruncher/blob/main/docs/tutorial/01-First_Report.Rmd) ] .pull-right[  ] ??? Each time document is Knitted, a self-contained session is started. Prevents problems with depending on something in your environment that aren't explicitly called out https://www.rforecology.com/post/how-to-use-rmarkdown-part-one/ --- ## Now Let's create our first report!!! .pull-left[ To start with, let's use the first template "KoboCruncher A - Exploration" To do so, from the top menu on the left: > file > New file > R markdown > From Template In the process you may be requested to install missing packages, do so as required ] .pull-right[  ] --- ## Save you notebook file and check the report __parameters__ .pull-left[ In an RMD report, the top part of the file, the header is called [YAML](). A YAML header contains YAML arguments, such as “title”, “author”, and “output”, demarcated by three dashes (—) on either end.  ] .pull-right[ The YAML header for this template contains also a few parameters. They have values by default that can be adjusted * `datafolder`: "data-raw" ## This is the default folder where to put you data in * `data`: "data.xlsx" ## Name of the data file * `form`: "form.xlsx" ## name of the xlsform - * `language`: "" ## Check what you have in your xlsform - ::english (en) -or ::french (fr) or ::spanish (es) .bg-blue[ We will review the other parameters in the following sessions ] ] ??? * `datasource`: "Study name reference" ## String used in caption for all your charts * `ridl`: "ridlproject" ## Name of the ridl project where you data is documented and archived * `publish`: "no" ## put to "yes" in order to add your report, source and analysis plan as ressource within the same ridl c * `republish`: "no" * `visibility`: "public" * `stage`: "exploration_initial" ## you may change this to exploration_advanced if you configuring many --- ## Editing a notebook is simple!  --- ## Let's review the chunk to run the demo! .pull-left[  ] .pull-right[ Each line with a `#` will not be executed Remove the `#` at the beginning of line 69 & 70 so that the report use the demo dataset Then click on the `knit` button ] --- ## Et Voila! You just built your first report!! <img src="data:image/png;base64,#../../inst/firstreport.png" width="70%" /> --- ## What happenned? The xlsform was first expanded with the [kobo_prepare_form](https://edouard-legoupil.github.io/kobocruncher/reference/kobo_prepare_form.html). The file then got converted in a broad data dictionary with [kobo_dico](https://edouard-legoupil.github.io/kobocruncher/reference/kobo_dico.html) and data got loaded in the session with [kobo_data](https://edouard-legoupil.github.io/kobocruncher/reference/kobo_data.html). The function [kobo_cruncher](https://edouard-legoupil.github.io/kobocruncher/reference/kobo_cruncher.html) then loop around all the questions and based on the data types, generate standard charts: * `select_one` simple bar chart with [plot_select_one](https://edouard-legoupil.github.io/kobocruncher/reference/plot_select_one.html) * `select_multiple` bar chart [plot_select_multiple](https://edouard-legoupil.github.io/kobocruncher/reference/plot_select_multiple.html) * `integer` or `numeric` or `date` histogram with [plot_integer](https://edouard-legoupil.github.io/kobocruncher/reference/plot_integer.html) * `text` word cloud with [plot_text](https://edouard-legoupil.github.io/kobocruncher/reference/plot_text.html) * In addition, the [kobo_likert](https://edouard-legoupil.github.io/kobocruncher/reference/kobo_likert.html) serach for questions that have common responses in order to output [likert chart](https://edouard-legoupil.github.io/kobocruncher/reference/plot_likert.html) Later we will see how to configure charts based on `crosstabulation` --- class: inverse, center, middle # TIME TO PRACTISE ON YOUR OWN! ### .large[.white[<svg aria-hidden="true" role="img" viewBox="0 0 512 512" style="height:1em;width:1em;vertical-align:-0.125em;margin-left:auto;margin-right:auto;font-size:inherit;fill:currentColor;overflow:visible;position:relative;"><path d="M368.4 18.3L312.7 74.1 437.9 199.3l55.7-55.7c21.9-21.9 21.9-57.3 0-79.2L447.6 18.3c-21.9-21.9-57.3-21.9-79.2 0zM288 94.6l-9.2 2.8L134.7 140.6c-19.9 6-35.7 21.2-42.3 41L3.8 445.8c-3.8 11.3-1 23.9 7.3 32.4L164.7 324.7c-3-6.3-4.7-13.3-4.7-20.7c0-26.5 21.5-48 48-48s48 21.5 48 48s-21.5 48-48 48c-7.4 0-14.4-1.7-20.7-4.7L33.7 500.9c8.6 8.3 21.1 11.2 32.4 7.3l264.3-88.6c19.7-6.6 35-22.4 41-42.3l43.2-144.1 2.8-9.2L288 94.6z"/></svg>] **10 minutes! **] <div class="countdown" id="timer_33c30588" data-update-every="1" data-play-sound="true" tabindex="0" style="right:0;bottom:0;margin:5%;font-size:8em;position: relative; width: min-content;"> <div class="countdown-controls"><button class="countdown-bump-down">−</button><button class="countdown-bump-up">+</button></div> <code class="countdown-time"><span class="countdown-digits minutes">10</span><span class="countdown-digits colon">:</span><span class="countdown-digits seconds">00</span></code> </div> Get your environment ready, Open a notebook & Compile it with demo dataset Do not hesitate to raise your questions in the [ticket system](https://github.com/Edouard-Legoupil/kobocruncher/issues/new) or in the chat so the training content can be improved accordingly! --- class: inverse, center, middle ### .large[.white[<svg aria-hidden="true" role="img" viewBox="0 0 512 512" style="height:1em;width:1em;vertical-align:-0.125em;margin-left:auto;margin-right:auto;font-size:inherit;fill:currentColor;overflow:visible;position:relative;"><path d="M256 0a256 256 0 1 1 0 512A256 256 0 1 1 256 0zM232 120V256c0 8 4 15.5 10.7 20l96 64c11 7.4 25.9 4.4 33.3-6.7s4.4-25.9-6.7-33.3L280 243.2V120c0-13.3-10.7-24-24-24s-24 10.7-24 24z"/></svg>] **Let's take a break! **] <div class="countdown" id="timer_995af287" data-update-every="1" data-play-sound="true" tabindex="0" style="right:0;bottom:0;margin:5%;font-size:8em;position: relative; width: min-content;"> <div class="countdown-controls"><button class="countdown-bump-down">−</button><button class="countdown-bump-up">+</button></div> <code class="countdown-time"><span class="countdown-digits minutes">10</span><span class="countdown-digits colon">:</span><span class="countdown-digits seconds">00</span></code> </div> __Next session__: [02-Relabeling the way your survey variables are labelled for data collection is not always optimal when the goal is display the resulting information, hence you need to relabel (mostly shorten and simplify) the survey content](02-Relabeling.html)