# NWnet

**Repository Path**: mselab_admin/nwnet

## Basic Information

- **Project Name**: NWnet
- **Description**: A bioinformatics tool for pangenome analysis based on the Newman-Watts small-world network model.
- **Primary Language**: Unknown
- **License**: GPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-24
- **Last Updated**: 2026-10-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# NWNet

**Small-world network based orthogroup inference.**

NWNet infers orthogroups from protein FASTA files (one file per genome) through a four-stage pipeline. To avoid the quadratic cost of all-against-all sequence comparison, NWNet builds a Newman–Watts–Strogatz small-world graph over the input genomes and aligns proteins only along the edges of this graph; a graph-based network-optimization step then recovers orthologs that the sparse initial alignment would otherwise miss.

## Key features

- **Small-world sparsification** — at the default neighbourhood size (k = n/4), NWNet removes roughly 70% of the genome-pair comparisons while keeping the genome graph connected and every genome sampled at least k times.
- **Four network filters** — reciprocal best hit (RBH), a fixed cutoff, and graph-based refinement with a median/MAD fallback (GBR, GBR_MAD).
- **Adaptive Markov clustering** — global MCL or adaptive MCL with a per-component inflation interpolated from the copy-number ratio (proteins per covered genome).
- **Main-tier accuracy** — on the Quest for Orthologs 2022 benchmark, NWNet reaches precision comparable to scalability-oriented methods such as FastOMA.

## Installation

NWNet requires Python ≥ 3.10.

```bash
pip install nwnet
```

The Python dependencies are installed automatically; the external alignment, clustering and
phylogenetics tools listed below must be installed separately and be on `PATH`.

To install from source instead (for development):

```bash
git clone https://github.com/MSE-Lab/NWNet.git
cd NWNet
pip install -e ".[dev]"
pytest
```

## Dependencies

### Python libraries (installed automatically by pip)

| Library | Minimum version | Purpose |
| :--- | :--- | :--- |
| `igraph` | 0.11 | Graph construction, connected components, and network representation |
| `numpy` | 1.24 | Numerical computation |
| `matplotlib` | 3.7 | Plotting |

### External tools (install separately; must be on `PATH`)

| Tool | Required for | Purpose |
| :--- | :--- | :--- |
| [DIAMOND](https://github.com/bbuchfink/diamond) | `nwnet run` | Protein alignment (default backend) |
| [NCBI BLAST+](https://blast.ncbi.nlm.nih.gov/) (`blastp`) | `nwnet run` | Optional alternative backend (`--align-method blastp`) |
| [MCL](https://micans.org/mcl/) | `nwnet run` | Graph clustering |
| [MAFFT](https://mafft.cbrc.jp/alignment/software/) | `nwnet phylo` | Single-gene alignment |
| [trimAl](https://github.com/inab/trimal) | `nwnet phylo` | Alignment trimming |
| [FastTree](http://www.microbesonline.org/fasttree/) | `nwnet phylo` | Tree inference |

## Quick start

```bash
nwnet run \
  --input-dir /path/to/protein_fastas \
  --output-dir /path/to/result \
  --threads 32
```

The input is a directory of protein FASTA files, one per genome. The orthogroups are written to `result/Orthogroups/Orthogroups.txt`.

## Usage

NWNet provides four subcommands:

- **`nwnet run`** — the full orthology pipeline (small-world network → alignment → network optimization → clustering → orthogroup output).
- **`nwnet compare`** — evaluate the agreement between two orthogroup sets (adjusted Rand index, adjusted/normalized mutual information, Fowlkes–Mallows index, V-measure, and split/merge statistics).
- **`nwnet pan`** — pangenome analysis: classify orthogroups into core/softcore/shell/cloud, fit the pangenome accumulation curve (Heaps' law), and produce visualisations.
- **`nwnet phylo`** — build a supermatrix species tree from single-copy core orthogroups (MAFFT + trimAl + FastTree).

Key options for `nwnet run`:

```
--network-method {RBH,cutoff,GBR,GBR_MAD}   base network filter (default: RBH)
--weighting      {identity,bitscore,evalue,normbitscore}
                                            edge weighting (default: normbitscore)
--k              n                          neighbourhood size (default: n/4)
--p              p                          random long-range edge probability (default: 0.2)
--mcl-mode       {global,adaptive}          clustering mode (default: adaptive)
--inflation      i                          MCL inflation (default: 1.2)
```

Run `nwnet run --help` for the complete list of options.

## Documentation

- [`nwnet run` user guide](https://github.com/MSE-Lab/NWNet/blob/master/docs/nwnet-run-user-guide.md) — the orthology inference pipeline
- [`nwnet compare` user guide](https://github.com/MSE-Lab/NWNet/blob/master/docs/nwnet-compare-user-guide.md) — compare two orthogroup sets
- [`nwnet pan` user guide](https://github.com/MSE-Lab/NWNet/blob/master/docs/nwnet-pan-user-guide.md) — pangenome analysis
- [`nwnet phylo` user guide](https://github.com/MSE-Lab/NWNet/blob/master/docs/nwnet-phylo-user-guide.md) — species-tree reconstruction

The guides are also shipped inside the source distribution under `docs/`.
The release history is in [CHANGELOG.md](https://github.com/MSE-Lab/NWNet/blob/master/CHANGELOG.md).

## Citation

The NWNet manuscript is in preparation. Until it appears, please cite the software itself:

> Lu Y-F, Zhi X-Y. NWNet: small-world network based orthogroup inference. Version 0.1.0.
> https://github.com/MSE-Lab/NWNet

This entry will be replaced by the paper upon publication.

## License

NWNet is licensed under the GNU General Public License v3 (GPL-3.0-or-later).
See [LICENSE](https://github.com/MSE-Lab/NWNet/blob/master/LICENSE).

Contact: Xiao-Yang Zhi ([xyzhi@ynu.edu.cn](mailto:xyzhi@ynu.edu.cn)).