# `art_modern_utils`: Python Utilities for `art_modern`

`art-modern-utils` badges:
[![GitHub Release](https://img.shields.io/github/v/release/YU-Zhejian/art_modern_utils.svg)](https://github.com/YU-Zhejian/art_modern_utils/releases)
[![License](https://img.shields.io/badge/licence-GPL_3.0-blue.svg)](https://www.gnu.org/licenses/)
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)

`art-modern-utils` on PyPI:
[![Python version](https://img.shields.io/badge/python-3.9-blue)](https://www.python.org/downloads/)
[![PyPI - Version](https://img.shields.io/pypi/v/art-modern-utils)](https://pypi.org/project/art-modern-utils/)
[![PyPI - Downloads](https://img.shields.io/pypi/dm/art-modern-utils)](https://pypi.org/project/art-modern-utils/)

[![bioRxiv](https://img.shields.io/static/v1?label=preprint&message=bioRxiv&color=ee4d2d)](https://doi.org/10.64898/2026.02.20.707060)

Here presents `art_modern_utils`, a collection of Python utilities for [`art_modern`](https://github.com/YU-Zhejian/art_modern). In detail, it contains:

## `art-profile-fastqc`: A Python script for generating FASTQC-like report for ART-compatible error profiles

```text
$ art-profile-fastqc --help
usage: art-profile-fastqc [-h] [--version] [--input INPUT] [--output OUTPUT]

Generate boxplot from ART profile quality distribution

options:
  -h, --help       show this help message and exit
  --version        show program's version number and exit
  --input INPUT    Input file (default: stdin)
  --output OUTPUT  Output figure file. If unset, the plot will be shown interactively
```

Usage Example:

```shell
art-profile-fastqc --input ~/Documents/art_modern/data/Illumina_profiles/HiSeq2kL100R1.txt --output figs/HiSeq2kL100R1.txt.svg
```

Generating:

![HiSeq2kL100R1 QC Result](figs/HiSeq2kL100R1.txt.svg)

## `art-sam-validate`: A Python script for validating SAM/BAM files

This script can also be used to check whether the SAM/BAM files generated by aligners, etc., contains valid CIGAR string that matches what is specified in the reference sequence.

This script will work on sequences that are mapped to the opposite strand.

```text
$ art-sam-validate --help
usage: art-sam-validate [-h] ref alignment

Test whether a SAM/BAM is correct.

positional arguments:
  ref         Reference FASTA file
  alignment   Alignment BAM/SAM file

options:
  -h, --help  show this help message and exit
```

Usage Example:

```shell
art-sam-validate \
    ~/Documents/art_modern_benchmark_other_simulators/data/e_coli.fa \
    ~/Documents/art_modern_benchmark_other_simulators/data/e_coli_CNR0028307.bam
```

Output:

```text
4128472it [00:14, 283405.25it/s]
{'UNALIGNED': 376180, 'POS': 1877049, 'NEG': 1875243}
```

Meaning that there are 376,180 unaligned reads, with 1,877,049 and 1,875,243 reads aligned to positive and negative strand respectively. All reads are aligned without errors in BAM file.

## Copyright

Copyright (C) 2025--2026 YU Zhejian

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <https://www.gnu.org/licenses/>.
