Skip to content
motleystatePublic

Repository files navigation

Moonstone

Python package Documentation Status codecov

Moonstone aims to provide a way of performing analysis of metagenomics counts from raw data to statistical analysis and visualization of the results.

Thus, in moonstone you will find:

  • parsers for common file types for metagenomics counts
  • modules for cleaning and filtering your data
  • normalization modules
  • analysis modules
  • plot modules

The main idea is to keep track of every steps applied to a raw data to be able to easily share the analysis and reproduce it.

Please check our documentation for more information.

Install moonstone

You can install moonstone either as a user (to use the tool as-is) or as a developer (to work directly on the code). We recommend using Mamba (a faster drop-in replacement for Conda) to manage environments.

🧪 User Installation

Moonstone requires Python 3.13. If you only want to use moonstone and don't need to edit the source code:

# Create and activate a Python 3.13 environment
mamba create -n moonstone python=3.13 -y
conda activate moonstone

# Install the latest release of moonstone from PyPI
pip install moonstone

# Check the installation
moonstone --help

To try changes that are not released yet, install from GitHub instead: pip install "git+https://github.com/motleystate/moonstone.git". Releases from 1.5.0 onwards require Python 3.13; on older Python versions, pip installs moonstone 1.0.0.

🛠️ Developer Installation

To work directly with the code and have your changes reflected automatically, follow these steps:

# Clone the repository
git clone https://github.com/motleystate/moonstone.git
cd moonstone

# Create a development environment
mamba create -n moonstone-dev python=3.13 -y
conda activate moonstone-dev

# Install Moonstone in editable mode, with the development tools
pip install -e . -r requirements-dev.txt

# Run the test suite
pytest

Without Mamba or Conda, a standard virtual environment works too: python3.13 -m venv .venv && source .venv/bin/activate, then run the same pip install command.


Quickstart with moonstone on the command-line

More detailed documentation is available on the documentation.

Moonstone is directly callable from your terminal for available built-in analysis scripts:

(moonstone) $ moonstone --help
usage: moonstone countfile, metadata file, output directory [options]

Microbiota Analysis Scripts for Machine LEarning

positional arguments:
  countfile             Normalized count file input
  metadata              Clinical data input file
  outdir                Output files directory

options:
  -h, --help            show this help message and exit
  -os, --skip_prompt    Suppress output directory exists prompt.
  -f, --filtering min_mean_read
                        Minimum mean reads per variable: use a float >0
  -c, --classify variable
                        Cross-validated classification of a metadata variable
                        from the counts
  --model {svm,random_forest} [{svm,random_forest} ...]
                        Classifier(s) for --classify: Support Vector Machine
                        and/or random forest (default: svm)
  --kernel {linear,poly,rbf,sigmoid,auto}
                        Support Vector Machine kernel; auto picks one by
                        nested cross-validation (default: linear)
  --explore_kernels     With --classify, compare Support Vector Machine
                        kernels (exploratory scores)
  --folds FOLDS         Number of cross-validation folds (default: 5)
  --seed SEED           Random seed for folds and models (default: 0)
  --group_column column
                        Metadata column naming the subject of each sample;
                        keeps a subject in one fold
  --roc                 With --classify, plot Receiver Operating
                        Characteristic curves
  --feature_selection   With --classify, select features by nested recursive
                        feature elimination

For example, moonstone counts.csv metadata.csv output --classify disease --model svm random_forest --roc runs a 5-fold stratified cross-validation of both classifiers. Scores are balanced accuracy and the area under the Receiver Operating Characteristic (ROC) curve, measured on samples the model did not see during training.


Development guide

To work on a new feature, related or not to an issue, we open a new branch from the development (currently master) branch to work on it.

If an issue is opened, we recommend to name your branch with the issue number at the begining, e.g. 5-my-new-feature

Once done, work is reviewed through a pull request.

Releases

Packages

Contributors

Languages