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.