% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/seqwrap.R
\name{seqwrap}
\alias{seqwrap}
\title{A flexible upper-level wrapper for iterative modelling using any available
fitting algorithm}
\usage{
seqwrap(
  y = NULL,
  modelfun = NULL,
  arguments = NULL,
  data = NULL,
  metadata = NULL,
  samplename = NULL,
  additional_vars = NULL,
  summary_fun = NULL,
  eval_fun = NULL,
  exported = list(),
  return_models = TRUE,
  save_models = FALSE,
  model_path = NULL,
  subset = NULL,
  cores = 1,
  verbose = TRUE
)
}
\arguments{
\item{y, }{An swcontainer object created with seqwrap_compose, a named list
or a DGEList object.}

\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{metadata}{A data frame with sample names (corresponding to column
names in the target matrix)
and design variables.}

\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{return_models}{Logical, should models be returned as part of the
output? Save models during development on subsets of the data.
If used on large data sets, this will result in large memory usage.}

\item{save_models}{Logical, should models be saved? Models may be saved
on disk to save working memory.}

\item{model_path}{A character. The path to saved models.}

\item{subset}{A sequence, random samples or integers to indicate which
rows to keep in data. This is useful if you want to test the model in a
subset of targets. If left to the default (NULL), all rows will be used.}

\item{cores}{An integer indicating the number of cores to be used in parallel
computations. If NULL, a sequential for loop is used. If "max", all
available cores are used.}

\item{verbose}{Logical, should the function print diagnostics after checking
the data container?}
}
\value{
A nested list with three upper levels slots: models, a list of
fitted objects; summaries, a list of summaries created from the summary_fun
function; evaluations, a list of diagnostics created from eval_fun.
}
\description{
A flexible upper-level wrapper for iterative modelling using any available
fitting algorithm
}
\details{
This function provides a flexible wrapper to fit, summarize and
evaluate statistical models fitted to high dimensional omics-type data.
Models are fitted and passed to user defined functions to summarize and
evaluate models.
}
\examples{
library(seqwrap)

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

# Simulate n targets
dat <- simcounts(n_genes = 10000)

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

# Prepare library size for use as offset
metadata$ln_libsize <- log(colSums(counts[,-1]))


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

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

# Run seqwrap using the container on a subset of targets
results <- seqwrap(container,
                   subset = 1:5,
                   cores = 1)


# Summarise results only contains the subset
summaries <- seqwrap_summarise(results)
}

}
