R: Create a study

createStudy {OmicNavigator}

R Documentation

Create a study

Description

Create a new OmicNavigator study.

Usage

createStudy(
  name,
  description = name,
  samples = list(),
  features = list(),
  models = list(),
  assays = list(),
  tests = list(),
  annotations = list(),
  results = list(),
  enrichments = list(),
  metaFeatures = list(),
  plots = list(),
  mapping = list(),
  barcodes = list(),
  reports = list(),
  resultsLinkouts = list(),
  enrichmentsLinkouts = list(),
  metaFeaturesLinkouts = list(),
  version = NULL,
  maintainer = NULL,
  maintainerEmail = NULL,
  studyMeta = list()
)

Arguments

`name`	Name of the study
`description`	Description of the study
`samples`	The metadata variables that describe the samples in the study. The input object is a named list of data frames (one per model). The first column of each data frame is used as the sampleID, so it must contain unique values. To share a data frame across multiple models, use the modelID "default".
`features`	The metadata variables that describe the features in the study. The input object is a list of data frames (one per model). The first column of each data frame is used as the featureID, so it must contain unique values. To share a data frame across multiple models, use the modelID "default". All columns will be coerced to character strings.
`models`	The models analyzed in the study. The input is a named list. The names correspond to the names of the models. The elements correspond to the descriptions of the models. Alternatively, instead of a single character string, you can provide a list of metadata fields about each model. The field "description" will be used to derive the tooltip displayed in the app.
`assays`	The assays from the study. The input object is a list of data frames (one per model). The row names should correspond to the featureIDs (`addFeatures`). The column names should correspond to the sampleIDs (`addSamples`). The data frame should only contain numeric values. To share a data frame across multiple models, use the modelID "default".
`tests`	The tests from the study. The input object is a list of lists. Each element of the top-level list is a model. The names should be the modelIDs. For each modelID, each element of the nested list is a test. The names should be the testIDs. The value should be a single character string describing the testID. To share tests across multiple models, use the modelID "default". Instead of a single character string, you can provide a list of metadata fields about each test. The field "description" will be used to derive the tooltip displayed in the app.
`annotations`	The annotations used for the enrichment analyses. The input is a nested list. The top-level list contains one entry per annotation database, e.g. reactome. The names correspond to the name of each annotation database. Each of these elements should be a list that contains more information about each annotation database. Specifically the sublist should contain 1) `description`, a character vector that describes the resource, 2) `featureID`, the name of the column in the features table that was used for the enrichment analysis, and 3) `terms`, a list of annotation terms. The names of `terms` sublist correspond to the name of the annotation terms. Each of the annotation terms should be a character vector of featureIDs.
`results`	The inference results from each model. The input is a nested named list. The names of the list correspond to the model names. Each element in the list should be a list of data frames with inference results, one for each test. In each data frame, the featureID must be in the first column, and all other columns must be numeric.
`enrichments`	The enrichment results from each model. The input is a nested named list. The names of the list correspond to the model names. Each list element should be a list of the annotation databases tested (`addAnnotations`). The names of the list correspond to the annotation databases. Each list element should be another list of tests (`addTests`). The names correspond to the tests performed. Each of these elements should be a data frame with enrichment results. Each table must contain the following columns: "termID", "description", "nominal" (the nominal statistics), and "adjusted" (the statistics after adjusting for multiple testing). Any additional columns are ignored.
`metaFeatures`	The metadata variables that describe the meta-features in the study. The input object is a list of data frames (one per model). The first column of each data frame is used as the featureID, so it must contain the same IDs as the corresponding features data frame (`addFeatures`). To share a data frame across multiple models, use the modelID "default". All columns will be coerced to character strings.
`plots`	Custom plotting functions for the study. The input object is a nested list. The first list corresponds to the modelID(s). The second list corresponds to the name(s) of the function(s) defined in the current R session. The third list provides metadata to describe each plot. The only required metadata element is `displayName`, which controls how the plot will be named in the app. You are encouraged to also specify the `plotType`, e.g. `"singleFeature"`, `"multiFeature"`, `"multiTest"`, `"multiModel"`. PlotType accepts vector of entries, whenever applicable, e.g., plotType = c(`"multiFeature"`, `"multiTest"`). If you do not specify the `plotType`, the plot will be assumed to be `"singleFeature"` and `"singleTest"`. Optionally, if the plotting function requires external packages, these can be defined in the element `packages`. To share plots across multiple models, use the modelID "default". To add a plotting function that returns an interactive plotly plot, add "plotly" to the `plotType` vector.
`mapping`	Feature IDs from models. The input object is a list of named data frames. For each data frame, column names indicate model names while rows indicate featureIDs per model. Features with same index position across columns are treated as mapped across models. For each model, feature IDs must match feature IDs available in the results object of the respective model. 1:N relationships are allowed. Mapping list elements are required to be named as 'default' or after a model name as provided in addModels(). If a single data frame is provided, this list element is recommended to be named 'default'. For multiple list elements, each with its own data frame, list elements should be named after model name(s) (a single element may still be named 'default'). In that case, when navigating in ON front-end (FE), mapping element related to the selected model in the FE will be used in multimodel plots. If a selected model in FE does not have a corresponding mapping list element, it may still use the mapping list element called 'default' if this is available. E.g., if in a study there are models "transcriptomics" and "proteomics" and the user wants to create a plot based on data from both, a mapping list should be provided with addMapping(). In this case, the mapping list element may be named 'default'. This should contain a data frame with column names 'transcriptomics' and 'proteomics', where feature IDs that map across models are found in the same row.
`barcodes`	The metadata variables that describe the barcode plot. The input object is a list of lists (one per model). Each sublist must contain the element `statistic`, which is the column name in the results table to use to construct the barcode plot. Each sublist may additionally contain any of the following optional elements: 1) `absolute` - Should the statistic be converted to its absolute value (default is `TRUE`). 2) `logFoldChange` - The column name in the results table that contains the log fold change values. 3) `labelStat` - The x-axis label to describe the statistic. 4) `labelLow` - The left-side label to describe low values of the statistic. 5) `labelHigh` - The right-side label to describe high values of the statistic. 6) `featureDisplay` - The feature variable to use to label the barcode plot on hover. To share metadata across multiple models, use the modelID "default".
`reports`	The analysis report(s) that explain how the study results were generated. The input object is a list of character vectors (one per model). Each element should be either a URL or a path to a file on your computer. If it is a path to a file, this file will be included in the exported study package. To share a report across multiple models, use the modelID "default".
`resultsLinkouts`	The URL patterns that describe linkouts to external resources (see Details below). The input object is a nested named list. The names of the list correspond to the model names. Each element of the list is a named list of character vectors. The names of this nested list must correspond to the column names of the matching features table. To share linkouts across multiple models, use the modelID "default".
`enrichmentsLinkouts`	The URL patterns that describe linkouts to external resources (see Details below). The input object is a named list. The names of the list correspond to the annotation names. Each element of the list is a character vector of linkouts for that annotationID.
`metaFeaturesLinkouts`	The URL patterns that describe linkouts to external resources (see Details below). The input object is a nested named list. The names of the list correspond to the model names. Each element of the list is a named list of character vectors. The names of this nested list must correspond to the column names of the matching metaFeatures table (`addMetaFeatures`). To share linkouts across multiple models, use the modelID "default".
`version`	(Optional) Include a version number to track the updates to your study package. If you export the study to a package, the version is used as the package version.
`maintainer`	(Optional) Include the name of the study package's maintainer
`maintainerEmail`	(Optional) Include the email of the study package's maintainer
`studyMeta`	(Optional) Define metadata about your study. The input is a list of key:value pairs. See below for more details.

Details

You can add metadata to describe your study by passing a named list to to the argument studyMeta. The names of the list cannot contain spaces or colons, and they can't start with # or -. The values of each list should be a single value. Also, your metadata fields cannot use any of the reserved fields for R's DESCRIPTION file.

Value

Returns a new OmicNavigator study object, which is a named nested list with class onStudy

Examples


study <- createStudy(name = "ABC",
                     description = "An analysis of ABC")

# Define a version and study metadata
study <- createStudy(name = "ABC",
                     description = "An analysis of ABC",
                     version = "0.1.0",
                     maintainer = "My Name",
                     maintainerEmail = "me@email.com",
                     studyMeta = list(department = "immunology",
                                      organism = "Mus musculus"))

[Package OmicNavigator version 1.13.13 Index]