Python module
-------------

.. image:: images/inMOTIFin_components.png

The package is following object oriented programming (OOP) principles, and it is organized into three main units: ``modules``, ``organizer``, and ``utils``, 
as shown on a simplified version of `class diagram <https://www.visual-paradigm.com/guide/uml-unified-modeling-language/uml-class-diagram-tutorial/>`_ above.
The classes highlighted in red are available for the user.
The exception under OOP are the ``utils`` submodules, these provide only functions.
Below the exported classes are explained.

===================
Controller class
===================

The ``Controller`` is a main unit that talks with the ``Prepare`` and the ``Sample`` modules.
Its role is to delegate tasks from the user.
When run from the command line, it takes input from ``Main`` (which provides the command line interface and argument reading through ``config_args``).
However, to enable usage from python, it is exposed to the user.

The simulation of motif-in-seq is provided by the ``run_inmotifin()`` function.
Simulation of motifs is provided by the ``create_motifs()`` function.
Simulation of random sequences is provided by the ``create_backgrounds()`` function.
The multimerisation can be achieved with ``create_multimers()`` function.
These functions takes ``Paramsdata`` dataclasses as their inputs, which stores the same information as would be given in the config file or command line options.

Beyond these options, the Controller class has two additional functions for more control over motif-in-seq simulation.
First, ``create_motif_in_seq()`` for adding of motifs into background sequences at specific locations.
This is different from the ``run_inmotifin()`` function because the default motif-in-seq creation is a probabilistic process and does not allow full control over which motif 
gets into which sequence or which location (except central locations).

The second additional functionality, is ``mask_motif_in_seq()`` for adding background sequences to specific positions in a given sequence, thus masking existing motifs.
This is different from the ones above, in that it creates short sequences of backgrounds with the given probability for each letter and adds these into the specified locations.
Note: this does not ensure that no existing motif resembles the added masks.

===================
Additional classes
===================

Beyond pre-existing methods for overall insertion, inMOTIFin allows for creative combination of existing lower level functionalities.
To this end, the ``Motifer``, ``MotifInstancer``, ``Multimerer``, ``Markover``, ``Backgrounder``, ``BackgroundSampler``, ``Shuffler``, ``Grouper``, ``Frequencer``, ``FrequencySampler``, ``Positioner``, 
and ``Inserter`` are providing access to lower level functionalities.
Furthermore, the basic functions of ``onehot_to_str``, ``create_reverse_complement``, ``define_complementary_map_motif_array``, and ``create_reverse_complement_motif`` are available.

========
Examples
========

For examples, please refer to the Python Examples page.

.. toctree::
   :maxdepth: 1

   python_module

=================================
Detailed documentation of classes
=================================

Controller
^^^^^^^^^^

.. autoclass:: inmotifin.Controller
    :members:

Dataclasses for input parameters
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. autoclass:: inmotifin.BasicParams
    :members:

.. autoclass:: inmotifin.MotifParams
    :members:

.. autoclass:: inmotifin.MultimerParams
    :members:

.. autoclass:: inmotifin.BackgroundParams
    :members:

.. autoclass:: inmotifin.GroupParams
    :members:

.. autoclass:: inmotifin.FreqParams
    :members:

.. autoclass:: inmotifin.SamplingParams
    :members:

.. autoclass:: inmotifin.PositionParams
    :members:

Dataclasses for input for sampling
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. autoclass:: inmotifin.Motifs
    :members:

.. autoclass:: inmotifin.Backgrounds
    :members:

.. autoclass:: inmotifin.Groups
    :members:

.. autoclass:: inmotifin.Frequencies
    :members:

.. autoclass:: inmotifin.Positions
    :members:

Simulating data
^^^^^^^^^^^^^^^^^

.. autoclass:: inmotifin.Motifer
    :members:

.. autoclass:: inmotifin.Multimerer
    :members:

.. autoclass:: inmotifin.Backgrounder
    :members:

.. autoclass:: inmotifin.Markover
    :members:

.. autoclass:: inmotifin.Shuffler
    :members:

.. autoclass:: inmotifin.Grouper
    :members:

.. autoclass:: inmotifin.Frequencer
    :members:

Sampling from data
^^^^^^^^^^^^^^^^^^

.. autoclass:: inmotifin.MotifInstancer
    :members:

.. autoclass:: inmotifin.BackgroundSampler
    :members:

.. autoclass:: inmotifin.FrequencySampler
    :members:

.. autoclass:: inmotifin.Positioner
    :members:

.. autoclass:: inmotifin.Inserter
    :members:


Utility classes
^^^^^^^^^^^^^^^^^

.. autoclass:: inmotifin.Reader
    :members:

.. autoclass:: inmotifin.Writer
    :members:

Utility functions
^^^^^^^^^^^^^^^^^

.. autofunction:: inmotifin.onehot_to_str

.. autofunction:: inmotifin.create_reverse_complement

.. autofunction:: inmotifin.define_complementary_map_motif_array

.. autofunction:: inmotifin.create_reverse_complement_motif