| Type: | Package |
| Title: | Statistical Framework for Co-Mediators of Zero-Inflated Single-Cell Data |
| Version: | 0.0.5 |
| Description: | A causal mediation framework for single-cell data that incorporates two key features ('MedZIsc', pronounced Magics): (1) zero-inflation using beta regression and (2) overdispersed expression counts using negative binomial regression. This approach also includes a screening step based on penalized and marginal models to handle high-dimensionality. Full methodological details are available in our recent preprint by Ahn S et al. (2025) <doi:10.48550/arXiv.2507.06113>. |
| License: | GPL-3 |
| Encoding: | UTF-8 |
| RoxygenNote: | 7.3.2 |
| Depends: | R (≥ 3.5.0) |
| Imports: | MASS, betareg, glmnet |
| Suggests: | knitr, rmarkdown, testthat (≥ 3.0.0) |
| LazyData: | true |
| Config/testthat/edition: | 3 |
| NeedsCompilation: | no |
| Packaged: | 2026-08-27 03:07:02 UTC; seungjunahn |
| Author: | Seungjun Ahn 
[cre, aut],
Zhigang Li [ctb] |
| Maintainer: | Seungjun Ahn <seungjun.ahn@mountsinai.org> |
| Repository: | CRAN |
| Date/Publication: | 2026-08-28 09:50:43 UTC |
Magics
Description
A main function for conducting causal mediation analysis with co-mediators derived from zero-inflated single-cell data.
Usage
Magics(data.name, n_genes, covariate.names)
Arguments
data.name |
A data.frame or matrix with N x (2G + k), where N is the number of samples, G is the number of genes, and K is the number of covariates. For each gene, the input includes M_g and F_g, where M_g represents the sample-level expression mediator and F_g represents the proportion of cells with nonzero expression. |
n_genes |
An integer value. The number of genes (G) represented in the data. |
covariate.names |
A character vector to specify the column name of covariates. |
Value
A list containing the following elements: (1) estimated coefficients from the outcome and two mediation models (M and F models in methodology paper); (2) standard errors corresponding to (1); (3) logical vector indicating whether each gene's mediator component (M model) is statistically significant; (4) logical vector indicating whether each gene's zero-inflation component (F model) is statistically significant; (5) Adjusted p-values for M and F model (joint significance test).
References
Ahn S, Li Z. A Statistical Framework for Co-Mediators of Zero-Inflated Single-Cell RNA-Seq Data. ArXiv. 2025 July 8:arXiv:2507.06113v1. Available at: https://arxiv.org/pdf/2507.06113
Examples
data("simulated_data")
n_genes = ncol(simulated_data[, grep("^(M_)", colnames(simulated_data))])
Magics(data.name = simulated_data, n_genes = n_genes, covariate.names = c("Z1", "Z2", "Z3"))
adjust_Fg
Description
A function that adjusts zero proportion values to meet the requirements of beta regression by bounding values of 0 and 1 to 0.001 and 0.999.
Usage
adjust_Fg(Fg)
Arguments
Fg |
A numeric vector of length n, where each element represents the proportion of zero counts for a given gene g across cells for subject i. |
Value
A vector of adjusted zero proportions, with values constrained between 0.001 and 0.999.
Compute M Mediator
Description
Computes the sample-level expression mediator used for Magics().
Usage
compute_M(counts, sample_id, M_type = c("overall", "nonzero"))
Arguments
counts |
A matrix or data.frame of cell-level gene expression counts, with cells in rows and genes in columns. |
sample_id |
A vector indicating the sample corresponding to each cell.
Its length must equal the number of rows in |
M_type |
A character string specifying how the expression mediator is
calculated. |
Value
A data.frame with one row per sample and one M variable per gene.
For M_type = "nonzero", the M value is set to 0 when a gene has zero
expression in all cells within a sample.
Simulated Mediation Dataset
Description
A simulated dataset created for zero-inflated single-cell mediation analysis.
Usage
simulated_data
Format
An object of class data.frame with 400 rows and 405 columns.
Details
A simulated dataset used to evaluate mediation methods for zero-inflated single-cell data. The dataset includes 300 samples with a continuous outcome (Y), a binary exposure (X), three covariates (Z1–Z3), 200 aggregated gene expression values (M_1–M_200), and corresponding zero proportions (F_1–F_200).
Source
Simulated using code in inst/scripts/simulate_example_data.R