update docs

docs/.buildinfo

@@ -0,0 +1,4 @@
+# Sphinx build info version 1
+# This file records the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: d98f966c84b1d975a1817e646e42fccc
+tags: 645f666f9bcd5a90fca523b33c5a78b7

docs/_sources/index.rst.txt

@@ -0,0 +1,31 @@
+Welcome to the LIgO documentation!
+======================================
+
+LIgO is a Python tool for simulation of adaptive immune receptors (AIRs) and repertoires (AIRRs) with known ground-truth immune signals for the development and benchmarking of AIRR-based machine learning. To get started using LigO right now, check out our :doc:`quickstart` tutorial.
+
+.. image:: ./_static/figures/ligo_pipeline.png
+
+Why should you use LIgO?
+---------------------------------
+* LIgO makes **simulations reproducible**, all simulation parameters are specified through a YAML file. 
+* LIgO contains **different types of immune events and immune signals**, including (gapped) k-mers, PWMs, specific V and J genes.
+* LIgO supports simulation of signal-specific AIRs using **rejection sampling or signal implantation** and **preserves the AIRR generation probability distribution**.
+* LIgO simulates synthetic AIRR (BCRs and TCRs) data both on the **receptor and repertoire level, the single and paired-chain level**.
+* LIgO **guides the user** and helps to set optimal simulation parameters.
+* LIgO outputs detailed information about presence and position(s) of immune signal(s) for every AIR in AIRR-compliant format.  
+
+Please **check out LIgO manuscript** `(biorxiv link) <https://www.biorxiv.org/content/10.1101/2023.10.20.562936v2>`_ for more information!
+
+Contents
+---------------------------------
+
+.. toctree::
+  :maxdepth: 1
+
+  quickstart
+  installation
+  tutorials
+  usecases
+  specification
+
+

docs/_sources/installation.rst.txt

@@ -0,0 +1,185 @@
+Installing LIgO
+===================
+
+.. toctree::
+   :maxdepth: 2
+
+There are two options for installing LIgO:
+
+#. Install on the local machine either from PyPI or from GitHub
+#. Use Docker image
+
+Installing LIgO on the local machine
+---------------------------------
+
+.. note::
+
+  Requirements: Python 3.11 or later
+
+To install LIgO on the local machine with pip:
+
+1. Make a virtual environment where LIgO will be installed to avoid package versioning issues or collisions with the packages installed for other projects:
+
+.. code-block:: console
+
+  python -m venv ligo_env
+
+2. Activate virtual environment:
+
+.. code-block:: console
+
+  source ligo_env/bin/activate
+
+3. Install LIgO from PyPI (recommended):
+
+.. code-block:: console
+
+  pip install ligo
+
+Alternatively, to install LIgO from GitHub run the following:
+
+.. code-block:: console
+
+  pip install git+https://github.com/uio-bmi/ligo.git
+
+4. To be able to export full-length TCR sequences, it is necessary to also download the reference data using Stitchr:
+
+.. code-block:: console
+
+  stitchrdl -s human
+
+For more information on downloading data using Stitchr, see `Stitcher documentation <https://jamieheather.github.io/stitchr/installation.html>`_. Once the Stitchr reference data has been downloaded, LigO will automatically include full-length TCR sequences in the output.
+
+
+Use LIgO with Docker
+----------------------
+
+.. note::
+
+   This tutorial assumes you have Docker installed on your machine. To install it, see `the official Docker documentation <https://docs.docker.com/get-docker/>`_.
+
+Getting started with LIgO and Docker
+********************************************
+
+Once you have Docker working on your machine, put the following content in the specs.yaml in the current working directory:
+
+.. indent with spaces
+.. code-block:: yaml
+
+ definitions:
+    motifs:
+      motif1:
+        seed: AS
+      motif2:
+        seed: G/G
+        max_gap: 2
+        min_gap: 1
+    signals:
+      signal1:
+        v_call: TRBV7
+        motifs: [motif1]
+      signal2:
+        motifs: [motif2]
+    simulations:
+      sim1:
+        is_repertoire: false
+        paired: false
+        sequence_type: amino_acid
+        simulation_strategy: RejectionSampling
+        remove_seqs_with_signals: true # remove signal-specific AIRs from the background
+        sim_items:
+          sim_item1: # group of AIRs with the same parameters
+            generative_model:
+              chain: beta
+              default_model_name: humanTRB
+              model_path: null
+              type: OLGA
+            number_of_examples: 100
+            signals:
+              signal1: 1
+          sim_item2:
+            generative_model:
+              chain: beta
+              default_model_name: humanTRB
+              model_path: null
+              type: OLGA
+            number_of_examples: 100
+            signals:
+              signal2: 1
+          sim_item3:
+            generative_model:
+              chain: beta
+              default_model_name: humanTRB
+              model_path: null
+              type: OLGA
+            number_of_examples: 100
+            signals: {} # no signal
+    instructions:
+      my_sim_inst:
+        export_p_gens: false
+        max_iterations: 100
+        number_of_processes: 4
+        sequence_batch_size: 1000
+        simulation: sim1
+        type: LigoSim
+
+
+Then, use the following command to download and run the Docker image with LIgO analysis. This will do the following:
+
+1. create the Docker container with the given name (here: :code:`my_container`),
+
+2. bind the current working directory to the path /data inside the container which will make the data from the working directory visible inside the container and which will keep the data placed there visible after the container is stopped,
+
+3. run an LIgO analysis using specs.yaml from the current folder and store the output in the new 'output' directory in the current working directory:
+
+.. code-block:: console
+
+  docker run -it -v $(pwd):/data --name my_container milenapavlovic/ligo ligo /data/specs.yaml /data/output/
+
+This analysis will simulate 300 TCR beta receptors and store the results in the `/data/output` folder.
+
+To exit the Docker container, use the following command:
+
+.. code-block:: console
+
+  exit
+
+Using the Docker container for longer LIgO runs
+***************************************************
+
+If you expect the analysis to take more time, you can start the container as a background process. The command to run in that case would be the following:
+
+.. code-block:: console
+
+  docker run -itd -v $(pwd):/data --name my_container milenapavlovic/ligo ligo /data/specs.yaml /data/output/
+
+To see the logs, run the following command with the container name (here: :code:`my_container`):
+
+.. code-block:: console
+
+  docker logs my_container
+
+To see the list of available containers, you can use the following command:
+
+.. code-block:: console
+
+  docker ps -a
+
+If you just started the container with the previous command, the output showing the list of available containers should look similar to this:
+
+.. code-block:: console
+
+  CONTAINER ID        IMAGE                     COMMAND             CREATED             STATUS              PORTS               NAMES
+  e799e644e479        milenapavlovic/ligo   "/bin/bash"         34 seconds ago      Up 33 seconds                           my_container
+
+To stop the container, run the following command where the argument is the name of your container:
+
+.. code-block:: console
+
+  docker stop my_container
+
+To delete the container, run the following command where the argument is the name of your container:
+
+.. code-block:: console
+
+  docker rm my_container

docs/_sources/quickstart.rst.txt

@@ -0,0 +1,37 @@
+Quickstart
+==========
+
+How to run LIgO
+---------------------------------
+
+You can run LIgO in the command line using the following command:
+
+.. code-block:: console
+
+  ligo specs.yaml output_folder
+
+Where
+
+* **specs.yaml** — simulation parameters described by the user in a yaml file. Please see :doc:`specification` for more information about LIgO parameters.
+* **output_folder** — output folder name defined by the user (should not exist before the run). 
+
+How to explore LIgO results
+---------------------------------
+
+The output folder structure is the same for all LIgO runs. The output folder should include:
+
+- **index.html**: main output file which gives an overview of the simulation: link to the full specification, the used LIgO version, some general information on the dataset and the link to the dataset exported in the standard AIRR format
+- **full_specs.yaml** file: includes the specification and default parameters if any of the parameters were left unfilled
+- **inst1** folder: this folder name is the same as the name given to the instruction by the user; all results are located here; the simulated dataset is located under `inst1/exported_dataset/airr/`
+- **HTML_output** folder: presentation of figures and reports if specified
+
+
+Quickstart tutorials
+---------------------------------
+
+
+.. toctree::
+  :maxdepth: 1
+
+  quickstart/receptor_level_simulation
+  quickstart/repertoire_level_simulation