Quickstart
----------

==================
Installation
==================

.. admonition:: Under construction

    The package is under construction, therefore the pip and container installations might be lagging behind.
    Clone the main branch from the repository to use the most up to date stable version corresponding to the documentation.

You can install from `pypi <https://pypi.org/project/inMOTIFin/>`_ with the command

``python -m pip install inmotifin``

or pull the container at `dockerhub <https://hub.docker.com/r/cbgr/inmotifin/tags>`_. If you have `docker <https://www.docker.com/>`_ installed, you can run from within the docker container with

``sudo docker run -it cbgr/inmotifin:latest bash``

Altenarively, you can also clone `the inMOTIFin bitbucket repository <https://bitbucket.org/CBGR/inmotifin/src/main/>`_ and install the package locally by ``pip install -e .`` run in the folder where the ``setup.py`` file resides.

A Nextflow module of inMOTIFin is available at the `inMOTIFin evaluation bitbucket repository <https://bitbucket.org/CBGR/inmotifin_evaluation/src/main/modules/local/inmotifin/main.nf>`_.

==================
Command line usage
==================

Simulating sequences with inserted motif instances
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

To simulate 100 backgrounds of length 50, simulate 10 motifs of length 5 and insert 1 instance of a motif at random positions per background sequence:

``python -m inmotifin motif-in-seq --title insert_test``

Simulating random sequences
^^^^^^^^^^^^^^^^^^^^^^^^^^^

To simulate 100 random sequences:

``python -m inmotifin random-sequences --title seq_test``

Simulating motifs
^^^^^^^^^^^^^^^^^^

To simulate 10 motifs of length 5:

``python -m inmotifin motifs --title motifs_test``

To connect given motifs with predefined distances (multimerize):
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Create two files.

First, a motif file in MEME format.
For the description of the format, reference the `The MEME Suite site <https://meme-suite.org/meme/doc/meme-format.html?man_type=web>`_.
The minimal format is expected; background letter frequency and strands information are not used by inMOTIFin.
``motifs.meme`` with content:

.. code-block::

   MEME version 4

   ALPHABET= ACGT

   MOTIF motif_sim_motif_0
   letter-probability matrix: alength= 4 w= 4
   0.993109 0.000061 0.001844 0.004986
   0.391855 0.001010 0.152693 0.454442
   0.040823 0.023752 0.022399 0.913026
   0.812262 0.018175 0.001388 0.168175

   MOTIF motif_sim_motif_1
   letter-probability matrix: alength= 4 w= 4
   0.614586 0.000060 0.070698 0.314656
   0.606263 0.000000 0.162612 0.231125
   0.017036 0.036870 0.511546 0.434548
   0.837547 0.000156 0.002451 0.159846

Second, a tsv file ``multimer_rules.tsv`` with content:

.. code-block::

   motif_sim_motif_0,motif_sim_motif_0,motif_sim_motif_1	1,2
   motif_sim_motif_0,motif_sim_motif_0	-1
   motif_sim_motif_0,motif_sim_motif_1	2

*Note: columns are tab separated. The first column is a list of motif IDs, the second column is the pairwise distance between them. So for 3 motifs 2 distances are expected; for 2 motifs 1 distance is expected.*

Then run:

``python -m inmotifin multimers --title multimers_test --motif_files simulated_motifs.meme --multimerisation_rules multimer_rules.tsv``


===================
Further information
===================

For description of all options and input examples refer to the `Command line options page <https://inmotifin.readthedocs.io/en/latest/usage/command_line_options.html>`_

For advanced usage examples refer to the `Advanced usage page <https://inmotifin.readthedocs.io/en/latest/usage/advanced_usage.html>`_