FreesearchR/vignettes/FreesearchR.Rmd

---
title: "FreesearchR"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{FreesearchR}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include=FALSE}
knitr::opts_chunk$set(echo = TRUE,eval = FALSE)
library(FreesearchR)
```

# Getting started with ***FreesearchR***

Below is a simple walk-trough and basic instructions for the functions on the FreesearchR app.

## Launching

The easiest way to get started is to launch [the hosted version of the app on shinyapps.io (click this link)](https://agdamsbo.shinyapps.io/freesearcheR/).

Additionally you have the option to run the app locally with access to any data in your current working environment.

To do this, open *R* (or RStudio or similar), and run the following code to install the latest version of ***FreesearchR*** and launch the app:

```{r}
require("pak")
pak::pak("agdamsbo/FreesearchR")
library(FreesearchR)
FreesearchR::launch_FreesearchR()
```

As a small note, a standalone Windows app version is on the drawing board as well, but no time frame is available.

## Importing data

Once in the app and in the "**Import**", you have three options available for importing data: file upload, REDCap server export and local or sample data.

After choosing a data source, you can set a threshold to filter data be completenes and further manually specify variables to include for analyses.

### File upload

Currently several data file formats are supported for easy import (csv, txt, xls(x), ods, rds, dta). If importing workbooks (xls(x) or ods), you are prompted to specify sheet(s) to import. If choosing multiple sheets, these are automatically merged by common variable(s), so please make sure that key variables are correctly named identically.

A notification is posted with error or success. After succesfull import data can be previewed directly by clicking "click to see data" in the notification.

### REDCap server export

Export data directly from a REDCap server. You need to first generate an API-token ([see these instruction](https://confluence.research.cchmc.org/pages/viewpage.action?pageId=50987698)) in REDCap. Make sure you have the necessary rights to do so.

Please don't store the API-key on your device unless encrypted or in a keyring, as this may compromise data safety. Log in to your REDCap server and retrieve the token when needed.

Type the correct webaddress of your REDCap server.

The module will validate the information and you can click "Connect".

This will unfold options to preview your data dictionary (the main database metadata), choose fields/variables to download as well as filtering options.

### Local or sample data

When opening the online hosted app, this is mainly for testing purposes. When running the app locally from *R* on your own computer, you will find all data.frames in the current environment here. This extends the possible uses of this app to allow for quick and easy data insights and code generation for basic plotting to fine tune.

## Data

This is the panel to get a good overview of your data, check data is classed and formatted correctly, perform simple modifications and filter data. 

### Summary

Here, the data variables can be inspected with a simple visualisation and a few key measures. Also, data filtering is available at two levels: 

   - Data type filtering allows to filter by variable [data type](https://agdamsbo.github.io/FreesearchR/articles/data-types.html)
   
   - Observations level filtering allow to filter data by variable

### Modify

Re-class, rename, and relabel variables. Subset data, create new variables and reorder factor levels. Also, compare the modified dataset to the original and restore the original data.

## Evaluate

This panel allows for basic data evaluation.

### Characteristics

Create a classical baseline characteristics table with optional data stratification and comparisons.

### Correlation matrix

Visualise variable correlations and get suggestions to exclude highly correlated variables.

## Visuals

There are a number of plotting options to visualise different aspects of the data.

Below are the available plot types listed.

```{r echo = FALSE, eval = TRUE}
c("continuous", "dichotomous", "categorical") |> 
  lapply(\(.x){
    dplyr::bind_cols(
      dplyr::tibble("Data type"=.x),
      supported_plots() |> 
      lapply(\(.y){
        if (.x %in% .y$primary.type){
          .y[c("descr","note")]|> dplyr::bind_cols()
        }
})|> 
  dplyr::bind_rows() |> 
  setNames(c("Plot type","Description")))
  }) |> 
  dplyr::bind_rows() |> 
  # toastui::datagrid(filters=TRUE,theme="striped") |> 
  knitr::kable()
```

Export the plots directly from the sidebar with easily adjusted plot dimensions for your next publication.

Also copy the code to generate the plot in your own R-environment and fine tune all the small details.

## Regression

This section is only intended for very simple explorative analyses and as a proof-of-concept for now. If you are doing complex regression analyses you should probably just write the code yourself.

Below are the available regression types listed.

```{r echo = FALSE, eval = TRUE}
c("continuous", "dichotomous", "categorical") |> 
  lapply(\(.x){
    dplyr::bind_cols(
      dplyr::tibble("Data type"=.x),
      supported_functions()|> 
      lapply(\(.y){
        if (.x %in% .y$out.type){
          .y[c("descr","fun","design")]|> dplyr::bind_cols()
        }
})|> 
  dplyr::bind_rows() |> 
  setNames(c("Regression model","Function","Study design")))
  }) |> 
  dplyr::bind_rows() |> 
  # toastui::datagrid(filters=TRUE,theme="striped") |> 
  knitr::kable()
```

### Table

Generate simple regression models and get the results in a nice table. This will also be included in the exported report.

### Plots

Plot the coefficients from the regression models in a forest plot. Choose which model(s) to include.

### Checks

Check model assumptions visually. Supported checks can be chosen.

## Download

### Report

Download a nice report with baseline characteristics and regression model results. Choose between MS Word or LibreOffice format.

### Data

Export the modified dataset in different formats.

### Code

See all the code snippets from the different steps in your data evaluation.