rerender of tutorials

content/en/docs/Tutorials/Using-Modules/Add-Metadata/Trial2.Rmd

@@ -0,0 +1,140 @@
+---
+title: "Describe And Disseminate Youth Mental Health Datasets"
+output: rmarkdown::html_vignette
+# output: 
+#   rmarkdown::html_vignette:
+#     toc: true
+#   pdf_document:
+#     highlight: null
+#     number_sections: yes
+vignette: >
+  %\VignetteIndexEntry{Describe And Disseminate Youth Mental Health Datasets}
+  %\VignetteEncoding{UTF-8}
+  %\VignetteEngine{knitr::rmarkdown}
+---
+
+Note: **This vignette is illustrated with fake data**. The dataset explored in this example should not be used to inform decision-making.
+
+```{r echo = F}
+knitr::opts_chunk$set(echo = TRUE)
+```
+```{r results='hide', message=FALSE, warning=FALSE}
+library(ready4)
+library(youthvars)
+```
+
+Youthvars provides two [ready4 framework modules](https://www.ready4-dev.com/docs/framework/implementation/modularity/#ready4-model-modules) - `YouthvarsProfile` and `YouthvarsSeries` that form part of the [ready4 economic model of youth mental health](https://www.ready4-dev.com/docs/model/). The ready4 modules in `youthvars` extend the [Ready4useDyad module](https://www.ready4-dev.com/docs/framework/use/authoring-data/label-data/) and can be used to help describe key structural properties of youth mental health datasets.
+
+## Ingest data
+To start we ingest  `X`, a `Ready4useDyad` (dataset and data dictionary pair) that we can download from a remote repository.
+
+```{r}
+X <- ready4use::Ready4useRepos(dv_nm_1L_chr = "fakes",
+                               dv_ds_nm_1L_chr = "https://doi.org/10.7910/DVN/W95KED",
+                               dv_server_1L_chr = "dataverse.harvard.edu") %>%
+  ingest(fls_to_ingest_chr = "ymh_clinical_dyad_r4",
+         metadata_1L_lgl = F)
+```
+
+## Add metadata
+If a dataset is cross-sectional or we wish to treat it as if it were (i.e., where data collection rounds are ignored) we can create `Y`, an instance of the `YouthvarsProfile` module, to add minimal metadata (the name of the  unique identifier variable).
+
+```{r}
+Y <- YouthvarsProfile(a_Ready4useDyad = X, id_var_nm_1L_chr = "fkClientID")
+```
+
+If the temporal dimension of the dataset is important, it may be therefore preferable to instead transform `X` into a `YouthvarsSeries` module instance.  `YouthvarsSeries` objects contain all of the fields of `YouthvarsProfile` objects, but also include additional fields that are specific for longitudinal datasets (e.g. `timepoint_var_nm_1L_chr` and `timepoint_vals_chr` that respectively specify the data-collection timepoint variable name and values and `participation_var_1L_chr` that specifies the desired name of a yet to be created variable that will summarise the data-collection timepoints for which each unit record supplied data).
+
+```{r}
+Z <- YouthvarsSeries(a_Ready4useDyad = X,
+                     id_var_nm_1L_chr = "fkClientID",
+                     participation_var_1L_chr = "participation",
+                     timepoint_vals_chr = c("Baseline","Follow-up"),
+                     timepoint_var_nm_1L_chr = "round")
+```
+
+## YouthvarsProfile methods
+### Inspect data
+We can now specify the variables that we would like to prepare descriptive statistics for by using the `renew` method. The variables to be profiled are specified in the `profile_chr` argument, the number of decimal digits (default = 3) of numeric values in the summary tables to be generated can be specified with `nbr_of_digits_1L_int`.
+
+```{r}
+Y <- renew(Y, nbr_of_digits_1L_int = 2L, profile_chr = c("d_age","d_sexual_ori_s","d_studying_working"))
+```
+
+We can now view the descriptive statistics we created in the previous step.
+
+```{r overalltb, tab.cap='Descriptive summary', tab.id = 'overalltb', results="asis"}
+Y %>%
+  exhibit(profile_idx_int = 1L, scroll_box_args_ls = list(width = "100%"))
+```
+
+We can also plot the distributions of selected variables in our dataset.
+
+```{r totalscsnlfig, fig.cap="SOFAS total scores", out.width = "600px"}
+depict(Y, var_nms_chr = c("c_sofas"), labels_chr = c("SOFAS"))
+```
+
+
+## YouthvarsSeries methods
+### Validate data
+To explore longitudinal data we need to first use the `ratify` method to ensure that `Z` has been appropriately configured for methods examining datasets reporting measures at two timepoints.
+
+```{r}
+Z <- ratify(Z,
+            type_1L_chr = "two_timepoints")
+```
+
+### Inspect data
+We can now specify the variables that we would like to prepare descriptive statistics for using the `renew` method. The variables to be profiled are specified in arguments beginning with "compare_". Use `compare_ptcpn_chr` to compare variables based on whether cases reported data at one or both timepoints and `compare_by_time_chr` to compare the summary statistics of variables by timepoints, e.g at baseline and follow-up. If you wish these comparisons to report p values, then use the `compare_ptcpn_with_test_chr` and `compare_by_time_with_test_chr` arguments.
+
+```{r}
+Z <- renew(Z,
+           compare_by_time_chr = c("d_age","d_sexual_ori_s","d_studying_working"),
+           compare_by_time_with_test_chr = c("k6_total", "phq9_total", "bads_total"),
+           compare_ptcpn_with_test_chr = c("k6_total", "phq9_total", "bads_total")) 
+```
+
+The tables generated in the preceding step can be inspected using the `exhibit` method.
+
+```{r participtb, tab.cap='Outcomes by data completeness', tab.id = 'participtb', results="asis"}
+Z %>%
+  exhibit(profile_idx_int = 1L,
+          scroll_box_args_ls = list(width = "100%"))
+```
+
+```{r outcomestb, tab.cap='Outcomes by data collection round', tab.id = 'outcomestb', results="asis"}
+Z %>%
+  exhibit(profile_idx_int = 2L,
+          scroll_box_args_ls = list(width = "100%"))
+```
+
+```{r outcomestbtst, tab.cap='Outcomes by data collection round (with p values)', tab.id = 'outcomestbtst', results="asis"}
+Z %>%
+  exhibit(profile_idx_int = 3L,
+          scroll_box_args_ls = list(width = "100%"))
+```
+
+The `depict` method can create plots, comparing numeric variables by timepoint.
+
+```{r totalsfig, fig.cap="SOFAS total scores by data collection round", out.width = "600px"}
+depict(Z,
+       type_1L_chr = "by_time",
+       var_nms_chr = c("c_sofas"),
+       label_fill_1L_chr = "Time",#
+       labels_chr = c("SOFAS"),#
+       y_label_1L_chr = "")
+```
+
+## Share data
+**If and only if the dataset you are working with is appropriate for public dissemination (e.g. is synthetic data), you can use the following workflow for sharing it.**
+We can share the dataset we created for this example using the `share` method, specifying the repository to which we wish to publish the dataset (and for which we have write permissions) in a ([Ready4useRepos object](https://ready4-dev.github.io/ready4use/articles/V_01.html)). 
+
+```{r eval = F}
+A <- Ready4useRepos(gh_repo_1L_chr = "ready4-dev/youthvars", # Replace with your repository 
+                          gh_tag_1L_chr = "Documentation_0.0"), # (need write permissions).
+A <- share(A,
+           obj_to_share_xx = Z,
+           fl_nm_1L_chr = "ymh_YouthvarsSeries")
+```
+
+`Z` is now available for download as the file `ymh_YouthvarsSeries.RDS` from the ["Documentation_0.0" release of the youthvars package](https://github.com/ready4-dev/youthvars/releases/tag/Documentation_0.0).