Licence Build Status

Ymir

Probabilistic models of immune receptors assembling


Overview

Features

Paper

Details

Undetailed dependencies. For more information on dependencies see Installing and using Ymir subsection.


Installing and using Ymir

You can use Ymir in two ways:

Compiling Ymir

Note: you can see detailed installation of dependencies in next sections.

Dependencies:

Installation on Ubuntu

Open your Terminal.

Install CMake and Pythons with

sudo apt-get install cmake
sudo apt-get install python
sudo apt-get install python3

Other installation steps (JsonCPP and compiling) are equal to those for Mac users.

Installation on Mac OS

Open your Terminal.

Install Homebrew by typing this into the Terminal:

ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

After that you need to install CMake and Pythons with the following commands:

brew install cmake
brew install python
brew install python3

At this point you can either install the JsonCPP library and download benchmark files by yourself (see next paragraphs) or simply go to Ymir's GitHub, download the latest release source code called Source_code_FULL.zip and unzip it. You will see the new folder called ymir. In both ways to compile Ymir you need to make your Terminal point to Ymir's folder.

To install JsonCPP you should clone the repository and install JsonCPP library by the following commands:

git clone https://github.com/imminfo/ymir.git
cd ymir
curl -sL https://github.com/open-source-parsers/jsoncpp/archive/master.zip > jsoncpp.zip
unzip jsoncpp.zip
rm jsoncpp.zip
cd jsoncpp-master
python amalgamate.py
mv ./dist/jsoncpp.cpp ../Ymir/src/jsoncpp.cpp
mv ./dist/json ../include/json
cd ..

And now, finally when you are in Ymir's folder, you can compile Ymir:

mkdir build
cd build
cmake -DCMAKE_BUILD_TYPE=Release ..
cmake --build . && cd ..

It will build a number of Ymir programs to run: tests, benchmarks and ready-to-use scripts.

You can test Ymir with running

python3 ytest.py

For benchmarks you need to download benchmark files (if you haven't download Source_code_FULL.zip):

    curl -sL https://github.com/imminfo/ymir/releases/download/v1.0-pre3/benchmark-files.zip > benchmark-files.zip 
    unzip benchmark-files.zip
    rm benchmark-files.zip 
    mv benchmark-files/ ./benchmark/data/
    rm -r benchmark-files

To run benchmarks execute

    python3 ybenchmark.py

To see how you can use pre-made scripts go to the Examples / ready-to-use scripts section.

Using Ymir as a library

Ymir is a header only library, however, you need to put the jsoncpp.cpp file to the Ymir/src folder.

In your CMakeLists.txt files you should put include_directories(include) if Ymir's folder is in the include directory.

Next text is assumed that your include path is setted to $YMIR_FOLDER/.

For using only the core data structures MAAG and MAAGBuilder add:

    #include <Ymir/Graph>

For computing and generation assembling probabilities from files:

    #include <Ymir/Model>

For the statistical inference of marginal parameters of generation models:

    #include <Ymir/Inference>

For super secret unimplemented things:

    #include <Ymir/Pattern>

Wow-wow, easy here. They are not implemented yet.


Main helper script

python3 pyymir.py


Examples / ready-to-use scripts

After compiling an executable files will appear in the build folder.

You can download sample files with outputs from tcR package and MiTCR software with

curl -sL https://github.com/imminfo/ymir/releases/download/v1.0-pre3/example-files.zip > examples.zip unzip examples.zip

Compute generation probabilities of human TCR-alpha data from tcR output files

The most common task with generation probabilities is to compute them.

python3 compute.py -i -f -m [-o ] [-p] [-l]

Note: run python3 compute.py -h to see a help message.

Example command to compute generation probabilities from tcR file:

python3 compute.py -i ./examples/tcr.htra.txt -f tcr -m htra

Estimate human TCR-beta generation model parameters using EM-algorithm from MiTCR output files

python3 inference.py -i ??? -f mitcr -m htrb

Note: run python3 inference.py -h to see a help message.

Example command to perform statistical inference from MiTCR file:

python3 inference.py -i ./examples/mitcr.htrb.txt -f mitcr -m htrb

Run python3 pyymir.py -m to view all available models and their aliases.

Generate artificial human TCR-alpha repertoire before selection

python3 generate.py -c 500000 -m htra

Note: run python3 generate.py -h to see a help message.

asdasd


Types of input files and their formats

Model files

Main JSON file

Gene segments files

Event probability files

Cloneset files

Available parsers

Reminder: run python3 pyymir.py -f to view all available formats and their aliases.


Benchmarks


For full documentation visit mkdocs.org.

mkdocs.yml # The configuration file. docs/ index.md # The documentation homepage. ... # Other markdown pages, images and other files.