# RSAND CLI — Relational Systemwide Asymmetric Network of Dispersion
**Relational Systemwide Asymmetric Network of Dispersion**  
Version **1.0.4**

[![Crates.io](https://img.shields.io/crates/v/rsand.svg?logo=crates.io)](https://crates.io/crates/rsand)
[![Crates.io downloads](https://img.shields.io/crates/d/rsand?color=green&label=crates.io%20downloads)](https://crates.io/crates/rsand)
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.18347261.svg)](https://doi.org/10.5281/zenodo.18347261)



<!-- SVG image below the logo -->

<p align="center">
  <img src="readme/rsand_readme_final_2l_logo.svg" width="500" />
</p>

SAND is a Rust-based, command-line toolkit to infer network of dominance dispersion of a conditional system using CLR normalization, asymmetric regression, power-law analysis, and Cartesian eco-network mapping.

---

## ⚡ Features

| Command     | Description                                                                                 |
| ----------- | ------------------------------------------------------------------------------------------- |
| **spun**    | CLR/Log/Abundance normalization of compositional Omics data tables.                         |
| **plaw**    | Power-law detection and system structure distribution analysis.                          |
| **weave**   | Direction & Sign inference using asymmetric regression + metadata-conditioned perturbation. |
| **ecocart** | Eco-Cartesian network plot generation.                                                      |
| **oss**     | One-Step-System pipeline (spun → weave → ecocart).                                          |

---

## 📦 Installation

Download the latest release binary from the repository:
```bash
cargo install rsand
```

```bash
rsand -h

# CLR normalize
rsand spun -i otu.tsv -o clr.csv -f clr

# Powerlaw analysis
rsand plaw -i clr.csv -m meta.csv -mc Condition -o dist

# Direction & sign inference
rsand weave -i clr.csv -m meta.csv -mc Condition:Case -mp 10 -t 0.05

# Eco-network chart
rsand ecocart -i weave_output.csv -m Case -o network.svg

# Full pipeline
rsand oss -i otu.tsv -m meta.csv -mc Condition -o results
```

## Example datasets

This repository does not include third-party datasets directly.

To obtain the example genus-level abundance tables used for demonstrating
the SAND workflow, run:

    ./datasets/data_download.sh

This script downloads the publicly available genus-level MetaPhlAn abundance
files from the BenRossLab/T6SS-Loss project (original authors). These data
are used only as example input to illustrate how SAND processes compositional
tables and is not redistributed in this repository.

The metadata CSVs included here (hmp\_metadata.csv, kostic\_metadata.csv,
vatanen\_metadata.csv, yassour\_metadata.csv) were created entirely by the
authors of this tool to demonstrate categorical stratification workflows.

### After downloading

The downloaded files are provided in Excel (.xlsx) format by the original authors. SAND requires TSV formatted abundance tables, so users must convert the Excel files to TSV using any standard method.

In addition, the datasets contain column names with extra suffixes (e.g., \_metaphlan\_....txt). Users should ensure to remove those and only retain the sample id's alone. If unsure, refer to the included metadata files for the correct column header naming conventions (make sure the columns headers in the datamatrix matches the index of metadata file ).

Metadata files

The metadata CSV files included in this repository (hmp\_metadata.csv, kostic\_metadata.csv, vatanen\_metadata.csv, yassour\_metadata.csv) were created entirely by the authors of this project to demonstrate presence/absence stratification within the SAND workflow. These metadata files contain only categorical labels constructed for this example and do not reuse any sensitive or copyrighted materials.

## Ecocart Visualisation

<p align="center">
  <img src="readme/final_ecocart_anime_with_data.svg" width="900" />
</p>

## Citation

This software and its visualizations are part of academic research.
If you use *rsand* or its ideas in scholarly work, please cite:
DOI: 10.5281/zenodo.18347261 
See `CITATION.cff` for machine-readable citation metadata.
