diff --git a/latest-tag/404.html b/latest-tag/404.html index 3b8defcef9..86871657d0 100644 --- a/latest-tag/404.html +++ b/latest-tag/404.html @@ -7,8 +7,8 @@ Page not found (404) • teal - - + + Contributor Covenant Code of Conduct • tealContributor Covenant Code of Conduct • teal @@ -10,7 +10,7 @@ teal - 0.14.0 + 0.15.0
part of NESTpharmaverse
+ + + + + +
+ + + + +
+
+

Actors

+

NEST +CoreDev

+ + + Source: vignettes/blueprint/actors.Rmd +
actors.Rmd
+
+ + + +

There are two main actors in the teal development:

+
    +
  • +teal App Developer
    • +
  • +teal Module Developer
    • +
+
+

+teal app developer +

+ +
+%% This is a mermaid diagram, if you see this the plot failed to render. Sorry.
+graph LR
+    A[teal App Developer]--utilizes--> B[teal modules]
+    B--to create--> C[teal app]
+    D[app user]--uses--> C
+style A fill:lightblue
+style C fill:gold
+style D fill:pink
+
+

The primary responsibility of a teal app developer is to +leverage the available building blocks of the teal +framework to create a functional teal app that analyses the +data.

+

To expedite the app creation process, developers can take advantage +of pre-existing teal modules found in R +packages like teal.modules.general and +teal.modules.clinical.

+

These modules are designed with a focus on standardization and +versatility, making them suitable for a wide range of use cases.

+

When developing a teal app, the developer will select +the most appropriate teal modules and integrate them into +the app’s interface to ensure seamless usability for end-users.

+

To learn more about the existing modules, visit teal.gallery, +which contains several demo applications and their source code.

+
+
+

+teal module developer +

+
+%% This is a mermaid diagram, if you see this the plot failed to render. Sorry.
+graph LR
+    A[Teal App Developer]--utilizes--> B[teal modules]
+    E[Teal Module Developer]--develops--> B
+    B--to create--> C[teal app]
+    D[app user]--uses--> C
+style A fill:lightblue
+style E fill:lightgreen
+style D fill:pink
+style C fill:gold
+
+

The main duty of a teal module developer is to construct +a compatible teal module that can be utilized within the +teal framework.

+

Several factors influence the scope and requirements for building a +teal module.

+

When creating a reusable teal module, it’s advisable to +focus on making it as general and adaptable as feasible to maximize the +possibilities of being re-used in the future. However, developers have +the freedom to create a teal module that is customized to +suit the specific demands of a project.

+

Ultimately, one or more teal modules are employed to +construct a teal app.

+

To learn more about creating custom modules follow the Tutorial on Creating a Custom +Module.

+
+
+

Workflow in a clinical trial study +

+
+%% This is a mermaid diagram, if you see this the plot failed to render. Sorry.
+%%| fig-width: 7.5
+graph LR
+    subgraph Study B
+        A2[Study Teal App Developer]--utilizes--> B2[teal modules]
+        E2[Study Teal Module Developer]-.develops.-> B2
+        B2--to create--> C2[study teal app]
+        D2[study app user]--uses--> C2
+    end
+    E3[Teal Module Developer]--develops--> B
+    E3--develops-->B2
+    subgraph Study A
+        A[Study Teal App Developer]--utilizes--> B[teal modules]
+        E[Study Teal Module Developer]-.develops.-> B
+        B--to create--> C[study teal app]
+        D[study app user]--uses--> C
+    end
+style A fill:lightblue
+style A2 fill:lightblue
+style E fill:limegreen
+style E2 fill:limegreen
+style E3 fill:lightgreen
+style D fill:pink
+style D2 fill:pink
+style C fill:gold
+style C2 fill:gold
+
+

In a clinical trial study setting, a unique study +teal app developer is assigned to each study team +and is accountable for developing a tailored teal app for +their respective study.

+

The study teal app developer will +initially leverage existing teal modules from +R packages created by teal module +developers.

+

In cases where there is a need to create new modules tailored to the +study, a study teal module developer will +need to be involved.

+

Upon completion, each study team will have their own designated +teal app tailored to their specific study.

+
+
+
+ + + + +
+ + + + + + + diff --git a/latest-tag/articles/blueprint/dataflow.html b/latest-tag/articles/blueprint/dataflow.html new file mode 100644 index 0000000000..08776069d7 --- /dev/null +++ b/latest-tag/articles/blueprint/dataflow.html @@ -0,0 +1,207 @@ + + + + + + + + +Data Flow • teal + + + + + + + + + + + Skip to contents + + +
+ + + + +
+
+

Data Flow

+

NEST +CoreDev

+ + + Source: vignettes/blueprint/dataflow.Rmd +
dataflow.Rmd
+
+ + + + +
+%% This is a mermaid diagram, if you see this the plot failed to render. Sorry.
+sequenceDiagram;
+    autonumber
+    participant data
+    participant filters
+    participant filtered data
+    participant teal module
+    data->filters: gets
+    filters->>filtered data: becomes
+    filtered data->>teal module: sent to
+
+

The sequence diagram above illustrates the different stages that data +goes through within the teal framework, supported by the +teal.slice package:

+
    +
  1. Data is created and loaded into teal app; +
      +
    • Data sets are wrapped in a teal_data before being +passed to the app;
      • +
    • The teal_data class +facilitates reproducibility;
      • +
    +
    2. +
  2. Data is passed to the filter panel; +
      +
    • Users (or app developers) can specify filters to +apply;
      • +
    • Filters can be specified globally, for the whole app, or for +specific modules;
      • +
    • Filtering code is appended to the data;
      • +
    • See the Filter panel vignette for +details;
      • +
    +
    3. +
  3. Filtered data is sent to teal modules for analysis; +
      +
    • Each module receives a teal_data object so analysis +code applied to the data is tracked (and can be used to reproduce +the whole analysis);
      • +
    +
    4. +
+

Whenever filters are added or removed, the data coming into modules +is re-computed, providing the teal module with new filtered +data to conduct the required analysis.

+
+
+ + + + +
+ + + + + + + diff --git a/latest-tag/articles/blueprint/filter_panel.html b/latest-tag/articles/blueprint/filter_panel.html new file mode 100644 index 0000000000..9f38282327 --- /dev/null +++ b/latest-tag/articles/blueprint/filter_panel.html @@ -0,0 +1,216 @@ + + + + + + + + +Filter Panel • teal + + + + + + + + + + + Skip to contents + + +
+ + + + +
+
+

Filter Panel

+

NEST +CoreDev

+ + + Source: vignettes/blueprint/filter_panel.Rmd +
filter_panel.Rmd
+
+ + + +
+

Introduction +

+

+

+

The teal.slice package provides teal +applications with the filter panel, a powerful tool for +exploring and analyzing data, and a key component of the +teal framework.

+

One of the great things about the filter panel is that it comes +built-in with teal, requiring no programming knowledge to +use.

+

The filter panel provides a convenient way for users to subset their +data, simplifying the process of exploration and comprehension. +Moreover, users can activate or deactivate filter states interactively, +either individually or globally, using the filter panel.

+
+ +
+
+
+

Filter flow +

+ +
+%% This is a mermaid diagram, if you see this the plot failed to render. Sorry.
+sequenceDiagram
+    autonumber
+    data->teal.slice: processed by
+    teal.slice->>shiny inputs: creates
+    Note over teal.slice,shiny inputs: based on data type
+    shiny inputs->>reactive dataset: updates
+    reactive dataset->>teal modules: processed by
+
+

The filter panel creates subsets of data. Subsetting is achieved by +creating filter states, each of which holds a logical predicate (filter +condition) that is applied to single variables. These filter conditions +are composed into a single expression, a call to a particular function +(e.g. dplyr::filter), and that expression is evaluated to +create a filtered data subset.

+

The process is entirely interactive. Filter states can be created, +removed, and changed at will, however, the app developer may choose to +constrain or even restrict them.

+

When a filter state is created, the filter panel generates a +filter card with shiny inputs appropriate to the +type of the variable, e.g. range selectors for numeric columns and sets +of checkboxes or drop-down menus for categorical ones.

+

As users interact with the filter cards, the subsetting complete +expression is updated and filtered data is recomputed.

+

The filtered data is passed to teal modules for +downstream analysis. The subsetting expression is returned along with +the data, ensuring an unbroken track record of the entire analysis. +Signature of the data are also stored to ensure reproducible +results.

+
+
+
+ + + + +
+ + + + + + + diff --git a/latest-tag/articles/blueprint/in_app_data.html b/latest-tag/articles/blueprint/in_app_data.html new file mode 100644 index 0000000000..82fce28675 --- /dev/null +++ b/latest-tag/articles/blueprint/in_app_data.html @@ -0,0 +1,186 @@ + + + + + + + + +In-App Data • teal + + + + + + + + + + + Skip to contents + + +
+ + + + +
+
+

In-App Data

+

NEST +CoreDev

+ + + Source: vignettes/blueprint/in_app_data.Rmd +
in_app_data.Rmd
+
+ + + +
+

Building data in the App +

+

Typically the data that is passed into a teal +application is available before the app is run. However, this is not +always true and in some cases the data will be built only after the app +has started. A good example is pulling the data from an external +repository, like a database, or uploading a file. Additional +authentication may be required.

+
+

+teal_data_module +

+

Preprocessing actions can be performed in-app using the +teal_data_module. Rather than passing a +teal_data object to the app, one may pass a +shiny module that returns a +teal_data object (wrapped in a reactive expression). This +allows the app developer to include user actions data creation, +fetching, and even pre-filtering modification.

+
+
+
+

Further reading +

+

A complete explanation of using the teal_data_module can +be found in this teal +vignette

+
+
+
+ + + + +
+ + + + + + + diff --git a/latest-tag/articles/blueprint/index.html b/latest-tag/articles/blueprint/index.html new file mode 100644 index 0000000000..f344774094 --- /dev/null +++ b/latest-tag/articles/blueprint/index.html @@ -0,0 +1,166 @@ + + + + + + + + +About Technical Blueprint • teal + + + + + + + + + + + Skip to contents + + +
+ + + + +
+
+

About Technical Blueprint

+

NEST +CoreDev

+ + + Source: vignettes/blueprint/index.Rmd +
index.Rmd
+
+ + + +

Welcome to teal Technical Blueprint documentation!

+

The purpose of this material is to aid new developer’s comprehension +of the fundamental principles of the teal framework. We +will explore crucial teal concepts such as data flow, +actors, and filter panel, among others.

+

While this material will be presented at a high-level, we will direct +you to our vignettes for a more in-depth understanding.

+

Our hope is that this resource will provide new developers with a +strong grasp of teal products, enabling them to contribute +to code with confidence.

+
+
+ + + + +
+ + + + + + + diff --git a/latest-tag/articles/blueprint/input_data.html b/latest-tag/articles/blueprint/input_data.html new file mode 100644 index 0000000000..ed45666323 --- /dev/null +++ b/latest-tag/articles/blueprint/input_data.html @@ -0,0 +1,222 @@ + + + + + + + + +Input Data • teal + + + + + + + + + + + Skip to contents + + +
+ + + + +
+
+

Input Data

+

NEST +CoreDev

+ + + Source: vignettes/blueprint/input_data.Rmd +
input_data.Rmd
+
+ + + +
+

Introduction +

+

Reproducibility is paramount in the pharmaceutical industry. Accurate +and consistent results are essential to ensure high-quality research and +the safety of patients. By prioritizing reproducibility, researchers can +validate their methods, confirm their findings, and contribute to the +advancement of the field.

+

The teal.code package provides the qenv +class that facilitates code reproducibility. Code is passed to a +qenv object, where is evaluated in a specific environment. +qenv also stores the code so that it can be retrieved on +request.

+

The teal_data class, which serves as the primary data +interface for teal applications, inherits this code +tracking behavior from qenv.

+
+
+

Preparing data for a teal application +

+

All teal applications run on data provided in a +teal_data object. Data objects are stored and modified +within the environment of the teal_data object and all +R code used is tracked, which allows for the code to be +evaluated and executed in the teal application, and +reproduced outside the teal application. This includes data +loading, preprocessing, filtering, transformations, and plotting, +etc.

+

The teal_data object makes it easy for users to +reproduce and validate the results of their analyses.

+

+

Learn more about the use of teal_data in the teal.data +package vignettes.

+
+
+

+Show R Code and Reporter +

+

In both the teal.modules.clinical and +teal.modules.general packages, you’ll find that most +modules include a convenient Show R Code button. When this +button is clicked, a modal window appears, revealing the R +code responsible for generating the module’s output. This functionality +is achieved by inspecting the teal_data object and +retrieving code from it. With the Show R Code button, users +can easily copy and independently run the code to reproduce the analysis +presented in the teal module.

+
+Show R Code
Show R Code
+
+

The Reporter feature also leverages the teal_data object +in its operation. Much like the Show R Code mechanism, the +code displayed in a Reporter Card is extracted from the +teal_data object.

+
+Reporter
Reporter
+
+

To learn more about the Reporter feature, please visit +the teal.reporter +documentation.

+

Overall, qenv from teal.code and its child +class, teal_data, are powerful tools for ensuring code +reproducibility and promoting high-quality research in the +R programming language.

+
+
+
+ + + + +
+ + + + + + + diff --git a/latest-tag/articles/blueprint/input_data_files/figure-html/teal_data_dot_diagram-1.png b/latest-tag/articles/blueprint/input_data_files/figure-html/teal_data_dot_diagram-1.png new file mode 100644 index 0000000000..1912576849 Binary files /dev/null and b/latest-tag/articles/blueprint/input_data_files/figure-html/teal_data_dot_diagram-1.png differ diff --git a/latest-tag/articles/blueprint/intro.html b/latest-tag/articles/blueprint/intro.html new file mode 100644 index 0000000000..516331727a --- /dev/null +++ b/latest-tag/articles/blueprint/intro.html @@ -0,0 +1,228 @@ + + + + + + + + +Introduction • teal + + + + + + + + + + + Skip to contents + + +
+ + + + +
+
+

Introduction

+

NEST +CoreDev

+ + + Source: vignettes/blueprint/intro.Rmd +
intro.Rmd
+
+ + + +

teal is an interactive data exploration framework based +on Shiny, designed primarily to analyze CDISC clinical trial data.

+

A Shiny Application created with teal offers users the +ability to:

+
    +
  • Import data from external sources;
    • +
  • Dynamically filter data for analysis;
    • +
  • Generate reproducible code for future analysis;
    • +
  • Create and download reports of analysis results (for analysis +modules that support reporting).
    • +
+

Moreover, the teal framework provides application +developers with a wide range of customizable standard analysis modules +to integrate into their applications, along with a logging framework +that facilitates debugging. Additionally, advanced users of the +framework can develop new analysis modules and easily integrate them +into any teal application.

+

The teal framework’s functionality draws heavily from +the following packages:

+ ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
R packageDescription
teal +shiny-based interactive exploration +framework for analyzing data
teal.widgets +shiny UI components used within +teal +
teal.dataprovides the data structure used in all +teal applications
teal.sliceprovides the filter panel to allow dynamic filtering of +data
teal.codeprovides a mechanism for tracking code to reproduce an +analysis
teal.loggerstandardizes logging within teal +framework
teal.reporterallows teal applications to generate +reports
+

Although these packages are mentioned in the material, we strongly +recommend visiting their vignettes to learn more about them.

+

Learn on how to make your first teal application here!

+
+
+ + + + +
+ + + + + + + diff --git a/latest-tag/articles/blueprint/module_encapsulation.html b/latest-tag/articles/blueprint/module_encapsulation.html new file mode 100644 index 0000000000..ee82258691 --- /dev/null +++ b/latest-tag/articles/blueprint/module_encapsulation.html @@ -0,0 +1,193 @@ + + + + + + + + +Module Encapsulation • teal + + + + + + + + + + + Skip to contents + + +
+ + + + +
+
+

Module Encapsulation

+

NEST +CoreDev

+ + + Source: vignettes/blueprint/module_encapsulation.Rmd +
module_encapsulation.Rmd
+
+ + + +
+

Introduction +

+

The teal framework leverages the shiny +module concept to enable encapsulation of analytical actions in +teal modules, while maintaining seamless communication +between the modules and the application.

+
+
+

Benefits +

+

By implementing the modular app technique from the shiny module into +the creation of the teal module, several benefits are +realized:

+
    +

  1. Streamlined maintenance
    +The development of the teal module becomes more manageable, +as it can function independently from the teal framework. +This separation allows developers to maintain the module with ease. This +approach has been successfully applied in R packages +dedicated to teal module development, such as +teal.modules.general and +teal.modules.clinical.

    2. +

  2. Enhanced focus on output
    teal module developers can concentrate solely on refining +parameters or encoding, and output aspects (such as data summarization +and visualization) without the need to concern themselves with the +intricacies of the teal framework. When developed +correctly, the module seamlessly integrates with +teal.

    3. +

  3. Facilitated collaboration
    teal module development becomes an accessible entry point +for developers interested in collaborating. This approach encourages +user collaboration for the improvement of teal modules, as +developers gain a deeper understanding of the mechanics of the +teal framework.

    4. +
+
+
+
+ + + + +
+ + + + + + + diff --git a/latest-tag/articles/blueprint/product_map.html b/latest-tag/articles/blueprint/product_map.html new file mode 100644 index 0000000000..8b5ad97e39 --- /dev/null +++ b/latest-tag/articles/blueprint/product_map.html @@ -0,0 +1,235 @@ + + + + + + + + +Product Map • teal + + + + + + + + + + + Skip to contents + + +
+ + + + +
+
+

Product Map

+

NEST +CoreDev

+ + + Source: vignettes/blueprint/product_map.Rmd +
product_map.Rmd
+
+ + + + +
+%% This is a mermaid diagram, if you see this the plot failed to render. Sorry.
+flowchart RL
+teal
+subgraph features
+  direction LR
+  teal.data
+  teal.slice
+  teal.code
+  teal.logger
+  teal.widgets
+end
+subgraph modules
+  direction RL
+  teal.modules.general
+  teal.modules.clinical
+  teal.osprey
+  teal.goshawk
+  teal.modules.hermes
+end
+teal--has-->features
+features--builds-->modules
+modules--creates-->teal
+subgraph modules
+  teal.modules.general
+  teal.modules.clinical
+  teal.osprey
+  teal.goshawk
+  teal.modules.hermes
+end
+subgraph calculations
+  direction RL
+  tern
+  osprey
+  goshawk
+  hermes
+end
+tern--supports-->teal.modules.clinical
+osprey--supports-->teal.osprey
+goshawk--supports-->teal.goshawk
+hermes--supports-->teal.modules.hermes
+style teal fill:lightblue
+style features fill:lightgreen
+style modules fill:pink
+
+

teal is a modular framework that relies on a suite of +related packages, as illustrated in the above diagram, to provide a wide +range of functionalities.

+

teal’s primary function is to create web app for +analyzing clinical trial data but it has a multitude of +features distributed across various packages.

+

Developers can selectively leverage these packages, such as +teal.widgets, teal.code, and +teal.logger, to build teal +modules for a teal app. This approach gives the developers +the tools that speed up their work and avoid re-implementing existing +logic and UI elements.

+

The teal modules utilize various packages such as +tern, osprey, and goshawk to +perform calculations and analyses. These packages provide +support to the teal modules by performing +all computations while the modules only have to focus on how to wrap the +input options and the output.

+

Once developed, new and existing modules can be integrated into +teal to create a functional +teal app.

+
+

Why so many packages? +

+

By breaking down teal features, modules, and +calculations into dedicated packages, maintenance is made significantly +more manageable.

+
+
+
+ + + + +
+ + + + + + + diff --git a/latest-tag/articles/teal-bs-themes.html b/latest-tag/articles/bootstrap-themes-in-teal.html similarity index 64% rename from latest-tag/articles/teal-bs-themes.html rename to latest-tag/articles/bootstrap-themes-in-teal.html index 92b6c62ace..dd7ca20bc0 100644 --- a/latest-tag/articles/teal-bs-themes.html +++ b/latest-tag/articles/bootstrap-themes-in-teal.html @@ -6,12 +6,12 @@ -teal and Bootstrap Themes • teal +Bootstrap Themes in teal • teal - - + + - + + + @@ -27,7 +27,7 @@ teal - 0.14.0 + 0.15.0
part of NESTpharmaverse
+ + + + + +
+ + + + +
+
+

Data as shiny Module

+

NEST +CoreDev

+ + + Source: vignettes/data-as-shiny-module.Rmd +
data-as-shiny-module.Rmd
+
+ + + +
+

Introduction +

+

Proper functioning of any teal application requires the +presence of a teal_data object. Typically, a +teal_data object created in the global environment will be +passed to the data argument in init. This +teal_data object should contain all elements necessary for +successful execution of the application’s modules.

+

In some scenarios, however, application developers may opt to +postpone some data operations until the application runtime. This can be +done by passing a special shiny module to the +data argument. The teal_data_module function +is used to build such a module from the following components:

+
    +
  • a UI function; accepts only one argument, id; defines +user interface elements for the data module
    • +
  • a server function: accepts only one argument, id; +defines server logic for the data module, including data creation; must +return a reactive expression containing a teal_data +object
    • +
+

teal will run this module when the application starts +and the resulting teal_data object that will be used +throughout all teal (analytic) modules.

+
+
+

Creating data in-app +

+

One case for postponing data operations is datasets that are dynamic, +frequently updated. Such data cannot be created once and kept in the +global environment. Using teal_data_module enables creating +a dataset from scratch every time the user starts the application.

+ +
+data_module <- teal_data_module(
+  ui = function(id) div(),
+  server = function(id) {
+    moduleServer(id, function(input, output, session) {
+      reactive({
+        data <- within(
+          teal_data(),
+          {
+            dataset1 <- iris
+            dataset2 <- mtcars
+          }
+        )
+        datanames(data) <- c("dataset1", "dataset2") # optional
+        data
+      })
+    })
+  }
+)
+
+
+app <- init(
+  data = data_module,
+  modules = example_module()
+)
+
+if (interactive()) {
+  shinyApp(app$ui, app$server)
+}
+

See ?qenv for a detailed explanation of how to use +the within method.

+
+
+

Modification of data in-app +

+

Another reason to postpone data operations is to involve the +application user in the preprocessing stage. An initial, constant form +of the data can be created in the global environment and then modified +once the app starts.

+

The following example illustrates how teal_data_module +can be utilized to subset data based on the user inputs:

+
+data <- within(teal_data(), {
+  dataset1 <- iris
+  dataset2 <- mtcars
+})
+datanames(data) <- c("dataset1", "dataset2")
+
+data_module <- teal_data_module(
+  ui = function(id) {
+    ns <- NS(id)
+    div(
+      selectInput(ns("species"), "Select species to keep",
+        choices = unique(iris$Species), multiple = TRUE
+      ),
+      actionButton(ns("submit"), "Submit")
+    )
+  },
+  server = function(id) {
+    moduleServer(id, function(input, output, session) {
+      eventReactive(input$submit, {
+        data_modified <- within(
+          data,
+          dataset1 <- subset(dataset1, Species %in% selected),
+          selected = input$species
+        )
+        data_modified
+      })
+    })
+  }
+)
+
+app <- init(
+  data = data_module,
+  modules = example_module()
+)
+
+if (interactive()) {
+  shinyApp(app$ui, app$server)
+}
+

Note that running preprocessing code in a module as opposed to the +global environment will increase app loading times. It is recommended to +keep the constant code in the global environment and to move only the +dynamic parts to a data module.

+
+
WARNING +
+

When using teal_data_module to modify a pre-existing +teal_data object, it is crucial that the server function +and the data object are defined in the same environment, otherwise the +server function will not be able to access the data object. This means +server functions defined in packages cannot be used.

+
+
+

Extending existing teal_data_modules +

+

The server logic of a teal_data_module can be modified +before it is used in an app, using the within function. +This allows the teal_data object that is created in the +teal_data_module to be processed further.

+

In the previous example, data_module takes a predefined +teal_data object and allows the app user to select a +subset. The following example modifies data_module so that +new columns are added once the data is retrieved.

+
+data_module_2 <- within(
+  data_module,
+  {
+    # Create new column with Ratio of Sepal.Width and Petal.Width
+    dataset1$Ratio.Sepal.Petal.Width <- round(dataset1$Sepal.Width / dataset1$Petal.Width, digits = 2L)
+    # Create new column that converts Miles per Galon to Liter per 100 Km
+    dataset2$lp100km <- round(dataset2$mpg * 0.42514371, digits = 2L)
+  }
+)
+
+app <- init(
+  data = data_module_2,
+  modules = example_module()
+)
+
+if (interactive()) {
+  shinyApp(app$ui, app$server)
+}
+
+
+
+
+ + + + +
+ + + + + + + diff --git a/latest-tag/articles/filter-panel.html b/latest-tag/articles/filter-panel.html index 55f6353005..a33f725b47 100644 --- a/latest-tag/articles/filter-panel.html +++ b/latest-tag/articles/filter-panel.html @@ -8,8 +8,8 @@ Filter Panel • teal - - + + @@ -27,7 +27,7 @@ teal - 0.14.0 + 0.15.0
part of NESTpharmaverse
- - - - - -
- - - - -
-
-

Input `ADaM` data in a teal application

-

NEST -CoreDev

- -

2022-04-20

- - -
including-adam-data-in-teal.Rmd
-
- - - -
-

Introduction -

-

To include ADaM data in a teal app, the -teal.data::cdisc_data function is used.

-

The cdisc_data function allows teal -applications to include multiple datasets, identifying merge keys and -providing information to produce R code for reproducibility.

-

There is an advantage to passing CDISC datasets that -adhere to ADaM standards to these functions in that the -code is minimized. However, the dataset-related functions also include -the flexibility to work with non-standard datasets provided that merge -keys and the relationship between the datasets are specified.

-

The examples below illustrate the usage of these different dataset -functions for example cdisc_dataset and -dataset. For more information, see documentation in -teal.data.

-
-
-

Keys -

-

Primary keys serve as unique row identifiers in individual datasets -and thus need to be specified for each dataset and dataset connector. -These can be specified on the most general dataset constructor -dataset as shown below.

-
-library(teal)
-
-# using cdisc_dataset, keys are automatically derived for standard datanames
-# (although they can be overwritten)
-adsl <- data.frame(
-  STUDYID = "study",
-  USUBJID = 1:10,
-  SEX = sample(c("F", "M"), 10, replace = TRUE),
-  AGE = rpois(10, 40)
-)
-dataset_adsl <- cdisc_dataset("ADSL", adsl)
-class(dataset_adsl)
-
## [1] "CDISCTealDataset" "TealDataset"      "R6"
-

When passing multiple datasets to the cdisc_data -function, dataset relationship are set using join_keys and -join_key and these are used to merge datasets together -within teal apps.

-

In the example below, two standard CDISC datasets -(ADSL and ADTTE) are passed to the -aforementioned function. In the case of CDISC datasets that -adhere to ADaM standards, the merge keys do not need to be -manually specified. Keys are automatically added if -dataname matches one of the implemented standards as -documented in the cdisc_dataset function. This minimizes -the code needed to allow data merges as seen in this example:

-
-adsl <- data.frame(
-  STUDYID = "study",
-  USUBJID = 1:10,
-  SEX = sample(c("F", "M"), 10, replace = TRUE),
-  AGE = rpois(10, 40)
-)
-adtte <- rbind(adsl, adsl, adsl)
-adtte$PARAMCD <- rep(c("OS", "EFS", "PFS"), each = 10)
-adtte$AVAL <- c(
-  rnorm(10, mean = 700, sd = 200), # dummy OS level
-  rnorm(10, mean = 400, sd = 100), # dummy EFS level
-  rnorm(10, mean = 450, sd = 200) # dummy PFS level
-)
-
-cdisc_data_obj <- cdisc_data(
-  cdisc_dataset(
-    dataname = "ADSL",
-    x = adsl,
-    code = '
-    adsl <- data.frame(
-      STUDYID = "study",
-      USUBJID = 1:10,
-      SEX = sample(c("F", "M"), 10, replace = TRUE),
-      AGE = rpois(10, 40)
-    )'
-  ),
-  cdisc_dataset(
-    dataname = "ADTTE",
-    x = adtte,
-    code = '
-    adtte <- rbind(adsl, adsl, adsl)
-    adtte$PARAMCD <- rep(c("OS", "EFS", "PFS"), each = 10)
-    adtte$AVAL <- c(
-      rnorm(10, mean = 700, sd = 200),
-      rnorm(10, mean = 400, sd = 100),
-      rnorm(10, mean = 450, sd = 200)
-    )'
-  )
-)
-class(cdisc_data_obj)
-
## [1] "TealData"         "TealDataAbstract" "R6"
-
-# which is equivalent to:
-example_data <- cdisc_data(
-  cdisc_dataset(
-    dataname = "ADSL",
-    x = adsl,
-    code = '
-    adsl <- data.frame(
-      STUDYID = "study",
-      USUBJID = 1:10,
-      SEX = sample(c("F", "M"), 10, replace = TRUE),
-      AGE = rpois(10, 40)
-    )',
-    keys = c("STUDYID", "USUBJID")
-  ),
-  cdisc_dataset(
-    dataname = "ADTTE",
-    x = adtte,
-    code = '
-    adtte <- rbind(adsl, adsl, adsl)
-    adtte$PARAMCD <- rep(c("OS", "EFS", "PFS"), each = 10)
-    adtte$AVAL <- c(
-      rnorm(10, mean = 700, sd = 200),
-      rnorm(10, mean = 400, sd = 100),
-      rnorm(10, mean = 450, sd = 200)
-    )',
-    keys = c("STUDYID", "USUBJID", "PARAMCD")
-  ),
-  join_keys = join_keys(
-    join_key("ADSL", "ADSL", c("STUDYID", "USUBJID")),
-    join_key("ADTTE", "ADTTE", c("USUBJID", "STUDYID", "PARAMCD")),
-    join_key("ADSL", "ADTTE", c("STUDYID", "USUBJID"))
-  )
-)
-
-app <- init(
-  data = example_data,
-  modules = example_module()
-)
-
-if (interactive()) {
-  shinyApp(app$ui, app$server)
-}
-

The [teal.data::join_keys()] function is used to specify keys:

-
    -
  • [teal.data::join_keys()] is a collection of multiple -[teal.data::join_key()] entries
    • -
  • [teal.data::join_key()] specifies the relation between two datasets: -
      -
    • -dataset_1, dataset_2 - name of two -datasets
      • -
    • -key - (optionally) named vector of column names
      • -
    -
    • -
-

Note that it is assumed that join keys are symmetric, -i.e. join_key("x", "y", "x_col" = "y_col") will enable -merge from “x” to “y” and vice-versa.

-

For more information about preprocessing, reproducibility, -relationships between datasets and DDL, please refer to the -teal.data -package.

-
-
-
- - - - -
- - - - - - - diff --git a/latest-tag/articles/including-data-in-teal-applications.html b/latest-tag/articles/including-data-in-teal-applications.html new file mode 100644 index 0000000000..c9271c83fd --- /dev/null +++ b/latest-tag/articles/including-data-in-teal-applications.html @@ -0,0 +1,473 @@ + + + + + + + + +Including Data in teal Applications • teal + + + + + + + + + + + Skip to contents + + +
+ + + + +
+
+

Including Data in teal Applications

+

NEST +CoreDev

+ + + Source: vignettes/including-data-in-teal-applications.Rmd +
including-data-in-teal-applications.Rmd
+
+ + + +
+

Data in teal Applications +

+

The teal framework readily accepts general, +non-relational data. Modules defined in the +teal.modules.general package are designed to work well with +that kind of data. Relational data is handled just as well and the +mechanism of passing data to applications is virtually the same. This +includes clinical data that conforms to the ADaM standard. +We are working on making the framework extendable so that support for +other data structures can be added with relative ease. Currently some +support is offered for the MultiAssayExperiment class.

+

All applications use the teal_data class as a data +container. teal_data objects are passed to +init to build the application, where they are modified by +the filter panel (if applicable) and passed on to modules. Thus, the +first step of building a teal app is creating a +teal_data object.

+
+

General data +

+

A teal_data object is created by calling the +teal_data function and passing data objects as +name:value pairs.

+
+library(teal)
+
+# create teal_data
+data <- teal_data(iris = iris, cars = mtcars)
+

Note that iris and cars have been added to +the datanames property of data (see datanames property).

+

This is sufficient to run a teal app.

+
+# build app
+app <- init(
+  data = data,
+  modules = example_module()
+)
+
+# run app
+shinyApp(app$ui, app$server)
+
+
+

Reproducible data +

+

A teal_data object stores data in a separate +environment. Therefore, modifying the stored datasets requires that +processing code be evaluated in that environment. Following that logic, +one can create an empty teal_data object and populate it by +evaluating code. This can be done using the eval_code +function or, more conveniently, using the within +function.

+
+# create empty object
+data_empty <- teal_data()
+
+# run code in the object
+data_populated_1 <- eval_code(data_empty, code = "iris <- iris
+                                                  cars <- mtcars")
+# alternative
+data_populated_2 <- within(data_empty, {
+  iris <- iris
+  cars <- mtcars
+})
+

The key difference between eval_code and +within is that the former accepts code as character vector +or language objects (calls and expressions), while within +accepts only inline code. See ?qenv for more +details.

+

Note that in the first example data was created by +passing data objects, so the code that was used to create the data +objects is unknown and therefore the process cannot be reproduced. +Inspecting code the in the app created above reveals a note that the +preprocessing code is absent.

+

+

The necessary code can be supplied to the code argument +of the teal_data function.

+
+data_with_code <- teal_data(
+  iris = iris, cars = mtcars,
+  code = "iris <- iris
+          cars <- mtcars"
+)
+

+

Keep in mind this code is not executed in the +teal_data’s environment, so it may not reproduce the +environment. Such an object is considered unverified (see verified property).

+

If reproducibility is required, we recommend creating an empty +teal_data object and then evaluating code.

+
+

code from file +

+

The ability to pass code as a character vector to +eval_code opens the door to using code stored in a +file.

+
+# not run
+data_from_file <- teal_data()
+data_from_file <- eval_code(data, readLines("<path_to_file>"))
+
+
+
+

Creating data in-app +

+

The one departure from passing a teal_data object to +init is when the data does not exist in the environment +where the app is run, e.g. when it has to be pulled from a +remote source. In those cases a teal_data_module must be +used. See this vignette for a +detailed description.

+


+
+
+
+

Clinical data +

+

Currently teal supports two specialized data +formats.

+
+

+ADaM data +

+

The ADaM data model, defined in CDISC standards, +specifies relationships between the subject-level parent dataset and +observation-level child datasets. The cdisc_data function +takes advantage of that fact to automatically set default joining keys +(see join_keys property). In the +example below, two standard ADaM datasets +(ADSL and ADTTE) are passed to +cdisc_data.

+
+# create cdisc_data
+data_cdisc <- cdisc_data(ADSL = teal.data::rADSL, ADTTE = teal.data::rADSL)
+
+datanames(data_cdisc)
+#> [1] "ADSL"  "ADTTE"
+join_keys(data_cdisc)
+#> A join_keys object containing foreign keys between 2 datasets:
+#> ADSL: [STUDYID, USUBJID]
+#>   <-- ADTTE: [STUDYID, USUBJID]
+#> ADTTE: [STUDYID, USUBJID, PARAMCD]
+#>   --> ADSL: [STUDYID, USUBJID]
+
+app <- init(
+  data = data_cdisc,
+  modules = example_module()
+)
+shinyApp(app$ui, app$server)
+
+
+

+MultiAssayExperiment data +

+

The MultiAssayExperiment package offers a data structure +for representing and analyzing multi-omics experiments that involve +multi-modal, high-dimensionality data, such as DNA mutations, protein or +RNA abundance, chromatin occupancy, etc., in the same biological +specimens.

+

The MultiAssayExperiment class is described in detail here.

+

MultiAssayExperiment objects (MAEs) are placed in +teal_data just like normal objects.

+
+library(MultiAssayExperiment)
+utils::data(miniACC)
+
+data_mae <- teal_data(MAE = miniACC)
+
+app <- init(
+  data = data_mae,
+  modules = example_module()
+)
+shinyApp(app$ui, app$server)
+

Due to the unique structure of a MAE, teal requires +special considerations when building teal modules. +Therefore, we cannot guarantee that all modules will work properly with +MAEs. The package teal.modules.hermes +has been developed specifically with MAE in mind and will be more +reliable.

+

The filter panel supports MAEs out of the box.

+


+
+
+
+

+teal_data properties +

+
+
+datanames +
+

The datanames property lists the objects stored in the +teal_data environment that constitute datasets of interest. +Objects passed to teal_data become automatically listed in +the datanames property of the resulting object. Objects +created in teal_data by evaluating code need not be data +objects of interest and as such they are not automatically added to +datanames. For convenience, an empty datanames +property is considered to mean “all objects in the container”. +datanames can be read or modified with the +datanames function.

+
+data_with_objects <- teal_data(iris = iris, cars = mtcars)
+data_with_code <- teal_data() %>%
+  within({
+    iris <- iris
+    cars <- mtcars
+    not_a_dataset <- "data source credits"
+  })
+datanames(data_with_objects)
+#> [1] "iris" "cars"
+datanames(data_with_code)
+#> character(0)
+datanames(data_with_code) <- c("iris", "cars")
+datanames(data_with_code)
+#> [1] "iris" "cars"
+

The datanames property serves as a communication bridge +between the data container and modules in a teal +application. In teal all modules are called with a +datanames argument that determines which of the variables +in the teal_data object they are to access. Only variables +enumerated in the datanames property are eligible for use +in modules.

+

Note that specifying datanames in teal_data +is optional; if the property is empty, all objects are considered +eligible. Likewise, the datanames argument in the module +call defaults to "all", which means that module will +attempt to access all eligible variables in the teal_data +object.

+

For a detailed explanation of datanames, see this +teal.data vignette.

+

(back to General Data)

+
+
+
+join_keys +
+

Using relational data requires specifying joining keys for each pair +of datasets. Primary keys are unique row identifiers in individual +datasets and thus should be specified for each dataset. Foreign keys +describe mapping of variables between datasets. Joining keys are stored +in the join_keys property, which can be set when creating a +teal_data object, using the join_keys +argument, or using the join_keys function.

+
+ds1 <- data.frame(
+  id = seq(1, 10),
+  group = rep(c("A", "B"), each = 5)
+)
+ds2 <- data.frame(
+  group = c("A", "B"),
+  condition = c("condition1", "condition2")
+)
+keys <- join_keys(
+  join_key("DS1", keys = "id"),
+  join_key("DS2", keys = "group"),
+  join_key("DS1", "DS2", keys = c("group" = "group"))
+)
+data_relational1 <- teal_data(DS1 = ds1, DS2 = ds2, join_keys = keys)
+data_relational2 <- teal_data(DS1 = ds1, DS2 = ds2)
+join_keys(data_relational2) <- keys
+

For a detailed explanation of join keys, see this +teal.data vignette.

+

(back to ADaM Data)

+
+
+
+verified +
+

teal_data allows for tracking code from data creation +through data filtering through data analysis so that the whole process +can be reproduced. The verified property designates whether +or not reproducibility has been confirmed. teal_data +objects that are created empty and only modified by evaluating code +within them are considered verified by default. Those created with data +objects alone or with data objects and code are not verified by default, +but can become verified by running the verify function.

+
+data_with_code
+#> ✅︎ verified teal_data object
+#> <environment: 0x55914df04e30> [L]
+#> Parent: <environment: package:teal>
+#> Bindings:
+#> • not_a_dataset: <chr> [L]
+#> • cars: <df[,11]> [L]
+#> • iris: <df[,5]> [L]
+
+data_with_objects_and_code <- teal_data(iris = iris, cars = mtcars, code = expression(iris <- iris, cars <- mtcars))
+data_with_objects_and_code
+#> ✖ unverified teal_data object
+#> <environment: 0x55914e3a9cd8> [L]
+#> Parent: <environment: package:teal>
+#> Bindings:
+#> • cars: <df[,11]> [L]
+#> • iris: <df[,5]> [L]
+
+data_with_objects_and_code_ver <- verify(data_with_objects_and_code)
+data_with_objects_and_code_ver
+#> ✅︎ verified teal_data object
+#> <environment: 0x55914e3a9cd8> [L]
+#> Parent: <environment: package:teal>
+#> Bindings:
+#> • cars: <df[,11]> [L]
+#> • iris: <df[,5]> [L]
+

For a detailed explanation of verification, see this +teal.data vignette.

+

(back to Reproducible Data)

+


+
+
+
+

Further reading +

+

For a complete guide to the teal_data class, please +refer to the teal.data +package.

+
+
+
+ + + + +
+ + + + + + + diff --git a/latest-tag/articles/including-general-data-in-teal.html b/latest-tag/articles/including-general-data-in-teal.html deleted file mode 100644 index 550a28f2b7..0000000000 --- a/latest-tag/articles/including-general-data-in-teal.html +++ /dev/null @@ -1,210 +0,0 @@ - - - - - - - - -Input general data in a teal application • teal - - - - - - - - - - - Skip to contents - - -
- - - - -
-
-

Input general data in a teal application

-

NEST -CoreDev

- -

2022-04-20

- - -
including-general-data-in-teal.Rmd
-
- - - -
-

Introduction -

-

teal applications are not restricted to -CDISC-standard data. Although many teal modules included -with NEST are designed for CDISC data, those -in the library teal.modules.general have been designed to -work with non-relational data.

-

For example this application uses the standard iris and -mtcars datasets:

-
-library(teal)
-
-app <- init(
-  data = teal_data(
-    dataset("IRIS", iris, code = "IRIS <- iris"),
-    dataset("CARS", mtcars, code = "CARS <- mtcars")
-  ),
-  modules = example_module()
-)
-
-if (interactive()) {
-  shinyApp(app$ui, app$server)
-}
-

For more information, see documentation in -teal.data.

-
-
-

Delayed Data Loading (DDL) -

-

To learn more about DDL, visit -vignette("delayed-data-loading", package = "teal.data"). -All the features of DDL are available for general -datasets:

-
-library(teal)
-
-person_generator <- function() {
-  return(
-    data.frame(
-      ID = factor(1:8),
-      AGE = c(40, 23, 56, 11, 17, 71, 23, 56)
-    )
-  )
-}
-
-pet_generator <- function() {
-  return(
-    data.frame(
-      ID = factor(1:10),
-      TYPE = rep(c("CAT", "DOG"), 5),
-      COLOR = c("GINGER", rep("BROWN", 5), rep("BLACK", 4)),
-      PERSON_ID = factor(c(5, 4, 3, 3, 3, 1, 8, 1, 2, 2))
-    )
-  )
-}
-
-
-app <- init(
-  data = teal_data(
-    fun_dataset_connector("PERSON", fun = person_generator, keys = "ID") %>%
-      mutate_dataset("PERSON$SEX <- rep(c('M', 'F'), 4)"),
-    fun_dataset_connector("PETS", fun = pet_generator, keys = "ID")
-  ) %>%
-    mutate_join_keys("PERSON", "PETS", c("ID" = "PERSON_ID")),
-  modules = example_module()
-)
-
-if (interactive()) {
-  shinyApp(app$ui, app$server)
-}
-

For more information about preprocessing, reproducibility, -relationships between datasets and DDL, please refer to the -teal.data -package.

-
-
-
- - - - -
- - - - - - - diff --git a/latest-tag/articles/including-mae-data-in-teal.html b/latest-tag/articles/including-mae-data-in-teal.html deleted file mode 100644 index 1fcf42b923..0000000000 --- a/latest-tag/articles/including-mae-data-in-teal.html +++ /dev/null @@ -1,177 +0,0 @@ - - - - - - - - -Input `MultiAssayExperiment` data in a teal application • teal - - - - - - - - - - - Skip to contents - - -
- - - - -
-
-

Input `MultiAssayExperiment` data in a teal application

-

NEST -CoreDev

- -

2022-04-20

- - -
including-mae-data-in-teal.Rmd
-
- - - -
-

-MultiAssayExperiment data -

-

MultiAssayExperiment offers a data structure for -representing and analyzing multi-omics experiments: a biological -analysis approach utilizing multiple types of observations, such as DNA -mutations and abundance of RNA and proteins, in the same biological -specimens.

-

You can read more about MultiAssayExperiment data here.

-
-
-

Example application -

-

The example below represents an application including -MultiAssayExperiment data.

-
-library(teal)
-utils::data(miniACC, package = "MultiAssayExperiment")
-
-mae_d <- dataset("MAE", miniACC, metadata = list(type = "example"))
-
-app <- init(
-  data = teal_data(mae_d),
-  modules = example_module()
-)
-
-if (interactive()) {
-  shinyApp(app$ui, app$server)
-}
-

The filter panel supports MAE data out of the box, but -teal itself does not guarantee that any module will work -with MAE data the same way it works with other types of -data (e.g. ADaM) because MAE has a unique -structure that needs to be considered when developing a module. The -package teal.modules.hermes -has been specifically developed for the analysis of MAE -data.

-

For more information about preprocessing, reproducibility, -relationships between datasets and DDL, please refer to the -teal.data -package.

-
-
-
- - - - -
- - - - - - - diff --git a/latest-tag/articles/index.html b/latest-tag/articles/index.html index a44135ab0f..37d590b307 100644 --- a/latest-tag/articles/index.html +++ b/latest-tag/articles/index.html @@ -1,5 +1,5 @@ -Articles • tealArticles • teal @@ -10,7 +10,7 @@ teal - 0.14.0 + 0.15.0
part of NESTpharmaverse
- - - - - -
- - - - -
-
-

Preprocessing data

-

NEST -CoreDev

- -

2022-07-28

- - -
preprocessing-data.Rmd
-
- - - -
-

Usage in teal apps -

-

In this vignette, we will show how to use preprocessing in a -teal app. The basics of preprocessing data have been -discussed in teal.data here.

-

In a teal app, providing the code in a copy-paste style -is cumbersome and can lead to an out-of-sync situation where the code -does not represent the preprocessing code anymore. We therefore use the -get_code function to extract the preprocessing code from -the app.R file. The get_code function requires -# tags to indicate which lines of code in -app.R need be included in the preprocessing code. -get_code understands the following tags:

-
    -
  • Enclosing preprocessing code between #code> -#<code determines the start and end of preprocessing. -Only one start and one end is allowed. If start or end are not specified -then preprocessing starts at the beginning of the file and ends at the -end respectively.
    • -
  • -#nocode at the end of the line excludes this line from -preprocessing.
    • -
  • Lines enclosed within #nocode> -#<nocode are excluded from preprocessing.
    • -
-

Further, the get_code function has the following -arguments that might be useful:

-
    -
  • -exclude_comments = TRUE removes comments from -preprocessing code.
    • -
  • -read_sources = TRUE means that code from sourced file -will be included instead of source() call.
    • -
-

To complete the above example try the code below (NOTE: make sure to save the code in a -file called app.R):

-
-# Code needs modification before it can be run:
-#     - save as app.R
-# for the purpose of example save the file to current directory
-library(teal)
-
-# code>
-new_iris <- transform(iris, id = seq_len(nrow(iris)))
-# <code
-
-app <- init(
-  data = teal_data(dataset("new_iris", new_iris), code = get_code(file = "app.R")),
-  modules = example_module()
-)
-
-shinyApp(app$ui, app$server)
-

Also try the following more advanced usage of -get_code:

-
-# Code needs modification before it can be run:
-#     - save as app.R
-library(teal)
-
-# code>
-# data import
-new_iris <- transform(iris, id = seq_len(nrow(iris)))
-
-excluded_obj1 <- 1:10 # nocode
-
-# nocode>
-excluded_obj2 <- 1:10
-# <nocode
-
-included_obj <- 1:10
-
-# <code
-
-x <- init(
-  data = cdisc_data(cdisc_dataset("ADSL", adsl),
-    code = get_code("app.R", exclude_comments = TRUE, read_sources = TRUE),
-    check = TRUE
-  ),
-  modules = example_module(),
-  header = "Simple app with preprocessing",
-  footer = tags$p(class = "text-muted", "Source: agile-R website")
-)
-
-shinyApp(x$ui, x$server)
-

If you set check = TRUE in cdisc_data then -the data provided to the application is checked against the data -obtained by evaluating the code in an isolated environment. -If the datasets do not match then cdisc_data returns an -error.

-

cdisc_data also analyzes the arguments passed to it. -Note that additional transformation within cdisc_data call -can break reproducibility and is not allowed, e.g. developers shouldn’t -do an operation like ADSL = mutate(ADSL, a = 1) inside -cdisc_data.

-
-
-
- - - - -
- - - - - - - diff --git a/latest-tag/articles/teal-options.html b/latest-tag/articles/teal-options.html index a261b66815..4da23d4e91 100644 --- a/latest-tag/articles/teal-options.html +++ b/latest-tag/articles/teal-options.html @@ -6,12 +6,12 @@ -Modifying a teal application with R options • teal +Modifying a teal Application With R Options • teal - - + + - + Authors and Citation • tealAuthors and Citation • teal @@ -10,7 +10,7 @@ teal - 0.14.0 + 0.15.0
part of NESTpharmaverse