MARADONER

MARADONER: Motif Activity Response Analysis Done Right

MARADONER is a tool for analyzing motif activities using promoter expression data. It provides a streamlined workflow to estimate parameters, predict deviations, and export results in a tabular form.

Installation

MARADONER needs Python 3.11 or newer:

pip install maradoner

Input files

All tables are plain text (.tsv or .csv, optionally gzipped) with named rows and named columns: the first line holds the column names and the first column holds the row names.

• Promoter expression (p promoters x s samples), in log scale. Rows are promoters, columns are samples.
• Motif loadings (p promoters x m motifs): how strongly each motif is associated with each promoter. Rows must use the same promoter names as the expression table; promoters that are missing from either table are dropped. Several loading matrices can be supplied at once (see --loading-postfix).
• (Optional) Sample groups: which samples are replicates of the same condition. Either a JSON dictionary

  {"control": ["sample_1", "sample_2"], "treated": ["sample_3", "sample_4"]}
  

  or a text file with one group per line: the group name followed by its sample names. Without it every sample is a group of its own.
• (Optional) Covariates (--covariates): a table with sample names in the first column and one column per covariate (e.g. sex, age). Numeric covariates are z-scored, categorical ones are one-hot encoded.

Basic Workflow

A typical MARADONER analysis session involves running commands sequentially for a given project:

1. create: Initialize the project. This step parses your input files (promoter expression, motif loadings, optional motif expression, and sample groupings), performs initial filtering, and sets up the project's internal data structures.

   # Example: Initialize a project named 'my_project'
   maradoner create my_project path/to/expression.tsv path/to/loadings.tsv --sample-groups path/to/groups.json [other options...]
   

   • Input files are typically tabular (.tsv, .csv), potentially compressed.
   • You only need to provide input data files at this stage.
   • Read the warnings: create reports promoters, samples and motifs that it had to drop.

2. fit: Estimate the model's variance parameters and mean motif activities using the data prepared by create.

   maradoner fit my_project [options...]
   

3. predict: Estimate the deviations of motif activities from their means for each sample or group, based on the parameters estimated by fit.

   maradoner predict my_project [options...]
   

4. export: Save the final results, including estimated motif activities (mean + deviations), parameter estimates, goodness-of-fit statistics, and potentially statistical test results (like ANOVA) to a specified output folder.

   maradoner export my_project path/to/output_folder [options...]
   

The commands depend on each other: fit needs create, predict needs fit, and the commands that report results (export, gof, anova, contrast, grn) need predict. Re-running an earlier step invalidates the later ones: after a new fit run predict again (results of the outdated later steps are removed automatically).

What export writes

Motifs appear in the activity and test tables only if predict kept them (see predict --filter-motifs).

Other Useful Commands

• gof: After predict, calculate Goodness-of-Fit statistics (like Fraction of Variance Explained or Correlation) to evaluate how well the model components explain the observed expression data.

  maradoner gof my_project [options...]
  

  To evaluate the model on promoters it has not seen, hold some of them out at the fit stage and estimate their promoter-specific means before gof:

  maradoner fit my_project --test-chromosomes 3 --test-chromosomes X   # or --test-promoters-filename names.txt
  maradoner predict my_project
  maradoner estimate-promoter-mean my_project
  maradoner gof my_project
  

  The held-out promoters take no part in fit. Note, however, that the low-expression filter of create has already seen all promoters; use create --filter-lowexp-w 1 if the testing set must not influence anything at all.
• anova: Test whether motif activities differ between the listed groups.

  maradoner anova my_project anova.tsv control treated_6h treated_24h
  

• contrast: Test a linear combination of group activities, written as an algebraic expression of group names.

  maradoner contrast my_project "treated - control" path/to/output_folder
  maradoner contrast my_project "(a + b + c) / 3 - d" path/to/output_folder
  

  With --covariates, the variables are covariates in place of groups, and their effects on motif activities are compared (covariate_contrast.tsv). The reference level of a categorical covariate stands for zero.

  maradoner contrast my_project "tissue_liver - tissue_muscle" path/to/output_folder --covariates
  

• grn: Test each promoter against each motif in each group ("gene regulatory network"). The output is large: one promoters x motifs table per group.

  maradoner grn my_project path/to/output_folder
  

  In a project with covariates, --covariate <name> tests the effect of a covariate on motif activities in place of the activities. All samples are used, and one table per covariate is written to belief/covariates.

  maradoner grn my_project path/to/output_folder --covariate age
  

• select-rank: Choose the number of factors for fit --activity-lowrank. Models with 1, 2, ... factors are fitted, and a factor is accepted if it lowers the REML deviance more than a factor does on data simulated from the model without it. Needs a fitted project and changes nothing in it.

  maradoner select-rank my_project --max-rank 3
  

• select-motifs: If you provided multiple loading matrices in create (e.g., from different databases) with unique postfixes, this command helps select the single "best" variant for each motif based on statistical criteria. The output is a list of motif names intended to be used with the --motif-filename option in a subsequent create run.

  maradoner select-motifs my_project best_motifs.txt
  # Then, potentially re-run create using the generated list:
  # maradoner create my_project_filtered ... --motif-filename best_motifs.txt
  

• bayes_linreg: A different, single-sample model for data without replication across samples (fit needs at least two samples). It goes straight from a project to result files.

  maradoner bayes_linreg my_project path/to/output_folder
  

• generate: Create a synthetic dataset with known properties for testing or demonstration purposes.

  maradoner generate path/to/synthetic_data_output [options...]
  

• mara: The classical (IS)MARA model, for comparison purposes (maradoner mara --help).

Model extensions

• create --covariates covariates.tsv: mean motif activities depend on sample covariates.
• create --covariates covariates.tsv --formula "age * sex + batch": a formula chooses columns of the table and adds their interactions (a:b; a * b stands for a + b + a:b).
• fit --error-lowrank k / fit --activity-lowrank k: low-rank corrections for correlated noise / correlated activities across samples. export writes the factors to params/error_factors.tsv / params/factors.tsv; the latter is a valid table for create --covariates.
• fit --clustering KMeans|NMF --num-clusters k: replace motifs by clusters of motifs with similar loadings (useful when there are more motifs than the data can tell apart); all later commands then report clusters.
• fit --no-motif-variance: one common variance for all motifs, closer to the classical (IS)MARA.
• fit --promoter-variance (experimental): heuristic reweighting of promoters by their noise level.

Performance

MARADONER uses one thread for linear algebra by default: it mostly works with many small matrices, where the usual one-thread-per-core setting makes it considerably slower. Use maradoner --threads N <command> ... (or the MARADONER_THREADS environment variable) to change it; if OMP_NUM_THREADS and the like are already set in your environment they are respected.

On small and medium datasets a large part of the run time is spent compiling numerical code, the same code on every run. Set the environment variable MARADONER_JAX_CACHE to a folder (e.g. export MARADONER_JAX_CACHE=~/.cache/maradoner) to keep the compiled code between runs; repeated runs then start several times faster.

When something goes wrong

Problems with the input (a malformed table, sample names that do not match, a step that was skipped) are reported as a short Error: ... message that says what to fix. A long traceback, on the other hand, means an unexpected internal error: please report it via the issue tracker. Set the environment variable MARADONER_DEBUG=1 to get a traceback for every error.

Getting Help

Each command has various options for customization. To see the full list of commands and their detailed options, use the --help flag:

maradoner --help
maradoner create --help
maradoner fit --help
# and so on for each command

There's also a project doumentation available at maradoner.georgy.top.

Cite

For the time being, you can cite our technical arXiv paper that explains MARADONER's inner clockworks in a great detail:

@misc{meshcheryakov2026,
      title={MARADONER: Motif Activity Response Analysis Done Right}, 
      author={Georgy Meshcheryakov and Andrey I. Buyan},
      year={2026},
      eprint={2602.03343},
      archivePrefix={arXiv},
      primaryClass={stat.CO},
      url={https://arxiv.org/abs/2602.03343}, 
}