MPRAnalyze

https://github.com/yoseflab/mpranalyze
Admin
MPRAnalyze provides a statistical framework for the analysis of data generated by Massively Parallel...
Tokens:21,445
Snippets:171
Trust Score:9.7
Update:6 days ago
Show doc for...
Tokens:
Raw
### Example: Simulate data and get DNA fits with getFits_DNA

Source: https://github.com/yoseflab/mpranalyze/blob/master/man/getFits_DNA.Rd

Shows a complete workflow: simulate MPRA data, create an MpraObject, estimate depth factors, run quantification analysis, and extract DNA fits. The example uses default arguments for getFits_DNA.

```R
data <- simulateMPRA(tr = rep(2,5), nbatch=2, nbc=15)
obj <- MpraObject(dnaCounts = data$obs.dna, 
                  rnaCounts = data$obs.rna, 
                  colAnnot = data$annot)
obj <- estimateDepthFactors(obj, lib.factor = "batch", which.lib = "both")
obj <- analyzeQuantification(obj, dnaDesign = ~ batch + barcode, 
                              rnaDesign = ~1)
dna.fits <- getFits_DNA(obj)
```

--------------------------------

### Example: Simulate data, create MpraObject, estimate depth factors, analyze, and test coefficient

Source: https://github.com/yoseflab/mpranalyze/blob/master/man/testCoefficient.Rd

Complete workflow for testing a coefficient. Requires fit.se = TRUE in analyzeComparative for coefficient-based testing to work. The example simulates data, creates an MpraObject, estimates depth factors, runs comparative analysis, and calls testCoefficient with factor 'condition' and contrast 'contrast'.

```R
data <- simulateMPRA(tr = rep(2,5), da=c(rep(0,2), rep(1,3)), 
                     nbatch=2, nbc=15)
obj <- MpraObject(dnaCounts = data$obs.dna, 
                  rnaCounts = data$obs.rna, 
                  colAnnot = data$annot)
obj <- estimateDepthFactors(obj, lib.factor = "batch", which.lib = "both")

## fit.se must be TRUE for coefficient based testing to work
obj <- analyzeComparative(obj, dnaDesign = ~ batch + barcode + condition, 
                              rnaDesign = ~ condition, fit.se = TRUE)
results <- testCoefficient(obj, "condition", "contrast")
```

--------------------------------

### Install MPRAnalyze from GitHub using devtools

Source: https://github.com/yoseflab/mpranalyze/blob/master/README.md

Use this command to install the newest version of MPRAnalyze directly from GitHub. Requires the devtools package to be installed.

```r
library(devtools)
install_github("YosefLab/MPRAnalyze")
```

--------------------------------

### Initialize MpraObject with SummarizedExperiment objects

Source: https://github.com/yoseflab/mpranalyze/blob/master/man/MpraObject.Rd

Alternative initialization using SummarizedExperiment objects for DNA and RNA counts. This example is wrapped in \dontrun and is not executed during package checks.

```R
se.DNA <- SummarizedExperiment(list(data$obs.dna), colData=data$annot)
se.RNA <- SummarizedExperiment(list(data$obs.rna), colData=data$annot)
obj <- MpraObject(dnaCounts = se.DNA, rnaCounts = rna.se, 
                  controls = as.integer(c(1,2,4)))
```

--------------------------------

### getAlpha example: simulate data, fit model, and extract alpha

Source: https://github.com/yoseflab/mpranalyze/blob/master/man/getAlpha.Rd

This example shows a complete workflow: simulate MPRA data, create an MpraObject, estimate depth factors, run a comparative analysis, and then extract the transcription rate for the 'condition' factor using getAlpha with by.factor='condition'. The example assumes the MpraObject has been fitted with analyzeComparative.

```R
data <- simulateMPRA(tr = rep(2,10), da=c(rep(0,5), rep(1,5)), 
                     nbatch=2, nbc=15)
obj <- MpraObject(dnaCounts = data$obs.dna, 
                  rnaCounts = data$obs.rna, 
                  colAnnot = data$annot)
obj <- estimateDepthFactors(obj, lib.factor = "batch", which.lib = "both")
obj <- analyzeComparative(obj, dnaDesign = ~ batch + barcode + condition, 
                              rnaDesign = ~ condition, reducedDesign = ~ 1)
## get alpha estimate for the two conditions
alpha <- getAlpha(obj, by.factor="condition")
```

--------------------------------

### Install MPRAnalyze from Bioconductor using BiocManager

Source: https://github.com/yoseflab/mpranalyze/blob/master/README.md

Use this command to install the released version of MPRAnalyze from Bioconductor. Requires the BiocManager package to be installed.

```r
BiocManager::install("MPRAnalyze")
```

--------------------------------

### Set model to ln.ln and analyze quantification

Source: https://github.com/yoseflab/mpranalyze/blob/master/man/setModel.Rd

Example workflow from the documentation: simulate data, create an MpraObject, estimate depth factors, set the model to 'ln.ln' using setModel, then run analyzeQuantification. Use setModel before fitting the model to select an alternative distributional model.

```R
data <- simulateMPRA(tr = rep(2,10), da=NULL, nbatch=2, nbc=20)
obj <- MpraObject(dnaCounts = data$obs.dna, 
                  rnaCounts = data$obs.rna, 
                  colAnnot = data$annot)
obj <- estimateDepthFactors(obj, lib.factor = "batch", which.lib = "both")
obj <- setModel(obj, "ln.ln")
obj <- analyzeQuantification(obj, dnaDesign = ~ batch + barcode, 
                              rnaDesign = ~1)
```

--------------------------------

### Load and examine MPRA data with MPRAnalyze

Source: https://github.com/yoseflab/mpranalyze/blob/master/vignettes/vignette.Rmd

Loads the example dataset 'ChrEpi' and displays the column annotations summary and first rows. This is the first step before creating an MpraObject.

```r
library(MPRAnalyze)
data("ChrEpi")
summary(ce.colAnnot)
head(ce.colAnnot)
```

--------------------------------

### getFits_RNA example: simulate data, fit model, and extract RNA fits

Source: https://github.com/yoseflab/mpranalyze/blob/master/man/getFits_RNA.Rd

Shows the full workflow for obtaining RNA fits: simulate MPRA data, create an MpraObject, estimate depth factors by batch, run analyzeQuantification with DNA and RNA designs, then call getFits_RNA to extract the expected RNA values.

```r
data <- simulateMPRA(tr = rep(2,5), nbatch=2, nbc=15)
obj <- MpraObject(dnaCounts = data$obs.dna, 
                  rnaCounts = data$obs.rna, 
                  colAnnot = data$annot)
obj <- estimateDepthFactors(obj, lib.factor = "batch", which.lib = "both")
obj <- analyzeQuantification(obj, dnaDesign = ~ batch + barcode, 
                              rnaDesign = ~1)
rna.fits <- getFits_RNA(obj)
```

--------------------------------

### Extract distribution parameters from an MpraObject using getDistrParam_DNA and getDistrParam_RNA

Source: https://github.com/yoseflab/mpranalyze/blob/master/man/getDistrParam.Rd

Shows a complete workflow from simulating data to extracting distribution parameters for the first enhancer. The example creates an MpraObject from simulated DNA and RNA counts, estimates depth factors by batch, runs quantification analysis, and then calls getDistrParam_DNA and getDistrParam_RNA on enhancer 1. The resulting parameters are stored in dist.params.dna and dist.params.rna.

```R
data <- simulateMPRA(tr = rep(2,5), nbatch=2, nbc=15)
obj <- MpraObject(dnaCounts = data$obs.dna, 
                  rnaCounts = data$obs.rna, 
                  colAnnot = data$annot)
obj <- estimateDepthFactors(obj, lib.factor = "batch", which.lib = "both")
obj <- analyzeQuantification(obj, dnaDesign = ~ batch + barcode, 
                              rnaDesign = ~1)
## get distributional parameters of the first enhancer:
dist.params.dna <- getDistrParam_DNA(obj, 1)
dist.params.rna <- getDistrParam_RNA(obj, 1)
```

--------------------------------

### Extract alpha values with getAlpha and visualize

Source: https://github.com/yoseflab/mpranalyze/blob/master/vignettes/vignette.Rmd

Extracts transcription rate estimates (alpha values) from the fitted model using getAlpha, specifying by.factor = "condition" to get separate estimates per condition. Then visualizes the estimates with a boxplot.

```r
##extract alpha values from the fitted model
alpha <- getAlpha(obj, by.factor = "condition")

##visualize the estimates
boxplot(alpha)
```

--------------------------------

### Extract DNA and RNA model parameters from an MpraObject

Source: https://github.com/yoseflab/mpranalyze/blob/master/man/extractModelParameters.Rd

Simulates MPRA data, constructs an MpraObject, estimates depth factors, performs quantification analysis, and extracts model parameters for both DNA and RNA. The full model parameters are returned by default; set full=FALSE to get reduced model parameters for LRT-based analyses.

```R
data <- simulateMPRA(tr = rep(2,5), nbatch=2, nbc=15)
obj <- MpraObject(dnaCounts = data$obs.dna, 
                  rnaCounts = data$obs.rna, 
                  colAnnot = data$annot)
obj <- estimateDepthFactors(obj, lib.factor = "batch", which.lib = "both")
obj <- analyzeQuantification(obj, dnaDesign = ~ batch + barcode, 
                              rnaDesign = ~1)
model.params.dna <- getModelParameters_DNA(obj)
model.params.rna <- getModelParameters_RNA(obj)
```

--------------------------------

### Run LRT-based comparative analysis with analyzeComparative

Source: https://github.com/yoseflab/mpranalyze/blob/master/man/analyzeComparative.Rd

Simulates MPRA data, creates an MpraObject, estimates depth factors, and runs an LRT-based comparative analysis using a reduced design of ~ 1. This is the recommended approach.

```r
data <- simulateMPRA(tr = rep(2,5), da=c(rep(0,2), rep(1,3)), 
                     nbatch=2, nbc=15)
obj <- MpraObject(dnaCounts = data$obs.dna, 
                  rnaCounts = data$obs.rna, 
                  colAnnot = data$annot)
obj <- estimateDepthFactors(obj, lib.factor = "batch", which.lib = "both")
## run an LRT-based analysis, as recommnded:
obj <- analyzeComparative(obj, dnaDesign = ~ batch + barcode + condition, 
                              rnaDesign = ~ condition, reducedDesign = ~ 1)
```

--------------------------------

### simulateMPRA function signature with defaults

Source: https://github.com/yoseflab/mpranalyze/blob/master/man/simulateMPRA.Rd

Shows the default arguments for the simulateMPRA function. Use this to understand the default simulation parameters before customizing them.

```r
simulateMPRA(
  tr = rep(2, 100),
  da = NULL,
  dna.noise.sd = 0.2,
  rna.noise.sd = 0.3,
  dna.inter = 5,
  dna.inter.sd = 0.5,
  nbc = 100,
  coef.bc.sd = 0.5,
  nbatch = 3,
  coef.batch.sd = 0.5
)
```

--------------------------------

### Test enhancer activity with testEmpirical and visualize p-values

Source: https://github.com/yoseflab/mpranalyze/blob/master/vignettes/vignette.Rmd

Tests for enhancer activity using negative controls via testEmpirical, which provides empirical, z-score, and MAD-score p-values. The example tests episomal (MT) and chromosomal (WT) conditions, then visualizes the MAD-score p-value distributions with histograms, separating controls. The MAD-score p-values are recommended for robustness to outliers.

```r
## test 
res.epi <- testEmpirical(obj = obj, 
                               statistic = alpha$MT)
summary(res.epi)

res.chr <- testEmpirical(obj = obj,
                               statistic = alpha$WT)
par(mfrow=c(2,2))

hist(res.epi$pval.mad, main="episomal, all")
hist(res.epi$pval.mad[ce.control], main="episomal, controls")
hist(res.chr$pval.mad, main="chromosomal, all")
hist(res.chr$pval.mad[ce.control], main="chromosomal, controls")

par(mfrow=c(1,1))
```

--------------------------------

### Run coefficient-based comparative analysis with analyzeComparative

Source: https://github.com/yoseflab/mpranalyze/blob/master/man/analyzeComparative.Rd

Simulates MPRA data, creates an MpraObject, estimates depth factors, and runs a coefficient-based analysis by setting fit.se = TRUE to extract standard errors for coefficient-based testing.

```r
data <- simulateMPRA(tr = rep(2,5), da=c(rep(0,2), rep(1,3)), 
                     nbatch=2, nbc=15)
obj <- MpraObject(dnaCounts = data$obs.dna, 
                  rnaCounts = data$obs.rna, 
                  colAnnot = data$annot)
obj <- estimateDepthFactors(obj, lib.factor = "batch", which.lib = "both")
## alternatively, run a coefficient-based analysis:
obj <- analyzeComparative(obj, dnaDesign = ~ batch + barcode + condition, 
                              rnaDesign = ~ condition, fit.se = TRUE)
```

--------------------------------

### Basic testEmpirical usage

Source: https://github.com/yoseflab/mpranalyze/blob/master/man/testEmpirical.Rd

Simulates MPRA data, creates an MpraObject, estimates depth factors, performs quantification analysis, and runs testEmpirical with default settings.

```r
data <- simulateMPRA(tr = rep(2,10), da=NULL, nbatch=2, nbc=15)
obj <- MpraObject(dnaCounts = data$obs.dna, 
                  rnaCounts = data$obs.rna, 
                  colAnnot = data$annot)
obj <- estimateDepthFactors(obj, lib.factor = "batch", which.lib = "both")
obj <- analyzeQuantification(obj, dnaDesign = ~ batch + barcode, 
                              rnaDesign = ~1)
results <- testEmpirical(obj)
```

--------------------------------

### Initialize MpraObject with count matrices and controls

Source: https://github.com/yoseflab/mpranalyze/blob/master/man/MpraObject.Rd

Creates an MpraObject using observed DNA and RNA count matrices, column annotations, and a vector of control indices. The controls argument specifies non-active enhancers to use as controls.

```R
obj <- MpraObject(dnaCounts = data$obs.dna, 
                  rnaCounts = data$obs.rna, 
                  colAnnot = data$annot,
                  controls = as.integer(c(1,2,4)))
```

--------------------------------

### Run testLrt on simulated MpraObject

Source: https://github.com/yoseflab/mpranalyze/blob/master/man/testLrt.Rd

Simulates MPRA data, creates an MpraObject, estimates depth factors, performs comparative analysis with a reduced model, and runs the likelihood ratio test. Must be run after an LRT-based analysis.

```r
data <- simulateMPRA(tr = rep(2,5), da=c(rep(0,2), rep(1,3)), 
                     nbatch=2, nbc=15)
obj <- MpraObject(dnaCounts = data$obs.dna, 
                  rnaCounts = data$obs.rna, 
                  colAnnot = data$annot)
obj <- estimateDepthFactors(obj, lib.factor = "batch", which.lib = "both")
obj <- analyzeComparative(obj, dnaDesign = ~ batch + barcode + condition, 
                              rnaDesign = ~ condition, reducedDesign = ~ 1)
results <- testLrt(obj)
```

--------------------------------

### Run analyzeQuantification on simulated MPRA data

Source: https://github.com/yoseflab/mpranalyze/blob/master/man/analyzeQuantification.Rd

Simulates MPRA data with 10 sequences, 2 batches, and 15 barcodes per sequence. Creates an MpraObject, estimates depth factors using the batch library factor, then fits quantitative models with DNA design ~ batch + barcode and RNA design ~1.

```r
data <- simulateMPRA(tr = rep(2,10), nbatch=2, nbc=15)
obj <- MpraObject(dnaCounts = data$obs.dna, 
                  rnaCounts = data$obs.rna, 
                  colAnnot = data$annot)
obj <- estimateDepthFactors(obj, lib.factor = "batch", which.lib = "both")
obj <- analyzeQuantification(obj, dnaDesign = ~ batch + barcode, 
                              rnaDesign = ~1)
```

--------------------------------

### Run comparative analysis in scalable mode with mode='scale'

Source: https://github.com/yoseflab/mpranalyze/blob/master/vignettes/vignette.Rmd

Calls analyzeComparative with mode='scale' to use the scalable mode, which is faster but has reduced statistical power and does not support control-based correction. Requires matched DNA and RNA observations and does not need dnaDesign. The code then performs a likelihood ratio test and plots the log fold changes from the classic and scalable models.

```r
obj <- analyzeComparative(obj = obj, 
                          rnaDesign = ~ condition, 
                          reducedDesign = ~ 1, 
                          mode="scale")
res.scale <- testLrt(obj)
head(res.scale)
plot(res$logFC, res.scale$logFC)
```

--------------------------------

### Load ChrEpi dataset with data()

Source: https://github.com/yoseflab/mpranalyze/blob/master/man/ChrEpi.Rd

Loads the ChrEpi dataset into the R environment. This is the primary usage for accessing the sample MPRA data.

```R
data(ChrEpi)
```

--------------------------------

### MpraObject(dnaCounts, rnaCounts, dnaAnnot, rnaAnnot, colAnnot, controls, rowAnnot, BPPARAM)

Source: https://github.com/yoseflab/mpranalyze/blob/master/man/MpraObject.Rd

Creates an initialized MpraObject from DNA and RNA count matrices or SummarizedExperiment objects, along with optional annotations and control identifiers.

```APIDOC
## MpraObject(dnaCounts, rnaCounts, dnaAnnot, rnaAnnot, colAnnot, controls, rowAnnot, BPPARAM)

### Description
Creates an initialized MpraObject, the main object MPRAnalyze works with. It contains the input data, associated annotations, model parameters, and analysis results.

### Usage
```r
MpraObject(
  dnaCounts,
  rnaCounts,
  dnaAnnot = NULL,
  rnaAnnot = NULL,
  colAnnot = NULL,
  controls = NA_integer_,
  rowAnnot = NULL,
  BPPARAM = NULL
)
```

### Arguments
- **dnaCounts** (matrix or SummarizedExperiment) - Required - The DNA count matrix, or a SummarizedExperiment object containing the DNA Counts and column annotations for the DNA data. If the input is a SummarizedExperiment object, the dnaAnnot (or colAnnot) arguments will be ignored.
- **rnaCounts** (matrix or SummarizedExperiment) - Required - The RNA count matrix, or a SummarizedExperiment object containing the RNA Counts and column annotations for the RNA data. If the input is a SummarizedExperiment object, the rnaAnnot (or colAnnot) arguments will be ignored.
- **dnaAnnot** (data.frame) - Optional - Data.frame with the DNA column (sample) annotations.
- **rnaAnnot** (data.frame) - Optional - Data.frame with the RNA column (sample) annotations.
- **colAnnot** (data.frame) - Optional - If annotations for DNA and RNA are identical, they can be set at the same time using colAnnot instead of using both rnaAnnot and dnaAnnot.
- **controls** (character, logical, or numeric) - Optional - IDs of the rows in the matrices that correspond to negative control enhancers. These are used to establish the null for quantification purposes, and to correct systemic bias in comparative analyses. Can be a character vector (corresponding to rownames in the data matrices), logical or numeric indices.
- **rowAnnot** (data.frame) - Optional - A data.frame with the row (candidate enhancer) annotations. The names must match the row names in the DNA and RNA count matrices.
- **BPPARAM** (BiocParallel parameter) - Optional - A parallelization backend using the BiocParallel package.

### Value
An initialized MpraObject.

### Examples
```r
data <- simulateMPRA(tr = rep(2,10), da=c(rep(2,5), rep(2.5,5)), nbatch=2, nbc=20)
```
```

--------------------------------

### Simulate MPRA dataset with increasing transcription rates

Source: https://github.com/yoseflab/mpranalyze/blob/master/man/simulateMPRA.Rd

Simulates a dataset with gradually increasing true transcription rates from 2 to 3 in steps of 0.01, and no differential activity.

```r
# gradually increasing dataset
data <- simulateMPRA(tr = seq(2,3,0.01), da=NULL)
```

--------------------------------

### MpraObject(dnaCounts, rnaCounts, colAnnot, controls)

Source: https://github.com/yoseflab/mpranalyze/blob/master/man/MpraObject.Rd

Creates an MpraObject instance with DNA and RNA count matrices, column annotations, and control indices.

```APIDOC
## MpraObject(dnaCounts, rnaCounts, colAnnot, controls)

### Description
Creates an MpraObject instance with DNA and RNA count matrices, column annotations, and control indices.

### Method
Constructor

### Parameters
- **dnaCounts** (matrix or SummarizedExperiment) - Required - DNA count data.
- **rnaCounts** (matrix or SummarizedExperiment) - Required - RNA count data.
- **colAnnot** (data.frame) - Required - Column annotations for samples.
- **controls** (integer vector) - Required - Indices of non-active enhancers used as controls.

### Request Example
```r
obj <- MpraObject(dnaCounts = data$obs.dna, 
                  rnaCounts = data$obs.rna, 
                  colAnnot = data$annot,
                  controls = as.integer(c(1,2,4)))
```

### Response
#### Success Response
Returns an MpraObject instance.

```

--------------------------------

### setModel(obj, model)

Source: https://github.com/yoseflab/mpranalyze/blob/master/man/setModel.Rd

Sets the distributional model used for the MPRAnalyze object. Default is gamma.pois, which is recommended. Other supported models are ln.nb and ln.ln. Use this function before fitting the model.

```APIDOC
## setModel(obj, model)

### Description
Sets the distributional model used for the MPRAnalyze object. Default is gamma.pois, which is recommended. Other supported models are ln.nb and ln.ln. Use this function before fitting the model.

### Usage
setModel(obj, model)

### Parameters
- **obj** (MPRAnalyze object) - Required - The MPRAnalyze object.
- **model** (character) - Required - The identifier of the model to be used. Currently supported models: "ln.nb", "gamma.pois", "ln.ln".

### Return Value
The MPRAnalyze object with the model set for the given value.

### Example
```r
data <- simulateMPRA(tr = rep(2,10), da=NULL, nbatch=2, nbc=20)
obj <- MpraObject(dnaCounts = data$obs.dna, 
                  rnaCounts = data$obs.rna, 
                  colAnnot = data$annot)
obj <- estimateDepthFactors(obj, lib.factor = "batch", which.lib = "both")
obj <- setModel(obj, "ln.ln")
obj <- analyzeQuantification(obj, dnaDesign = ~ batch + barcode, 
                              rnaDesign = ~1)
```
```

--------------------------------

### Simulate single condition MPRA dataset

Source: https://github.com/yoseflab/mpranalyze/blob/master/man/simulateMPRA.Rd

Simulates a single-condition MPRA dataset with default parameters. The result is stored in the variable 'data'.

```r
# single condition
data <- simulateMPRA()
```

--------------------------------

### Fit quantification model with analyzeQuantification

Source: https://github.com/yoseflab/mpranalyze/blob/master/vignettes/vignette.Rmd

Fits the MPRAnalyze model for quantification analysis. The DNA model includes batch and condition, while the RNA model only includes condition, reflecting the paired experiment design where DNA factors are transferable to RNA.

```r
obj <- analyzeQuantification(obj = obj, 
                              dnaDesign = ~ batch + condition,
                              rnaDesign = ~ condition)
```

--------------------------------

### Simulate MPRA data with simulateMPRA

Source: https://github.com/yoseflab/mpranalyze/blob/master/man/MpraObject.Rd

Creates a simulated MPRA dataset with 10 elements, 2 batches, and 20 biological replicates per condition. The 'tr' argument sets the number of technical replicates (2 for each element) and 'da' sets the differential activity values (2 for the first 5 elements, 2.5 for the last 5).

```R
data <- simulateMPRA(tr = rep(2,10), da=c(rep(2,5), rep(2.5,5)), 
                     nbatch=2, nbc=20)
```

--------------------------------

### Fit comparative model with analyzeComparative

Source: https://github.com/yoseflab/mpranalyze/blob/master/vignettes/vignette.Rmd

Fits a comparative model using analyzeComparative, specifying the DNA design, RNA design, and a reduced design (intercept only) representing the null hypothesis of no differential activity between conditions.

```r
obj <- analyzeComparative(obj = obj, 
                           dnaDesign = ~ barcode + batch + condition, 
                           rnaDesign = ~ condition, 
                           reducedDesign = ~ 1)
```

--------------------------------

### getAlpha(obj, by.factor = NULL, full = TRUE)

Source: https://github.com/yoseflab/mpranalyze/blob/master/man/getAlpha.Rd

Returns the fitted transcription rate from an MpraObject. The by.factor argument allows extraction of rates for specific factor levels, and full controls whether the full or reduced model estimate is returned.

```APIDOC
## getAlpha(obj, by.factor = NULL, full = TRUE)

### Description
Returns the fitted value for the transcription rate from an MpraObject after model fitting. The function can return the baseline rate, rates for all model terms, or rates for a specific factor, and can optionally return the reduced model estimate.

### Usage
```r
getAlpha(obj, by.factor = NULL, full = TRUE)
```

### Arguments
- **obj** (MpraObject) - Required - The MpraObject to extract from, must be after model fitting.
- **by.factor** (character/NULL) - Optional - Determines which transcription rates to return. Options: NULL (default) returns only the intercept term (a single baseline rate for each enhancer); "all" returns the transcription rates for all values included in the model; a factor name (must be a factor included in the RNA annotations and the RNA design) returns the rates for all values of that factor.
- **full** (logical) - Optional - If TRUE (default), returns the rate of the full model; if FALSE, returns the rate of the reduced model (only applies if an LRT-based analysis was used).

### Value
Returns the estimate for transcription rate as fitted by the model.

### Examples
```r
data <- simulateMPRA(tr = rep(2,10), da=c(rep(0,5), rep(1,5)), 
                     nbatch=2, nbc=15)
obj <- MpraObject(dnaCounts = data$obs.dna, 
                  rnaCounts = data$obs.rna, 
                  colAnnot = data$annot)
obj <- estimateDepthFactors(obj, lib.factor = "batch", which.lib = "both")
obj <- analyzeComparative(obj, dnaDesign = ~ batch + barcode + condition, 
                              rnaDesign = ~ condition, reducedDesign = ~ 1)
## get alpha estimate for the two conditions
alpha <- getAlpha(obj, by.factor="condition")
```
```

--------------------------------

### analyzeComparative(obj, rnaDesign, dnaDesign = NULL, fit.se = FALSE, reducedDesign = NULL, correctControls = TRUE, verbose = TRUE, mode = "classic", BPPARAM = NULL)

Source: https://github.com/yoseflab/mpranalyze/blob/master/man/analyzeComparative.Rd

Runs a comparative analysis between conditions on an MpraObject. Supports likelihood-ratio testing via a reduced design or coefficient-based testing with standard errors. Optionally corrects for systemic bias using negative controls and can run in scalable mode.

```APIDOC
## analyzeComparative

### Description
Run a comparative analysis between conditions.

### Usage
```r
analyzeComparative(
  obj,
  rnaDesign,
  dnaDesign = NULL,
  fit.se = FALSE,
  reducedDesign = NULL,
  correctControls = TRUE,
  verbose = TRUE,
  mode = "classic",
  BPPARAM = NULL
)
```

### Arguments
- **obj** (MpraObject) - Required - The MpraObject.
- **rnaDesign** (formula) - Required - The design for the RNA model.
- **dnaDesign** (formula) - Optional - The design for the DNA model. Only terms that are matched with the RNA design should be included.
- **fit.se** (logical) - Optional - If TRUE, the standard errors of the coefficients are extracted from the model. These are necessary for computing coefficient-based testing, but make the model fitting slower. Default: FALSE.
- **reducedDesign** (formula) - Optional - The design for the reduced RNA model, for a likelihood-ratio testing scheme. The reduced design must be nested within the full design (i.e., all terms in the reduced must be included in the full).
- **correctControls** (logical) - Optional - If TRUE (default), use the negative controls to establish the null hypothesis, correcting for systemic bias in the data.
- **verbose** (logical) - Optional - Print progress reports (default: TRUE).
- **mode** (character) - Optional - Whether to run in classic mode ("classic") or in scalable mode ("scale"). Scale mode is only available in situations when each RNA observation has a single corresponding DNA observation.
- **BPPARAM** (BiocParallel object) - Optional - A parallelization object created by BiocParallel. This overwrites the BPPARAM object set in the object creation.

### Value
The MpraObject with fitted models for the input enhancers.

### Examples
```r
data <- simulateMPRA(tr = rep(2,5), da=c(rep(0,2), rep(1,3)), 
                     nbatch=2, nbc=15)
obj <- MpraObject(dnaCounts = data$obs.dna, 
                  rnaCounts = data$obs.rna, 
                  colAnnot = data$annot)
obj <- estimateDepthFactors(obj, lib.factor = "batch", which.lib = "both")
## run an LRT-based analysis, as recommnded:
obj <- analyzeComparative(obj, dnaDesign = ~ batch + barcode + condition, 
                              rnaDesign = ~ condition, reducedDesign = ~ 1)
                              
## alternatively, run a coefficient-based analysis:
obj <- analyzeComparative(obj, dnaDesign = ~ batch + barcode + condition, 
                              rnaDesign = ~ condition, fit.se = TRUE)
```
```

--------------------------------

### Estimate depth factors for library size normalization

Source: https://github.com/yoseflab/mpranalyze/blob/master/vignettes/vignette.Rmd

Estimates depth factors for DNA and RNA libraries using the upper quartile method. The 'lib.factor' argument specifies which annotation columns define libraries. The final call estimates factors for both DNA and RNA using the default method.

```r
## If the library factors are different for the DNA and RNA data, separate 
## estimation of these factors is needed. We can also change the estimation 
## method (Upper quartile by default)
obj <- estimateDepthFactors(obj, lib.factor = c("batch", "condition"),
                            which.lib = "dna", 
                            depth.estimator = "uq")
obj <- estimateDepthFactors(obj, lib.factor = c("condition"),
                            which.lib = "rna", 
                            depth.estimator = "uq")

## In this case, the factors are the same - each combination of batch and 
## condition is a single library, and we'll use the default estimation
obj <- estimateDepthFactors(obj, lib.factor = c("batch", "condition"),
                            which.lib = "both")
```

--------------------------------

### simulateMPRA

Source: https://github.com/yoseflab/mpranalyze/blob/master/man/simulateMPRA.Rd

Simulates an MPRA dataset with configurable parameters for transcription rates, differential activity, noise, barcodes, and batches. Returns a list with true and observed DNA/RNA counts and annotations.

```APIDOC
## simulateMPRA

### Description
Simulate an MPRA dataset using a nested-GLM construct with log-normal noise models.

### Usage
```r
simulateMPRA(
  tr = rep(2, 100),
  da = NULL,
  dna.noise.sd = 0.2,
  rna.noise.sd = 0.3,
  dna.inter = 5,
  dna.inter.sd = 0.5,
  nbc = 100,
  coef.bc.sd = 0.5,
  nbatch = 3,
  coef.batch.sd = 0.5
)
```

### Parameters
- **tr** (vector) - Optional - A vector of true transcription rates in log scale. Length determines number of enhancers. Default is 100 enhancers with transcription rate 2.
- **da** (vector) - Optional - Vector determining differential activity in log scale (log Fold-Change). If NULL (default), a single condition is simulated.
- **dna.noise.sd** (numeric) - Optional - Level of noise to add to the DNA library. Default: 0.2.
- **rna.noise.sd** (numeric) - Optional - Level of noise to add to the RNA library. Default: 0.3.
- **dna.inter** (numeric) - Optional - Baseline DNA levels (intercept term), controlling true mean abundance of plasmids. Default: 5.
- **dna.inter.sd** (numeric) - Optional - True variation of plasmid levels. Default: 0.5.
- **nbc** (integer) - Optional - Number of unique barcodes per enhancer. Default: 100.
- **coef.bc.sd** (numeric) - Optional - True variation between barcodes. Default: 0.5.
- **nbatch** (integer) - Optional - Number of batches to simulate. Default: 3.
- **coef.batch.sd** (numeric) - Optional - Level of true variation that distinguishes batches (size of batch effects). Default: 0.5.

### Return Value
A list with the following elements:
- **true.dna** - The true DNA abundances
- **obs.dna** - The observed DNA counts
- **true.rna** - The true RNA abundances
- **obs.rna** - The observed RNA counts
- **annot** - The annotations data.frame for each sample

### Details
The data is generated using the same nested-GLM construct that MPRAnalyze uses, with non-standard log-normal noise models (whereas by default MPRAnalyze uses a Gamma-Poisson model). The generated data can have multiple batches and either 1 or 2 conditions. The simulated data is always paired (DNA and RNA extracted from the same library). Users can control both true and observed variation levels (noise), the number of expected plasmids per barcode, the true transcription ratio, and the size of batch and barcode effects.

### Examples
```r
# single condition
data <- simulateMPRA()

# two conditions
data <- simulateMPRA(da=c(rep(-0.5, 50), rep(0.5, 50)))

# more observed noise
data <- simulateMPRA(dna.noise.sd = 0.75, rna.noise.sd = 0.75)

# gradually increasing dataset
data <- simulateMPRA(tr = seq(2,3,0.01), da=NULL)
```
```

--------------------------------

### Estimate depth factors with default and custom quantile

Source: https://github.com/yoseflab/mpranalyze/blob/master/man/estimateDepthFactors.Rd

The first block creates a simulated MPRA object and calls estimateDepthFactors with the default depth estimator ("uq"). The second block shows a custom depth.estimator function that uses the 95th quantile instead of the default 0.75, with na.rm=TRUE to handle missing values.

```r
data <- simulateMPRA(tr = rep(2,10), da=NULL, nbatch=2, nbc=20)
obj <- MpraObject(dnaCounts = data$obs.dna, 
                  rnaCounts = data$obs.rna, 
                  colAnnot = data$annot)
obj <- estimateDepthFactors(obj, lib.factor = "batch", which.lib = "both")
```

```r
## Upper quantile, using a higher quantile than 0.75:
obj <- estimateDepthFactors(obj, lib.factor = "batch", which.lib = "both",
                            depth.estimator = function(x) quantile(x, .95, 
                                 na.rm=TRUE))
```

--------------------------------

### testEmpirical with custom statistic

Source: https://github.com/yoseflab/mpranalyze/blob/master/man/testEmpirical.Rd

Tests with a different statistic by computing the aggregated ratio of RNA to DNA counts and passing it to testEmpirical.

```r
## or test with a different statistic:
aggregated.ratio <- rowSums(data$obs.rna) / rowSums(data$obs.dna)
results <- testEmpirical(obj, aggregated.ratio)
```

--------------------------------

### Create barcode-condition interaction annotation for allelic comparison

Source: https://github.com/yoseflab/mpranalyze/blob/master/vignettes/vignette.Rmd

Creates a new column 'barcode_allelic' in the column annotations by interacting the existing 'barcode' and 'condition' columns. This ensures each barcode is associated with only one condition, which is required for comparative analysis when sequences do not share barcodes. The summary() call displays the updated annotations.

```r
ce.colAnnot$barcode_allelic <- interaction(ce.colAnnot$barcode, ce.colAnnot$condition)
summary(ce.colAnnot)
```

--------------------------------

### getFits_RNA(obj, enhancers = NULL, depth = TRUE, full = TRUE, rnascale = TRUE)

Source: https://github.com/yoseflab/mpranalyze/blob/master/man/getFits_RNA.Rd

Retrieves RNA model-based estimates from an MpraObject. The estimates are the expected values based on the model and can be compared with observed counts to assess goodness of fit.

```APIDOC
## getFits_RNA(obj, enhancers = NULL, depth = TRUE, full = TRUE, rnascale = TRUE)

### Description
Get RNA model-based estimates from an MpraObject (the expected values based on the model). These can be compared with the observed counts to assess goodness of fit.

### Usage
```r
getFits_RNA(obj, enhancers = NULL, depth = TRUE, full = TRUE, rnascale = TRUE)
```

### Arguments
- **obj** (MpraObject) - Required - MpraObject to extract from
- **enhancers** (character vector, logical, or numeric) - Optional - Which enhancers to get the fits for. Can be character vectors with enhancer names, logical or numeric enhancer indices, or NULL if all enhancers are to be extracted (default)
- **depth** (logical) - Optional - Include depth correction in the model fitting (default TRUE)
- **full** (logical) - Optional - If LRT modeling was used, TRUE (default) would return the fits of the full model, FALSE would return the reduced model fits.
- **rnascale** (logical) - Optional - If controls were used to correct the fitting (in comparative analyses), use these factors to re-adjust the estimates back.

### Value
RNA fits (numeric, enhancers x samples)

### Examples
```r
data <- simulateMPRA(tr = rep(2,5), nbatch=2, nbc=15)
obj <- MpraObject(dnaCounts = data$obs.dna, 
                  rnaCounts = data$obs.rna, 
                  colAnnot = data$annot)
obj <- estimateDepthFactors(obj, lib.factor = "batch", which.lib = "both")
obj <- analyzeQuantification(obj, dnaDesign = ~ batch + barcode, 
                              rnaDesign = ~1)
rna.fits <- getFits_RNA(obj)
```
```

--------------------------------

### analyzeQuantification(obj, dnaDesign = ~1, rnaDesign = ~1, BPPARAM = NULL)

Source: https://github.com/yoseflab/mpranalyze/blob/master/man/analyzeQuantification.Rd

Performs quantitative analysis on the MPRA data to determine which sequences have a regulatory function when no condition is being tested. It fits models as specified and returns the MpraObject with populated models.

```APIDOC
## analyzeQuantification(obj, dnaDesign = ~1, rnaDesign = ~1, BPPARAM = NULL)

### Description
Performs quantitative analysis on the MPRA data to determine which sequences have a regulatory function when no condition is being tested. It fits models as specified and returns the MpraObject with populated models.

### Usage
```r
analyzeQuantification(obj, dnaDesign = ~1, rnaDesign = ~1, BPPARAM = NULL)
```

### Arguments
- **obj** (MpraObject) - Required - The MpraObject.
- **dnaDesign** (formula) - Optional - The design of the DNA counts. Default is `~1`.
- **rnaDesign** (formula) - Optional - The design of the RNA counts. Default is `~1`.
- **BPPARAM** (BiocParallel object) - Optional - A parallelization object created by BiocParallel. This overwrites the BPPARAM object set in the object creation.

### Value
Returns the MpraObject with populated models.

### Details
The analysis supports two approaches:
- **empirical**: The model is fitted as specified, enabling future empirical testing (either empirical p-value if negative controls are provided, or a global deviance analysis, see details in `test.empirical`).
- **lrt**: Only available if negative controls are provided. A likelihood ratio test is used, with the null hypothesis a joint model of the controls and a given candidate sequence, and the alternative model being a separate model for controls and candidates.

### Examples
```r
data <- simulateMPRA(tr = rep(2,10), nbatch=2, nbc=15)
obj <- MpraObject(dnaCounts = data$obs.dna, 
                  rnaCounts = data$obs.rna, 
                  colAnnot = data$annot)
obj <- estimateDepthFactors(obj, lib.factor = "batch", which.lib = "both")
obj <- analyzeQuantification(obj, dnaDesign = ~ batch + barcode, 
                              rnaDesign = ~1)
```
```

--------------------------------

### model(obj)

Source: https://github.com/yoseflab/mpranalyze/blob/master/man/MpraObject.Rd

Accessor method to retrieve the model from an MpraObject.

```APIDOC
## model(obj)

### Description
Accessor method to retrieve the model from an MpraObject.

### Method
Accessor

### Parameters
- **obj** (MpraObject) - Required - The MpraObject instance.

### Response
#### Success Response
Returns the model.

```

--------------------------------

### Simulate two-condition MPRA dataset with da vector

Source: https://github.com/yoseflab/mpranalyze/blob/master/man/simulateMPRA.Rd

Simulates a two-condition MPRA dataset by providing a vector of log fold-change values for differential activity. The first 50 enhancers have -0.5 and the last 50 have 0.5.

```r
# two conditions
data <- simulateMPRA(da=c(rep(-0.5, 50), rep(0.5, 50)))
```

--------------------------------

### testLrt(obj)

Source: https://github.com/yoseflab/mpranalyze/blob/master/man/testLrt.Rd

Calculates the likelihood ratio test for the specific nested model. Must be run after running an LRT-based analysis.

```APIDOC
## testLrt(obj)

### Description
Calculates likelihood ratio test for the specific nested model. Must be run after running an LRT-based analysis.

### Usage
```r
testLrt(obj)
```

### Arguments
- **obj** - The MpraObject containing the full and reduced model.

### Value
Returns a results data frame.

### Note
Must be run after running an LRT-based analysis.

### Examples
```r
data <- simulateMPRA(tr = rep(2,5), da=c(rep(0,2), rep(1,3)), 
                     nbatch=2, nbc=15)
obj <- MpraObject(dnaCounts = data$obs.dna, 
                  rnaCounts = data$obs.rna, 
                  colAnnot = data$annot)
obj <- estimateDepthFactors(obj, lib.factor = "batch", which.lib = "both")
obj <- analyzeComparative(obj, dnaDesign = ~ batch + barcode + condition, 
                              rnaDesign = ~ condition, reducedDesign = ~ 1)
results <- testLrt(obj)
```
```

--------------------------------

### rnaAnnot(obj)

Source: https://github.com/yoseflab/mpranalyze/blob/master/man/MpraObject.Rd

Accessor function to retrieve the RNA column (sample) annotations from an MpraObject.

```APIDOC
## rnaAnnot(obj)

### Description
Returns the data.frame with the RNA column (sample) annotations from an MpraObject.

### Usage
```r
rnaAnnot(obj)
```

### Arguments
- **obj** (MpraObject) - Required - The MpraObject to extract properties from.

### Value
A data.frame with the RNA column (sample) annotations.
```

--------------------------------

### estimateDepthFactors(obj, lib.factor)

Source: https://github.com/yoseflab/mpranalyze/blob/master/man/MpraObject.Rd

Estimates depth factors for normalization based on library factors.

```APIDOC
## estimateDepthFactors(obj, lib.factor)

### Description
Estimates depth factors for normalization based on library factors.

### Method
Function

### Parameters
- **obj** (MpraObject) - Required - The MpraObject instance.
- **lib.factor** (character vector) - Required - Library factors used for depth estimation.

### Request Example
```r
obj <- estimateDepthFactors(obj, lib.factor=c("batch", "condition"))
```

### Response
#### Success Response
Returns an updated MpraObject with estimated depth factors.

```
Tokens:
Raw