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.
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.
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 --helpTo 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.
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
pytestWithout 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.
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 eliminationFor 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.
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.