<commit_before>.. _meta:
.. currentmodule:: mixtape

Mixtape API Patterns
====================

Mixtape API
-----------

Hyperparamters
~~~~~~~~~~~~~~
Models in mixtape inherit from base classes in `scikit-learn
<http://scikit-learn.org/stable/>`_, and follow a similar API. Like sklearn,
each type of model is a python class. Hyperparameters are passed in via
the ``__init__`` method and set as instance attributes.

.. code-block:: python

    from mixtape.tica import tICA
    tica = tICA(gamma=0.05)
    tica.fit(...)

    # change gamma and refit. the old state will be discarded
    tica.gamma = 0.01
    tica.fit(...)

Fit Signature
~~~~~~~~~~~~~
The heavy lifting to actually fit the model is done in ``fit()``. In mixtape the
``fit()`` method always accepts a ``list`` of 2-dimensional arrays as input data,
where each array represents a single timeseries / trajectory and has a shape of
``(length_of_trajectory, n_features)``. Some models can also accept a list of
MD trajectories (:class:`~md.Trajectory`) as opposed to a list of arrays.


.. code-block:: python
    dataset = [np.load('traj-1-features.npy'), np.load('traj-2-featues.npy')]
    assert dataset[0].ndim == 2 and dataset[1].ndim == 2

    clusterer = KCenters(n_clusters=100)
    clusterer.fit(dataset)

.. note::

    This is different from sklearn. In sklearn, estimators take a **single**
    2D array as input in ``fit()``. Here we use a list of trajectories.

Learned Attributes
~~~~~~~~~~~~~~~~~~
Parameters of the model which are **learned or estimated** during ``fit()``
are always set as instance attributed that are named with a trailing underscore

.. code-block:: python

    tica = tICA(gamma=0.05)
    tica.fit(...)

    # timescales is an estimated quantity, so it ends in an underscore
    print(tica.timescales_)


Transformers
~~~~~~~~~~~~
Many models also implement a transform() method, which apply a transformation
to a dataset. [TODO: WRITE ME]

Pipelines
---------

The models in mixtape are designed to work together as part of a
:class:`sklearn.pipeline.Pipeline`

.. code-block:: python

    from mixtape.cluster import KMeans
    from mixtape.markovstatemodel import MarkovStateModel
    from sklearn.pipeline import Pipeline
    pipeline = Pipeline([
        ('cluster': KMeans(n_clusters=100)),
        ('msm': MarkovStateModel())
    ])<commit_msg>make the code examples valid<commit_after>.. _meta:
.. currentmodule:: mixtape

Mixtape API Patterns
====================

Mixtape API
-----------

Hyperparamters
~~~~~~~~~~~~~~
Models in mixtape inherit from base classes in `scikit-learn
<http://scikit-learn.org/stable/>`_, and follow a similar API. Like sklearn,
each type of model is a python class. Hyperparameters are passed in via
the ``__init__`` method and set as instance attributes.

.. code-block:: python

    from mixtape.tica import tICA
    tica = tICA(gamma=0.05)
    tica.fit(...)

    # change gamma and refit. the old state will be discarded
    tica.gamma = 0.01
    tica.fit(...)

Fit Signature
~~~~~~~~~~~~~
The heavy lifting to actually fit the model is done in ``fit()``. In mixtape the
``fit()`` method always accepts a ``list`` of 2-dimensional arrays as input data,
where each array represents a single timeseries / trajectory and has a shape of
``(length_of_trajectory, n_features)``. Some models can also accept a list of
MD trajectories (:class:`~md.Trajectory`) as opposed to a list of arrays.


.. code-block:: python
    dataset = [np.load('traj-1-features.npy'), np.load('traj-2-featues.npy')]
    assert dataset[0].ndim == 2 and dataset[1].ndim == 2

    clusterer = KCenters(n_clusters=100)
    clusterer.fit(dataset)

.. note::

    This is different from sklearn. In sklearn, estimators take a **single**
    2D array as input in ``fit()``. Here we use a list of trajectories.

Learned Attributes
~~~~~~~~~~~~~~~~~~
Parameters of the model which are **learned or estimated** during ``fit()``
are always set as instance attributed that are named with a trailing underscore

.. code-block:: python

    tica = tICA(gamma=0.05)
    tica.fit(...)

    # timescales is an estimated quantity, so it ends in an underscore
    print(tica.timescales_)


Transformers
~~~~~~~~~~~~
Many models also implement a transform() method, which apply a transformation
to a dataset. [TODO: WRITE ME]

Pipelines
---------

The models in mixtape are designed to work together as part of a
:class:`sklearn.pipeline.Pipeline`

.. code-block:: python

    from mixtape.cluster import KMeans
    from mixtape.markovstatemodel import MarkovStateModel
    from sklearn.pipeline import Pipeline
    pipeline = Pipeline([
        ('cluster', KMeans(n_clusters=100)),
        ('msm', MarkovStateModel())
    ])
{'fraction_non_alphanumeric': 0.13810633340393985, 'fraction_numerical': 0.00974369836898962, 'mean_word_length': 3.6430678466076696, 'pattern_counts': {'":': 0, '<': 5, '<?xml version=': 0, '>': 5, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1504896', 'n_tokens_mistral': 1473, 'n_tokens_neox': 1388, 'n_words': 538}