immuneml
immuneML is a platform for machine learning analysis of adaptive immune receptor repertoire data.
Science Score: 57.0%
This score indicates how likely this project is to be science-related based on various indicators:
-
○CITATION.cff file
-
✓codemeta.json file
Found codemeta.json file -
✓.zenodo.json file
Found .zenodo.json file -
✓DOI references
Found 2 DOI reference(s) in README -
○Academic publication links
-
✓Committers with academic emails
2 of 18 committers (11.1%) from academic institutions -
✓Institutional organization owner
Organization uio-bmi has institutional domain (www.mn.uio.no) -
○JOSS paper metadata
-
○Scientific vocabulary similarity
Low similarity (16.9%) to scientific vocabulary
Keywords
Repository
immuneML is a platform for machine learning analysis of adaptive immune receptor repertoire data.
Basic Info
- Host: GitHub
- Owner: uio-bmi
- License: agpl-3.0
- Language: Python
- Default Branch: master
- Homepage: https://immuneml.uio.no
- Size: 197 MB
Statistics
- Stars: 68
- Watchers: 12
- Forks: 30
- Open Issues: 0
- Releases: 17
Topics
Metadata Files
README.md
immuneML
immuneML is a platform for machine learning-based analysis and classification of adaptive immune receptors and repertoires (AIRR).
It supports the analyses of experimental B- and T-cell receptor data, as well as synthetic data for benchmarking purposes.
In immuneML, users can define flexible workflows supporting different machine learning libraries (such as scikit-learn or PyTorch), benchmarking of different approaches, numerous reports of data characteristics, ML algorithms and their predictions, and visualizations of results.
Additionally, users can extend the platform by defining their own data representations, ML models, reports and visualizations.
Useful links: - Main website: https://immuneml.uio.no - Documentation: https://docs.immuneml.uio.no - Documentation for the latest (unstable) version (development branch): https://uio-bmi.github.io/immuneML/ - Galaxy web interface: https://galaxy.immuneml.uiocloud.no
Installation
We recommend installing immuneML inside a virtual environment. immuneML uses Python 3.9 or later. If using immuneML simulation, Python 3.11 or later is recommended. immuneML can be installed directly using a package manager such as pip or conda, or set up via docker.
Quick installation (immuneML essentials):
bash
python3 -m venv ./immuneml_venv/
source ./immuneml_venv/bin/activate
pip install wheel
pip install immune-ml
or
bash
conda create --prefix immuneml_env/ python=3.11
conda activate immuneml_env/
conda install -c bioconda immuneml
Detailed installation (immuneML extras):
Please check the documentation for more detailed instructions or how to install optional dependencies.
Validating the installation
To validate the installation, run:
bash
immune-ml -h
This should display a help message explaining immuneML usage.
To quickly test out whether immuneML is able to run, try running the quickstart command:
bash
immune-ml-quickstart ./quickstart_results/
This will generate a synthetic dataset and run a simple machine machine learning analysis
on the generated data. The results folder will contain two sub-folders: one for the generated dataset (synthetic_dataset)
and one for the results of the machine learning analysis (machine_learning_analysis).
The files named specs.yaml are the input files for immuneML that describe how to generate
the dataset and how to do the machine learning analysis. The index.html files can be used
to navigate through all the results that were produced.
Usage
Quickstart
The quickest way to familiarize yourself with immuneML usage is to follow one of the Quickstart tutorials. These tutorials provide a step-by-step guide on how to use immuneML for a simple machine learning analysis on an adaptive immune receptor repertoire (AIRR) dataset, using either the command line tool or the Galaxy web interface.
Overview of immuneML analyses
The figure below shows an overview of immuneML usage.
All parameters for an immuneML analysis are defined in the YAML specification file.
In this file, the settings of the analysis components are defined (also known as definitions,
shown in different colors in the figure).
Additionally, the YAML file describes one or more instructions, which are workflows that are
applied to the defined analysis components.
See also: documentation of the YAML specification.
Each instruction produces different types of results, including trained ML models, ML model predictions on a given dataset, plots or other reports describing the dataset or trained models, or synthetic/simulated datasets. These results can be navigated through the summary HTML file. See also: tutorials for specific immuneML use cases.
Command line usage
The immune-ml command takes only two parameters: the YAML specification file and a result path.
An example is given here:
bash
immune-ml path/to/specification.yaml result/folder/path/
Results of an immuneML run
For each instruction specified in the YAML specification file, a subfolder is created in the
result/folder/path. Each subfolder will contain:
- An index.html file which shows an overview of the results produced by that instruction. Inspecting the results of an immuneML analysis typically starts here.
- A copy of the used YAML specification (full_specification.yaml) with all default parameters explicitly set.
- A log file (log.txt).
- A folder containing the imported dataset(s) in immuneML format.
- A folder containing all raw results produced by the instruction.
Support
We will prioritize fixing important bugs, and try to answer any questions as soon as possible. Please note we are only 2 people maintaining the platform with occasional absences.
When experiencing an issue, please take the following steps:
Make sure the latest version of immuneML is installed. immuneML is under constant development, and the issue you experience may already be resolved in the latest version of the platform.
Check the 'troubleshooting' page in the immuneML documentation. Any known issues and their solutions are already described there.
If you are still experience a problem and suspect a bug in immuneMl, you can report an issue on GitHub. Please make sure to include the following information:
- The YAML specification you tried to run.
- The full output log file (log.txt).
- A list of dependency versions (can be retrieved with pip list or conda list).
- We primarily test immuneML using Unix-based operating systems, please make sure to mention it if you're using Windows.
- We will be able to help you fastest if you can also provide a small reproducible example, such as a very small dataset for which your run fails.
If this does not answer your question, you can contact us via:
- Twitter @immuneml
- Email contact@immuneml.uio.no
Citing immuneML
If you are using immuneML in any published work, please cite:
Pavlović, M., Scheffer, L., Motwani, K. et al. The immuneML ecosystem for machine learning analysis of adaptive immune receptor repertoires. Nat Mach Intell 3, 936–944 (2021). https://doi.org/10.1038/s42256-021-00413-z
© Copyright 2021-2022, Milena Pavlovic, Lonneke Scheffer, Keshav Motwani, Victor Greiff, Geir Kjetil Sandve
Owner
- Name: Centre for Bioinformatics, University of Oslo
- Login: uio-bmi
- Kind: organization
- Location: Oslo, Norway
- Website: https://www.mn.uio.no/sbi/english/
- Twitter: unioslo_bioinfo
- Repositories: 34
- Profile: https://github.com/uio-bmi
The hub of bioinformatics and computational biology at the University of Oslo
GitHub Events
Total
- Issues event: 8
- Watch event: 7
- Delete event: 19
- Issue comment event: 4
- Member event: 3
- Push event: 376
- Pull request event: 22
- Fork event: 1
- Create event: 14
Last Year
- Issues event: 8
- Watch event: 7
- Delete event: 19
- Issue comment event: 4
- Member event: 3
- Push event: 376
- Pull request event: 22
- Fork event: 1
- Create event: 14
Committers
Last synced: about 2 years ago
Top Committers
| Name | Commits | |
|---|---|---|
| pavlovicmilena | m****5@g****m | 764 |
| Lonneke Scheffer | l****6@l****l | 210 |
| Keshav Motwani | k****2@g****m | 41 |
| Dmytro Titov | d****t@i****o | 18 |
| dtitov | d****v@g****m | 10 |
| Milena Pavlovic | m****a@M****l | 6 |
| Enrico Riccardi | e****2@g****m | 1 |
| Rune | r****5@g****m | 1 |
| Milena Misic | m****3@g****m | 1 |
| ivargr | i****n@g****m | 1 |
| slabodkin | a****n@g****m | 1 |
| rofrank | r****2@g****m | 1 |
| radmilak | r****o@i****o | 1 |
| Knut Dagestad Rand | k****d@g****m | 1 |
| Ping-Han Hsieh | d****7@g****m | 1 |
| zhaoqiang wang | z****g@g****m | 1 |
| Chakravarthi Kanduri | K****C | 1 |
| ghadialhajj | 6****j | 1 |
Committer Domains (Top 20 + Academic)
Issues and Pull Requests
Last synced: 6 months ago
All Time
- Total issues: 18
- Total pull requests: 124
- Average time to close issues: 14 days
- Average time to close pull requests: 15 days
- Total issue authors: 10
- Total pull request authors: 14
- Average comments per issue: 1.78
- Average comments per pull request: 0.3
- Merged pull requests: 102
- Bot issues: 0
- Bot pull requests: 0
Past Year
- Issues: 5
- Pull requests: 17
- Average time to close issues: 1 day
- Average time to close pull requests: about 6 hours
- Issue authors: 2
- Pull request authors: 3
- Average comments per issue: 0.6
- Average comments per pull request: 0.06
- Merged pull requests: 14
- Bot issues: 0
- Bot pull requests: 0
Top Authors
Issue Authors
- sandve (4)
- KanduriC (4)
- pavlovicmilena (2)
- Genokarma (2)
- agirgis3 (1)
- kvegesan-stjude (1)
- LonnekeScheffer (1)
- FsheriF (1)
- CokieLee (1)
- schristley (1)
Pull Request Authors
- LonnekeScheffer (90)
- pavlovicmilena (20)
- mmamica (5)
- EnricoRiccardi (3)
- knutdrand (2)
- ghadialhajj (2)
- theomannen (2)
- IsakMV (1)
- slabodkin (1)
- alxcost (1)
- jskimmeland (1)
- MathiBK (1)
- dn070017 (1)
- alexwang2013 (1)
Top Labels
Issue Labels
Pull Request Labels
Packages
- Total packages: 2
-
Total downloads:
- pypi 555 last-month
-
Total dependent packages: 0
(may contain duplicates) -
Total dependent repositories: 1
(may contain duplicates) - Total versions: 50
- Total maintainers: 1
pypi.org: immuneml
immuneML is a software platform for machine learning analysis of immune receptor repertoires.
- Homepage: https://github.com/uio-bmi/immuneML
- Documentation: https://immuneml.readthedocs.io/
- License: GNU Affero General Public License v3
-
Latest release: 3.0.15
published 9 months ago
Rankings
Maintainers (1)
pypi.org: immuneml-dev
immuneML is a software platform for machine learning analysis of immune receptor repertoires.
- Homepage: https://github.com/uio-bmi/immuneML
- Documentation: https://immuneml-dev.readthedocs.io/
- License: GNU Affero General Public License v3
-
Latest release: 0.0.5
published over 2 years ago
Rankings
Maintainers (1)
Dependencies
- actions/checkout v2 composite
- docker/build-push-action v2 composite
- docker/login-action v1 composite
- actions/checkout v2 composite
- actions/setup-python v2 composite
- ubuntu 20.04 build