RepLikCompare
==============

**RepLikCompare** is a Python package for working with Molecular
Dynamics data: dataset loading, clustering, dimensionality reduction,
plotting, and ensemble (replica/system) comparison workflows.

Most functionality is exposed directly on the
:class:`~RepLikCompare.dataset.Dataset` class, which wraps a pandas
DataFrame carrying simulation/replica metadata and mixes in plotting,
clustering, dimensionality-reduction, and ensemble-comparison methods.
A dataset can be created from an existing pandas DataFrame or loaded
directly from a CSV file:

.. code-block:: python

   import RepLikCompare as rlc

   # From an existing pandas DataFrame
   dataset = rlc.Dataset.from_dataframe(df)

   # Or directly from a CSV file
   dataset = rlc.Dataset.from_csv("df.csv")

The input dataset must contain two columns identifying, respectively,
the **system** (e.g. ``WT`` vs ``Mutant``) and the **replica** within
that system (e.g. ``1``, ``2``, ``3``). See
:class:`~RepLikCompare.dataset.Dataset` for auto-detection rules and
how to pass these column names explicitly.

Capabilities
------------

.. list-table::
   :header-rows: 1
   :widths: 20 30 50

   * - Module
     - Key functions
     - What it does
   * - :doc:`user_guide/plotting`
     - ``plot_scatter``, ``plot_free_energy``, ``plot_lineplot_avg``,
       ``plot_distri_norm``, ``plot_vonmises``, ``plot_rmsd``,
       ``plot_rmsf``, ``plot_contact_map``, ``plot_cluster_timeline``,
       ``compute_secondary_structure_timeline``
     - Scatter/line/distribution plots, free-energy landscapes,
       RMSD/RMSF and contact-map plots, and cluster/secondary-structure
       timelines -- most with a faceted (per-system) variant.
   * - :doc:`user_guide/clustering`
     - ``compute_cluster_kmean``, ``compute_cluster_GMM``,
       ``compute_cluster_dbscan``, ``compute_cluster_hdbscan``,
       ``hierarchical_clustering``, ``assign_cluster_representative``
     - Cluster conformations with K-means, GMM, DBSCAN, HDBSCAN, or
       hierarchical clustering, and pick a representative frame per
       cluster.
   * - :doc:`user_guide/dimensionality_reduction`
     - ``compute_pca``, ``compute_umap``, ``compute_tsne``,
       ``compute_kpca``
     - Reduce a set of numeric features to a low-dimensional embedding
       (PCA, UMAP, t-SNE, kernel PCA), with optional support for
       circular/angular features.
   * - :doc:`user_guide/ensemble_comparison`
     - ``compute_jsd``, ``compute_wasserstein``, ``compute_convergence``
     - Statistically compare feature distributions across systems and
       replicas (Jensen-Shannon divergence, Wasserstein distance) and
       check trajectory convergence.

Authors
-------

* Alaa REGUEI, PhD Student -- Universite Paris Cite, BFA.
* Samuel Murail, Associate Professor -- Universite Paris Cite, BFA.

.. toctree::
   :maxdepth: 2
   :caption: Getting started
   :hidden:

   getting_started/installation

.. toctree::
   :maxdepth: 2
   :caption: User Guide
   :hidden:

   user_guide/tutorial
   user_guide/plotting
   user_guide/clustering
   user_guide/dimensionality_reduction
   user_guide/ensemble_comparison