Package: mixalime
[MIXALIME webpage]MixALime: Mixture models for Allelic Imbalance EstimationMixALimeis a tool for the identification of allele-specific events in high-throughput sequencing data. It works by modelling counts data as a mixture of two Negative Binomial or Beta Negative Binomial distributions (where the latter is more applicable in case of noisy data at a cost of loss of sensitivity).Homepage & DocsMixALimefeatures and usage guidelines are best explained at the project's homepage:mixalime.georgy.topSystem requirementsOSIn our work, we mostly usedUbuntu 20.04.6 LTS (GNU/Linux 5.15.0-82-generic x86_64)andManjaro 6.1.62-1. We never testedMixALimeon Windows systems.Software dependenciesMixALimeis best used withPython 3.9.
Package dependencies that could affectMixALimeresults are theJAX  0.4.20,scipy 1.11.3andnumpy 1.26.2.Hardware requirementsIt is best to useMixALimewith plenty of RAM available if one wishes to use the parallelization to the full extent. In that case, make sure that your system has at least 16GB of RAM. However, the RAM requirement is depends on a dataset.Input requirementsMixalime expects input VCF/BED files to contain biallelic SNPs with Ref alleles corresponding to the reference genome. Multiallelic SNPs can be split into biallelic records withbcftools norm --multiallelics, Ref alleles can be checked with—check-refbcftools option.Installation guideMixALimecan be easily installed with thepippackage manager.> pip3 install mixalimeAlternatively,MixALimecan be installed from the git repository:> git clone https://github.com/autosome-ru/MixALime 
> cd MixALime 
> python3 setup.py installRegardless of the chosen method, installation time of theMixALimealone is capped by the internet connection speed, but should take no longer than a minute, granted that all the dependency packages are already installed.Instructions for useThe package isalmosteasy to use and we advise everyone to just jump straight to installingMixALimeand invoking the help command in a command line:> pip3 install mixalime
> mixalime --helpWe believe that the help section ofMixALimecovers its functionality well enough. Furthermore, the package arrives with a small demo dataset included and an easy-to-follow instruction in the abovementioned help section. Furthermore, note that all commands avaliable inMixALime's command-line interface have their ownhelppage too, e.g.:> mixalime fit --helpSo do not waste your time looking for how-to-clues or tutorials here, just use--help.Yet, for the sake of following the social norms that impose a requirement of README files to be useful, in the next section you'll find the excerpt from--helpcommand as well as some other possibly useful details:DemoA typicalMixALimesession consists of sequential runs ofcreate,fit,test,combineand, finally,export all,plotcommands. For instance, we provide a demo dataset that consists of a bunch of BED-like files with allele counts at SNVs (just for the record,MixALimecan work with most vcf and  BED-like file formats):> mixalime export demoAscorefilesfolder should appear now in a working directory with a plenty of BED-like files.
First, we'd like to parse those files into aMixALime-friendly and efficient data structures for further usage, as well as perform some basic filtering if necessary:> mixalime create myprojectname scorefiles --no-snp-bad-checkExpected output:┏━━━━━━┳━━━━━━━┳━━━━━━━━━━━━━━━┓
┃ BAD  ┃ SNVs  ┃ Obvservations ┃
┡━━━━━━╇━━━━━━━╇━━━━━━━━━━━━━━━┩
│ 1.00 │ 10320 │ 24893         │
│ 1.33 │ 7408  │ 13359         │
│ 1.50 │ 12409 │ 37584         │
│ 2.00 │ 41763 │ 199208        │
│ 2.50 │ 2195  │ 3585          │
│ 3.00 │ 6897  │ 26558         │
│ 4.00 │ 1677  │ 2420          │
│ 5.00 │ 712   │ 926           │
│ 6.00 │ 731   │ 1143          │
└──────┴───────┴───────────────┘
Total unique SNVs: 84112, total observations: 309676
✔️ Done!  time: 9.72 s.By default, MixALime throws an error if the same SNV belongs regions of different background allelic dosage (BAD) in data, as it is not possible in a single cell type. However, for datasets of multiple samples, this is fully OK, hence we turn this check off with the--no-snp-bad-check. The output:Then we fit model parameters to the data with Negative Binomial distribution:> mixalime fit myprojectname NBExpected output:WARNING:root:Total number of samples at BAD 6.0 is less than a window size (1143 < 10000). Number of samples is too small for a sensible fit, a conservative fit will be used.
WARNING:root:Total number of samples at BAD 2.5 is less than a window size (3585 < 10000). Number of samples is too small for a sensible fit, a conservative fit will be used.
WARNING:root:Total number of samples at BAD 5.0 is less than a window size (926 < 10000). Number of samples is too small for a sensible fit, a conservative fit will be used.
WARNING:root:Total number of samples at BAD 4.0 is less than a window size (2420 < 10000). Number of samples is too small for a sensible fit, a conservative fit will be used.
✔️ Done!  time: 38.21 s.Warnings are fine. More on them in thetutorial.
Next we obtain raw p-values:> mixalime test myprojectnameExpected output:✔️ Done!  time: 47.96 s.Usually we'd want to combine p-values across samples and apply a FDR correction:> mixalime combine myprojectnameExpected output:┏━━━━━━┳━━━━━━┳━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃      ┃      ┃      ┃ Total significant          ┃
┃ Ref  ┃ Alt  ┃ Both ┃ (Percentage of total SNVs) ┃
┡━━━━━━╇━━━━━━╇━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ 1325 │ 1127 │ 1    │ 2451 (7.28%)               │
└──────┴──────┴──────┴────────────────────────────┘
Total SNVs tested: 33689
✔️ Done!  time: 10.99 s.Finally, we obtain fancy plots fir diagnostic purposes and easy-to-work-with tabular data:> mixalime export all myprojectname results_folder
> mixalime plot myprojectname results_folderExpected output:✔️ Done!  time: 4.29 s.
✔️ Done!  time: 28.00 s.You'll find everything of interest inresults_folder.Combination of p-values across groupsNote: a popular synonym for "combination" in this context isaggregation.One important feature that is not covered by the glorified--helpin a very obvious fashion is a combination of p-values across separate groups (e.g. one group can be a treatment and the other is a control). Thecombinecommand with default options combines all the p-values. This can be changed by supplying the--groupoption followed by either a list of filenames that make up that group or a file that contains a list (newline-separated) of those files (the most convenient approach, probably), e.g.:> mixalime combine --subname treatment -g vcfs/file1.vcf.gz -g vfcfs/file2.vfc.gz -g vcfs/file3.vcf.gz myproject
> mixalime combine --subname control -g vcfs/file4.vcf.gz -g vfcfs/file5.vfc.gz -g vcfs/file6.vcf.gz myprojector> mixalime combine --subname treatment -g group_treatment.tsv combine myproject
> mixalime combine --subname control -g group_control.tsv combine myprojectThe--subnameoption is necessary if you wish to avoid differentcombineinvocations overwriting each other.Scoring modelsThe package provides a variety of models for datasets of varying dispersion:NameDataset varianceCommentsNBLowFastest parameter estimation; might be too liberal for some datasetsMCNBMedium-lowMarginalized Compound Negative Binomial (MCNB), the safest compromise between liberal NB and conservative BetaNBBetaNBHighIntroduces an extra parameter to control for higher variance, fits most datasets perfectly, yet the scoring is often overly conservativeRegularized BetaNBDependsIntroduces penalty on the extra parameter to make the model less likely to overfit with the--regul-acommand. Requires tuning the regularization hyperparameter alpha which might not be feasibleThe name of the appropriate model is supplied to thefitcommand as an argument (except for regularized BetaNB which is just anfit ProjectName BetaNBwith an--regul-a alpha_valueoption wherealpha_valueis your hyperparameter value, e.g.1.0).Binomial and beta-binomial modelsMixALimealso can do good old-fashion binomial and beta-binomial tests. They can be done with the separatetest_binom(with--betaflag if you want beta-binomial). Note, that with this command you can skip thefit(as not fit is done here, except for beta-binomial, where a single variance parameter is estimated for each BAD) andteststep.Inner clockworks & CitingFor the time being, you can citeour technical arXiv paperthat explains MixALime's inner clockworks in a great detail:@misc{mixalimeMath,
      title={MIXALIME: MIXture models for ALlelic IMbalance Estimation in high-throughput sequencing data}, 
      author={Georgy Meshcheryakov and Sergey Abramov and Aleksandr Boytsov and Andrey I. Buyan and Vsevolod J. Makeev and Ivan V. Kulakovskiy},
      year={2023},
      eprint={2306.08287},
      archivePrefix={arXiv},
      primaryClass={stat.AP},
      doi          = {10.48550/arXiv.2306.08287},
      url          = {https://doi.org/10.48550/arXiv.2306.08287}
}andthe practical bioRxiv paper:@article{mixalimeUsage,
	author = {Andrey Buyan and Georgy Meshcheryakov and Viacheslav Safronov and Sergey Abramov and Alexandr Boytsov and Vladimir Nozdrin and Eugene F. Baulin and Semyon Kolmykov and Jeff Vierstra and Fedor Kolpakov and Vsevolod J. Makeev and Ivan V. Kulakovskiy},
	title = {Statistical framework for calling allelic imbalance in high-throughput sequencing data},
	elocation-id = {2023.11.07.565968},
	year = {2023},
	doi = {10.1101/2023.11.07.565968},
	publisher = {Cold Spring Harbor Laboratory},
	abstract = {High-throughput sequencing facilitates large-scale studies of gene regulation and allows tracing the associations of individual genomic variants with changes in gene expression. Compared to classic association studies, allelic imbalance at heterozygous variants captures the functional effects of the regulatory genome variation with smaller sample sizes and higher sensitivity. Yet, the identification of allele-specific events from allelic read counts remains non-trivial due to multiple sources of technical and biological variability, which induce data-dependent biases and overdispersion. Here we present MIXALIME, a novel computational framework for calling allele-specific events in diverse omics data with a repertoire of statistical models accounting for read mapping bias and copy-number variation. We benchmark MIXALIME against existing tools and demonstrate its practical usage by constructing an atlas of allele-specific chromatin accessibility, UDACHA, from thousands of available datasets obtained from diverse cell types.Availability https://github.com/autosome-ru/MixALime, https://udacha.autosome.orgCompeting Interest StatementThe authors have declared no competing interest.},
	URL = {https://www.biorxiv.org/content/early/2023/11/09/2023.11.07.565968},
	eprint = {https://www.biorxiv.org/content/early/2023/11/09/2023.11.07.565968.full.pdf},
	journal = {bioRxiv}
}LicenseMixALimeis distributed underWTFPL. If you prefer more standard licenses, feel free to treat WTFPL as CC-BY.