# MutClust: Efficient and Scalable Mutual Rank-Based Coexpression Clustering
**MutClust** is a Python tool for efficient and scalable mutual rank-based gene coexpression analyses. The clustering analysis is conducted using [ClusterONE](https://paccanarolab.org/clusterone/), as described in [Wisecaver *et al.* 2017](https://academic.oup.com/plcell/article-abstract/29/5/944/6099316). MutClust is still under development.
---
## Features
- **Mutual Rank Analysis:** Compute mutual rank (MR) from Pearson correlations on your gene expression matrix.
- **ClusterONE Clustering:** Identify gene coexpression clusters from filtered/weighted MR networks.
- **Fast:** Multi-threaded, sparse matrix operations for speed on large datasets.
---
## Installation
### Recommended
**Install MutClust:** Create the recommended conda environment:
```bash
conda env create -f environment.yml
conda activate mutclust
```
### Alternative
**Step 1:** Make sure that ClusterONE is available from the command line:
```bash
conda install bioconda::clusterone
```
**Step 2a:** Install MutClust from PyPI:
```bash
pip install mutclust
```
**Step 2b:** Or clone the repository from GitHub:
```bash
git clone https://github.com/eporetsky/mutclust.git
cd mutclust
pip install .
```
## Usage
### 1. Calculate Mutual Rank (MR)
```bash
mutclust mr -i expr.tsv -o results.mrs.tsv.gz --mr-threshold 100 --threads 4 [--log2]
```
| Argument | Short | Description | Default |
|------------------|-------|-----------------------------------------------------|---------------|
| --input | -i | Path to the RNA-seq dataset (.tsv/.tsv.gz) | **Required** |
| --output | -o | Output file for mutual rank pairs | **Required** |
| --mr-threshold | -m | MR threshold for reporting gene pairs | 100 |
| --threads | -t | Number of CPU threads (correlation) | 4 |
| --log2 | | If set, applies log2(x+1) before calculation | OFF by default|
- Input: Genes as rows, samples as columns (TSV, row index 'geneID').
- Output: Gzipped tab-separated file containing `Gene1`, `Gene2`, `MR`.
### 2. Cluster Genes (with ClusterONE)
```bash
mutclust cls -i results.mrs.tsv.gz -o results.cls.tsv --e_value 10
```
| Argument | Short | Description | Default |
|------------------|-------|-----------------------------------------------------|---------------|
| --input | -i | Path to Mutual Rank (MR) pairs (.tsv/.tsv.gz) | **Required** |
| --output | -o | Output file for clusters (.tsv) | **Required** |
| --e_value | -e | Exponential decay constant for edge weighting | 10 |
- The tool filters/weights MR pairs and calls ClusterONE for clustering.
- Output: `clusters.tsv`, listing clusters with p-value < 0.1. Tab-separated file containing `clusterID`, `geneID`, `pval`.
---
## Example Workflow
```bash
mutclust mr -i data/myexpr.tsv -o out.mrs.tsv.gz --mr-threshold 100 --threads 72 --log2
mutclust cls -i out.mrs.tsv.gz -o out.clusters.tsv --e_value 10
```
---
## Input Format
Expression file:
```
geneID\tSample1\tSample2\n...
GeneA \t1.1 \t2.2
GeneB \t4.2 \t3.7
```
Note: MutClust might be limited to linux because of dependency on pynetcor.
---
## Coming Soon
- Generate cluster gene annotation
- Calculate cluster GO term enrichment
- Calculate clusteer eigen-gene data
- Add a MutClust Dockerfile
- Add unit testing
---
## License
MIT License. See LICENSE file for details.
---
## Contributing
Suggestions, pull requests, and issues welcome!
Raw data
{
"_id": null,
"home_page": null,
"name": "MutClust",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "bioinformatics, coexpression, mutual rank, clustering, RNA-seq",
"author": null,
"author_email": "Elly Poretsky <eporetsky@plantapp.org>",
"download_url": "https://files.pythonhosted.org/packages/14/d5/be7f0c1021dbc65392220bcd2b8c21c2219a7691f227c678491661111906/mutclust-0.1.4.tar.gz",
"platform": null,
"description": "# MutClust: Efficient and Scalable Mutual Rank-Based Coexpression Clustering\n\n**MutClust** is a Python tool for efficient and scalable mutual rank-based gene coexpression analyses. The clustering analysis is conducted using [ClusterONE](https://paccanarolab.org/clusterone/), as described in [Wisecaver *et al.* 2017](https://academic.oup.com/plcell/article-abstract/29/5/944/6099316). MutClust is still under development.\n\n---\n\n## Features\n- **Mutual Rank Analysis:** Compute mutual rank (MR) from Pearson correlations on your gene expression matrix.\n- **ClusterONE Clustering:** Identify gene coexpression clusters from filtered/weighted MR networks.\n- **Fast:** Multi-threaded, sparse matrix operations for speed on large datasets.\n\n---\n\n## Installation\n\n### Recommended\n\n**Install MutClust:** Create the recommended conda environment:\n```bash\nconda env create -f environment.yml\nconda activate mutclust\n```\n\n### Alternative\n\n**Step 1:** Make sure that ClusterONE is available from the command line:\n```bash\nconda install bioconda::clusterone\n```\n\n**Step 2a:** Install MutClust from PyPI:\n```bash\npip install mutclust\n```\n\n**Step 2b:** Or clone the repository from GitHub:\n```bash\ngit clone https://github.com/eporetsky/mutclust.git\ncd mutclust\npip install .\n```\n\n## Usage\n\n### 1. Calculate Mutual Rank (MR)\n\n```bash\nmutclust mr -i expr.tsv -o results.mrs.tsv.gz --mr-threshold 100 --threads 4 [--log2]\n```\n\n| Argument | Short | Description | Default |\n|------------------|-------|-----------------------------------------------------|---------------|\n| --input | -i | Path to the RNA-seq dataset (.tsv/.tsv.gz) | **Required** |\n| --output | -o | Output file for mutual rank pairs | **Required** |\n| --mr-threshold | -m | MR threshold for reporting gene pairs | 100 |\n| --threads | -t | Number of CPU threads (correlation) | 4 |\n| --log2 | | If set, applies log2(x+1) before calculation | OFF by default|\n\n- Input: Genes as rows, samples as columns (TSV, row index 'geneID').\n- Output: Gzipped tab-separated file containing `Gene1`, `Gene2`, `MR`.\n\n### 2. Cluster Genes (with ClusterONE)\n\n```bash\nmutclust cls -i results.mrs.tsv.gz -o results.cls.tsv --e_value 10\n```\n\n| Argument | Short | Description | Default |\n|------------------|-------|-----------------------------------------------------|---------------|\n| --input | -i | Path to Mutual Rank (MR) pairs (.tsv/.tsv.gz) | **Required** |\n| --output | -o | Output file for clusters (.tsv) | **Required** |\n| --e_value | -e | Exponential decay constant for edge weighting | 10 |\n\n- The tool filters/weights MR pairs and calls ClusterONE for clustering.\n- Output: `clusters.tsv`, listing clusters with p-value < 0.1. Tab-separated file containing `clusterID`, `geneID`, `pval`.\n\n---\n\n## Example Workflow\n\n```bash\nmutclust mr -i data/myexpr.tsv -o out.mrs.tsv.gz --mr-threshold 100 --threads 72 --log2\nmutclust cls -i out.mrs.tsv.gz -o out.clusters.tsv --e_value 10\n```\n\n---\n\n## Input Format\n\nExpression file:\n```\ngeneID\\tSample1\\tSample2\\n...\nGeneA \\t1.1 \\t2.2\nGeneB \\t4.2 \\t3.7\n```\n\nNote: MutClust might be limited to linux because of dependency on pynetcor.\n\n---\n\n## Coming Soon\n- Generate cluster gene annotation\n- Calculate cluster GO term enrichment\n- Calculate clusteer eigen-gene data\n- Add a MutClust Dockerfile\n- Add unit testing\n\n---\n\n## License\nMIT License. See LICENSE file for details.\n\n---\n\n## Contributing\nSuggestions, pull requests, and issues welcome!\n",
"bugtrack_url": null,
"license": null,
"summary": "MutClust: Mutual rank-based coexpression and clustering.",
"version": "0.1.4",
"project_urls": null,
"split_keywords": [
"bioinformatics",
" coexpression",
" mutual rank",
" clustering",
" rna-seq"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "15351414434356704498f2c6eed9bf79dd1c31086b4d72182a343f4c9e7de627",
"md5": "c080504a0d840395a1e54f688572d9be",
"sha256": "32afe8468e921094c8dbb34a83ccaa03289b523af68598e42ef01ae1cf505185"
},
"downloads": -1,
"filename": "mutclust-0.1.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c080504a0d840395a1e54f688572d9be",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 7481,
"upload_time": "2025-10-22T04:00:44",
"upload_time_iso_8601": "2025-10-22T04:00:44.045509Z",
"url": "https://files.pythonhosted.org/packages/15/35/1414434356704498f2c6eed9bf79dd1c31086b4d72182a343f4c9e7de627/mutclust-0.1.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "14d5be7f0c1021dbc65392220bcd2b8c21c2219a7691f227c678491661111906",
"md5": "fea4fa34ed5315a4f1f649e6cbac2360",
"sha256": "3ba5e98c950edcbaeaa0b8008cf5375d923704c637a31fef7a97463e7e9efe4e"
},
"downloads": -1,
"filename": "mutclust-0.1.4.tar.gz",
"has_sig": false,
"md5_digest": "fea4fa34ed5315a4f1f649e6cbac2360",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 6796,
"upload_time": "2025-10-22T04:00:45",
"upload_time_iso_8601": "2025-10-22T04:00:45.152031Z",
"url": "https://files.pythonhosted.org/packages/14/d5/be7f0c1021dbc65392220bcd2b8c21c2219a7691f227c678491661111906/mutclust-0.1.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-22 04:00:45",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "mutclust"
}
JSON