% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/seqwrap.R
\name{seqwrap_compose}
\alias{seqwrap_compose}
\title{Compose a swcontainer object for use in the seqwrap function.}
\usage{
seqwrap_compose(
  x = NULL,
  modelfun,
  arguments,
  data,
  rownames = FALSE,
  metadata,
  targetdata = NULL,
  samplename = "seq_sample_id",
  additional_vars = NULL,
  summary_fun = NULL,
  eval_fun = NULL,
  exported = list(),
  update = list()
)
}
\arguments{
\item{x}{An optional named list or DGEList object (DESeqDataSet not yet
implemented).}

\item{modelfun}{A model fitting function like stats::lm,
glmmTMB::glmmTMB or lme4::lmer}

\item{arguments}{An alist or list of arguments to be passed to the fitting
function, this should not contain data. Note that the formula must have
y as the dependent variable.}

\item{data}{A data frame or a list of data frames with targets (e.g. genes,
transcripts) as rows and sample names as columns.
If rownames = FALSE (default), each data frame should have target
identifications as the first column in the data frame(s). If rownames = TRUE
row names will be converted to target identifications. If data is provided as
a list, each element of the list should be named. The corresponding names
be available as variables for the fitting function.}

\item{rownames}{should row names in data be used as target identifications?
Defaults to FALSE.}

\item{metadata}{A data frame with sample names (corresponding to column
names in the target matrix)
and design variables.}

\item{targetdata}{A data frame or a list with target-wise values
(e.g. dispersion or start values) for each target. This data is made
available for the model fitting function and can be used to specify target
specific data in each iteration of seqwrap. When a data frame is provided
each row corresponds to the target specific value. When a list is provided,
each column of the data frame is available and can be called by name.}

\item{samplename}{A character value indicating the variable by which
metadata can merge with the target data. This defaults to "seq_sample_id"
as this is used in the trainomeMetaData package.}

\item{additional_vars}{A vector of additional variables that is contained
in the metadata data set that is needed to fit the model. By default the
metadata is reduced to variables contained in the slots
formula/model/fixed/random in additional arguments.
More variables may be needed for offsets, weights etc.}

\item{summary_fun}{A custom (user-created) function for
evaluating/summarizing models. If NULL, a list of fitted models are returned}

\item{eval_fun}{A custom (user-created) function for model
diagnostics/evaluation. If NULL, no evaluation/diagnostics of models are
returned}

\item{exported}{A list of functions, values etc. to be passed to
summary_fun and eval_fun. This list must contain any functions that
should be used in model summarise or evaluations.}

\item{update}{A list of named parameters to update a swcontainer object.}
}
\value{
A swcontainer object for direct use in seqwrap.
}
\description{
This function makes it possible to compose and  run checks on combined
data sets (meta data and target data) and fitting functions to avoid issues
in iterative modelling. See examples and vignettes for details.
}
\examples{
# Load packages and prepare data for examples -------------------------------

library(seqwrap)

if (requireNamespace("glmmTMB", quietly = TRUE)) {
library(glmmTMB)

dat <- simcounts2()

# Save simulated data as separate objects
counts <- dat$counts
metadata <- dat$metadata

# Prepare library size for use as offset
metadata$ln_libsize <- log(metadata$library_size)


# A mixed effects negative binomial model of RNA-seq counts -----------------

# Populate the seqwrap container
container <- seqwrap_compose(
  modelfun = glmmTMB::glmmTMB,
  arguments = list(
    formula = y ~ time * condition + (1|id) + offset(ln_libsize),
    family = glmmTMB::nbinom2()
  ),
  data = counts,
  metadata = metadata,
  samplename = "seq_sample_id"
)

# Run seqwrap using the container
results <- seqwrap(container,
                   cores = 1)




# Summarise results
summaries <- seqwrap_summarise(results)


# Including target-specific data --------------------------------------------

# Target specific data can be supplied to seqwrap_compose to enable, e.g.,
# the use of priors for empirical Bayes shrinkage. In this example we are
# setting a dummy-prior on the `condition` parameter and target-specific
# prior on the dispersion parameter.

fixef_priors <- data.frame(
  prior = "normal(0, 1)",
  class = "fixef",
  coef = "conditionB"
)

dips_priors <- data.frame(
  prior = c(
    "normal(0.5, 0.25)",
    "normal(1, 0.25)"),
  class = "fixef_disp",
  coef = 1
)


# Combine information in target-specific list
prior_list <- list()
for(i in 1:2) {

  prior_list[[i]] <- rbind(
    fixef_priors,
    dips_priors[i,]
  )


}



container <- seqwrap_compose(
  modelfun = glmmTMB::glmmTMB,
  # NOTE: The use of `alist` prevents evaluation of list components
  arguments = alist(
    formula = y ~ time * condition + (1|id) + offset(ln_libsize),
    family = glmmTMB::nbinom2(),
    priors = data.frame(
      prior = prior,
      class = class,
      coef = coef
    )
  ),
  data = counts,
  metadata = metadata,
  targetdata = prior_list,
  samplename = "seq_sample_id"
)

# Run seqwrap using the container
results_prior <- seqwrap(container,
                         # Return models to confirm use of prior information
                         # The use of prior information is not recommended
                         return_models = TRUE,
                         cores = 1)

# Confirm prior information
summary(results_prior@models[[1]])
# Compare to naive model
summary(results@models[[1]])
}

}
