{"id":35646110,"url":"https://github.com/vibtobilab/methurator","last_synced_at":"2026-01-24T18:01:14.000Z","repository":{"id":327061892,"uuid":"1088332081","full_name":"VIBTOBIlab/methurator","owner":"VIBTOBIlab","description":"methurator is a Python package designed to estimate sequencing saturation for reduced-representation bisulfite sequencing (RRBS) data.","archived":false,"fork":false,"pushed_at":"2026-01-22T15:46:07.000Z","size":3915,"stargazers_count":0,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-23T02:19:17.636Z","etag":null,"topics":["methylation","rrbs","sequencing-saturation"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/methurator/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/VIBTOBIlab.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-02T19:04:39.000Z","updated_at":"2026-01-05T11:08:28.000Z","dependencies_parsed_at":"2026-01-24T18:00:44.765Z","dependency_job_id":null,"html_url":"https://github.com/VIBTOBIlab/methurator","commit_stats":null,"previous_names":["vibtobilab/methurator"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/VIBTOBIlab/methurator","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VIBTOBIlab%2Fmethurator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VIBTOBIlab%2Fmethurator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VIBTOBIlab%2Fmethurator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VIBTOBIlab%2Fmethurator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/VIBTOBIlab","download_url":"https://codeload.github.com/VIBTOBIlab/methurator/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VIBTOBIlab%2Fmethurator/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28733285,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-24T17:51:25.893Z","status":"ssl_error","status_checked_at":"2026-01-24T17:50:48.377Z","response_time":89,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["methylation","rrbs","sequencing-saturation"],"created_at":"2026-01-05T13:10:48.632Z","updated_at":"2026-01-24T18:01:13.990Z","avatar_url":"https://github.com/VIBTOBIlab.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🧬 methurator\n\n[![Python Versions](https://img.shields.io/badge/python-≥3.10%20\u0026%20≤3.13-blue.svg)](https://www.python.org/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)\n[![Tested with pytest](https://img.shields.io/badge/tested%20with-pytest-blue.svg)](https://pytest.org/)\n[![Install with BioConda](https://img.shields.io/badge/bioconda-methurator-brightgreen.svg?logo=anaconda)](https://anaconda.org/bioconda/methurator)\n[![BioContainer](https://img.shields.io/badge/biocontainer-methurator-0A7BBB.svg?logo=docker)](https://quay.io/repository/biocontainers/methurator)\n\n**Methurator** is a Python package designed to estimate CpGs saturation for DNA methylation sequencing data.\n\n---\n\n## 📑 Table of Contents\n\n- [1. Dependencies and Notes](#1-dependencies-and-notes)\n- [2. Installation](#2-installation)\n- [3. Quick Start](#3-quick-start)\n  - [Option A: Good-Toulmin Estimator](#option-a-good-toulmin-estimator)\n  - [Option B: Downsample](#option-b-downsample)\n  - [Step 3 — Plot the sequencing saturation curve](#step-3--plot-the-sequencing-saturation-curve)\n- [4. Command Reference](#4-command-reference)\n  - [`gt-estimator` command](#gt-estimator-command)\n  - [`downsample` command](#downsample-command)\n  - [`plot` command](#plot-command)\n- [5. Example Workflow](#5-example-workflow)\n- [6. How do we compute the sequencing saturation?](#6-how-do-we-compute-the-sequencing-saturation)\n\n---\n\n## 1. Dependencies and Notes\n\n- methurator uses [SAMtools](https://www.htslib.org/) and [MethylDackel](https://github.com/dpryan79/MethylDackel) internally for BAM subsampling, thus they need to be installed.\n- When `--genome` is provided, the corresponding FASTA file will be automatically fetched and cached.\n- Temporary intermediate files are deleted by default unless `--keep-temporary-files` is specified.\n\n---\n\n## 2. Installation\n\nYou can install **methurator** in several ways:\n\n### **Option 1: Install via pip**\n\n```bash\npip install methurator\n```\n\n### **Option 2: Install via BioConda**\n\n```bash\nconda create -n methurator_env conda::methurator\nconda activate methurator_env\n```\n\n### **Option 3: Use the BioContainer**\n\n```bash\ndocker pull quay.io/biocontainers/methurator:0.1.8--pyhdfd78af_0\ndocker run quay.io/biocontainers/methurator:0.1.8--pyhdfd78af_0 methurator -h\n```\n\n---\n\n## 3. Quick Start\n\n### Option A: Good-Toulmin Estimator (best practise)\n\nThe `gt-estimator` command performs **Good-Toulmin extrapolation** to estimate sequencing saturation and predict the theoretical number of CpGs at higher depth. This is the recommended approach for extrapolation analysis.\n\n```bash\nmethurator gt-estimator --fasta tests/data/genome.fa tests/data/Ecoli.csorted.bam\n```\n\nThis command generates:\n\n- **Summary YAML file** (`methurator_summary.yml`) — Contains metadata, model parameters, and extrapolation results with:\n  - Extrapolation factor (t) values from 0 to `--t-max` (default: 10.0)\n  - Boolean indicating interpolated (t ≤ 1) vs extrapolated (t \u003e 1) data\n  - Total CpGs predicted at each t value\n  - Confidence intervals (if `--compute_ci` is enabled)\n\n### Option B: Downsample\n\nThe `downsample` command performs BAM downsampling according to specified percentages and coverage levels:\n\n```bash\nmethurator downsample --fasta tests/data/genome.fa tests/data/Ecoli.csorted.bam\n```\n\nThis command generates:\n\n- **CpG summary** — number of unique CpGs detected in each downsampled BAM\n- **Reads summary** — number of reads in each downsampled BAM\n- **Summary YAML** — consolidated file with all data and run metadata\n\n### Plot the sequencing saturation curve\n\nUse the `plot` command to visualize the results:\n\n```bash\nmethurator plot --summary output/methurator_summary.yml\n```\n\n---\n\n## 4. Command Reference\n\n### `gt-estimator` command\n\nThe **Good-Toulmin estimator** fits an extrapolation model to predict sequencing saturation at infinite depth.\n\n| Argument                       | Description                                                                                                        | Default               |\n| ------------------------------ | ------------------------------------------------------------------------------------------------------------------ | --------------------- |\n| `BAM (positional)`             | Path to a single `.bam` file or to multiple ones (e.g. `files/*.bam`).                                             | —                     |\n| `--outdir, -o`                 | Output directory.                                                                                                  | `./output`            |\n| `--fasta`                      | Path to the reference genome FASTA file. If not provided, it will be automatically downloaded based on `--genome`. | —                     |\n| `--genome`                     | Genome used for alignment. Available: `hg19`, `hg38`, `GRCh37`, `GRCh38`, `mm10`, `mm39`.                          | —                     |\n| `--minimum-coverage`, `-mc`    | Minimum CpG coverage to consider. Can be a single integer or a list (e.g. `1,3,5`).                                | `1`                   |\n| `--t-step`                     | Step size for extrapolation factor (t) predictions.                                                                | `0.05`                |\n| `--t-max`                      | Maximum extrapolation factor (t) value.                                                                            | `10.0`                |\n| `--compute_ci`                 | Compute confidence intervals using bootstrap replicates.                                                           | `False`               |\n| `--bootstrap-replicates`, `-b` | Number of bootstrap replicates for CI computation.                                                                 | `30`                  |\n| `--conf`                       | Confidence level for bootstrap intervals.                                                                          | `0.95`                |\n| `--mu`                         | Initial mu parameter for negative binomial distribution in EM algorithm.                                           | `0.5`                 |\n| `--size`                       | Initial size parameter for negative binomial distribution in EM algorithm.                                         | `1.0`                 |\n| `--mt`                         | Constraint for rational function approximations.                                                                   | `20`                  |\n| `--rrbs`                       | If set to True, MethylDackel will use the RRBS flag (--keepDupes).                                                 | `False`               |\n| `--threads`, `-@`              | Number of threads to use.                                                                                          | Available threads - 2 |\n| `--keep-temporary-files`, `-k` | Keep temporary files after analysis.                                                                               | `False`               |\n| `--verbose`                    | Enable verbose logging.                                                                                            | `False`               |\n| `--help` , `-h`                | Print the help message and exit.                                                                                   |                       |\n| `--version`                    | Print the package version.                                                                                         |                       |\n\n---\n\n### `downsample` command\n\n| Option                              | Description                                                                                                        | Default               |\n| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------ | --------------------- |\n| `BAM (positional)`                  | Path to a single `.bam` file or to multiple ones (e.g. `files/*.bam`).                                             | —                     |\n| `--outdir`, `-o`                    | Output directory.                                                                                                  | `./output`            |\n| `--fasta`                           | Path to the reference genome FASTA file. If not provided, it will be automatically downloaded based on `--genome`. | —                     |\n| `--genome`                          | Genome used for alignment. Available options: `hg19`, `hg38`, `GRCh37`, `GRCh38`, `mm10`, `mm39`.                  | —                     |\n| `--downsampling-percentages`, `-ds` | Comma-separated list of downsampling percentages between 0 and 1 (exclusive).                                      | `0.1,0.2,0.4,0.6,0.8` |\n| `--minimum-coverage`, `-mc`         | Minimum CpG coverage to consider for saturation. Can be a single integer or a list (e.g. `1,3,5`).                 | `3`                   |\n| `--rrbs`                            | If set, MethylDackel extract will consider the RRBS nature of the data by adding the `--keepDupes` flag.           | `False`               |\n| `--threads`, `-@`                   | Number of threads to use during downsampling.                                                                      | All available threads |\n| `--keep-temporary-files`            | If set, temporary files will be kept after analysis.                                                               | `False`               |\n| `--verbose`                         | Enable verbose logging.                                                                                            | `False`               |\n| `--help`, `-h`                      | Print the help message and exit.                                                                                   | —                     |\n| `--version`                         | Print the package version.                                                                                         | —                     |\n\n### `plot` command\n\n| Argument          | Description                      | Default    |\n| ----------------- | -------------------------------- | ---------- |\n| `--summary`, `-s` | Path to the YML summary file.    |            |\n| `--outdir`, `-o`  | Output directory.                | `./output` |\n| `--verbose`       | Enable verbose logging.          | `False`    |\n| `--help` , `-h`   | Print the help message and exit. |            |\n| `--version`       | Print the package version.       |            |\n\n---\n\n## 5. Example Workflow\n\n### Using Good-Toulmin Estimator (Recommended)\n\n```bash\n# Run Good-Toulmin estimator on BAM file\nmethurator gt-estimator --genome hg19 my_sample.bam --config_ci\n\n# Generate plots from the results\nmethurator plot --summary output/methurator_summary.yml\n```\n\n**Example plot preview** (also available as interactive html file [here](https://github.com/VIBTOBIlab/methurator/tree/main/docs/images/example_gt.html)):\n\n![Plot preview](https://raw.githubusercontent.com/VIBTOBIlab/methurator/main/docs/images/example_gt.png)\n\n### Using Downsample\n\n```bash\n# Downsample BAM file\nmethurator downsample --genome hg19 my_sample.bam\n\n# Generate plots from the results\nmethurator plot --summary output/methurator_summary.yml\n```\n\nThe output plots will be saved in `output/plots/` as interactive HTML files showing the CpG predictions with confidence intervals (if enabled).\n\n**Example plot preview** (also available as interactive html file [here](https://github.com/VIBTOBIlab/methurator/tree/main/docs/images/example.html)):\n\n![Plot preview](https://raw.githubusercontent.com/VIBTOBIlab/methurator/main/docs/images/example.png)\n\n## 6. How do we compute the sequencing saturation?\n\n### Good-Toulmin Estimator approach (best practise)\n\n**methurator gt-estimator** uses an approach developed in 2018 by [Chao Deng et al](https://arxiv.org/abs/1607.02804) and further implemented in [preseqR](https://github.com/smithlabcode/preseqR). This approach builds on the theoretical nonparametric empirical Bayes foundation of **Good and Toulmin (1956)**, to model sequencing saturation and extrapolate to higher sequencing depths. The model implemented in **preseqR** was mirrored here and tailored toward sequencing saturation application. The workflow consists of the following steps:\n\n1. **Extracts CpGs** from BAM files using MethylDackel\n2. **Fits the model implemented by Chao Deng et al** taking in input the observed CpG counts\n3. **Predicts future CpG discovery** using rational function approximations\n4. **Quantifies confidence intervals** through bootstrap resampling (if enabled)\n\nThe extrapolation factor (t) represents the ratio of hypothetical total reads to actual observed reads. Values of t ≤ 1 correspond to **interpolation** (between observed data points), while t \u003e 1 represents **extrapolation** (prediction beyond observed depth).\n\nFor a given coverage level:\n\n- At t = 1: prediction matches observed CpGs\n- As t increases: predictions approach the theoretical asymptote (maximum CpGs at infinite depth)\n\n### Downsample Approach\n\nTo calculate the **sequencing saturation** of an DNAm sample when using the `downsample` command, we adopt the following strategy. For each sample, we downsample it according to 4 different percentages (default: `0.1,0.2,0.4,0.6,0.8`). Then, we compute the number of **unique CpGs covered by at least 3 reads** and the **number of reads** at each downsampling percentage.\n\nWe then fit the following curve using the `scipy.optimize.curve_fit` function:\n\n$$\ny = \\beta_0 \\cdot \\arctan(\\beta_1 \\cdot x)\n$$\n\nWe chose the **arctangent function** because it exhibits an **asymptotic growth** similar to sequencing saturation.\nFor large values of $\\text{x}$ (as $\\text{x} \\to \\infty$), the asymptote corresponds to the theoretical maximum number of **unique CpGs covered by at least 3 reads** and can be computed as:\n\n$$\n\\text{asymptote} = \\beta_0 \\cdot \\frac{\\pi}{2}\n$$\n\nFinally, the **sequencing saturation value** can be calculated as following:\n\n$$\n\\text{Saturation} = \\frac{\\text{Number of unique CpGs (≥3 counts)}}{\\text{Asymptote}}\n$$\n\nThis approach allows estimation of the theoretical **maximum number of CpGs** that can be detected given an infinite sequencing depth, and quantifies how close the sample is to reaching sequencing saturation.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvibtobilab%2Fmethurator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvibtobilab%2Fmethurator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvibtobilab%2Fmethurator/lists"}