Metadata-Version: 2.4
Name: aaanalysis
Version: 1.1.0
Summary: Python framework for interpretable protein prediction
Author-email: Stephan Breimann <stephanbreimann@gmail.de>
License: BSD-3-Clause
Project-URL: Homepage, https://aaanalysis.readthedocs.io
Project-URL: Repository, https://github.com/breimanntools/aaanalysis
Project-URL: Documentation, https://aaanalysis.readthedocs.io
Keywords: protein,prediction,bioinformatics,machine learning,interpretable AI
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Natural Language :: English
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: License :: OSI Approved :: BSD License
Classifier: Development Status :: 5 - Production/Stable
Requires-Python: >=3.10
Description-Content-Type: text/x-rst
License-File: LICENSE
Requires-Dist: cycler>=0.12.1
Requires-Dist: et-xmlfile>=2.0.0
Requires-Dist: fonttools>=4.56.0
Requires-Dist: Jinja2>=3.1.6
Requires-Dist: joblib>=1.4.2
Requires-Dist: kiwisolver>=1.4.7
Requires-Dist: logomaker>=0.8.6
Requires-Dist: matplotlib>=3.5.3
Requires-Dist: numpy>=1.24.4
Requires-Dist: openpyxl>=3.1.5
Requires-Dist: packaging>=26.1
Requires-Dist: pandas>=2.2.3
Requires-Dist: patsy>=1.0.1
Requires-Dist: Pillow>=12.3.0
Requires-Dist: pyparsing>=3.2.1
Requires-Dist: python-dateutil>=2.9.0
Requires-Dist: pytz>=2024.2
Requires-Dist: scikit-learn>=1.6.1
Requires-Dist: scipy>=1.13.1
Requires-Dist: seaborn>=0.13.2
Requires-Dist: six>=1.17.0
Requires-Dist: threadpoolctl>=3.5.0
Provides-Extra: pro
Requires-Dist: biopython>=1.87; extra == "pro"
Requires-Dist: shap>=0.46.0; extra == "pro"
Requires-Dist: UpSetPlot>=0.9.0; extra == "pro"
Requires-Dist: requests>=2.0; extra == "pro"
Requires-Dist: afragmenter>=0.0.6; extra == "pro"
Requires-Dist: py3Dmol>=2.0; extra == "pro"
Requires-Dist: ipywidgets>=8.0.0; extra == "pro"
Provides-Extra: embed
Requires-Dist: torch>=2.13.0; extra == "embed"
Requires-Dist: transformers>=4.40; extra == "embed"
Requires-Dist: sentencepiece>=0.2; extra == "embed"
Requires-Dist: huggingface_hub>=0.23; extra == "embed"
Provides-Extra: bench
Requires-Dist: pytest-benchmark>=4.0; extra == "bench"
Provides-Extra: docs
Requires-Dist: aaanalysis[pro]; extra == "docs"
Requires-Dist: docutils==0.21.2; extra == "docs"
Requires-Dist: nbconvert>=7.17.0; extra == "docs"
Requires-Dist: nbformat==5.10.4; extra == "docs"
Requires-Dist: nbsphinx==0.9.6; extra == "docs"
Requires-Dist: numpydoc==1.8.0; extra == "docs"
Requires-Dist: sphinx==8.1.3; extra == "docs"
Requires-Dist: sphinx-autodoc-typehints==1.15.0; extra == "docs"
Requires-Dist: sphinx-copybutton==0.5.2; extra == "docs"
Requires-Dist: sphinx_design==0.6.1; extra == "docs"
Requires-Dist: sphinx_rtd_theme==3.0.2; extra == "docs"
Requires-Dist: sphinxext-opengraph==0.9.1; extra == "docs"
Requires-Dist: urllib3>=2.7.0; extra == "docs"
Requires-Dist: ipywidgets>=8.0.0; extra == "docs"
Provides-Extra: dev
Requires-Dist: aaanalysis[docs]; extra == "dev"
Requires-Dist: black>=26.3.1; extra == "dev"
Requires-Dist: deap>=1.4; extra == "dev"
Requires-Dist: hypothesis>=6.124.7; extra == "dev"
Requires-Dist: ipykernel==6.29.5; extra == "dev"
Requires-Dist: ipython>=8.18.1; extra == "dev"
Requires-Dist: pandoc==2.4; extra == "dev"
Requires-Dist: poetry>=2.0.1; extra == "dev"
Requires-Dist: pytest>=9.0.3; extra == "dev"
Requires-Dist: pytest-cov>=7.1.0; extra == "dev"
Requires-Dist: pytest-xdist>=3.6.0; extra == "dev"
Requires-Dist: pytest-mpl==0.19.0; extra == "dev"
Requires-Dist: mutmut>=3.0; extra == "dev"
Requires-Dist: pyright>=1.1.400; extra == "dev"
Dynamic: license-file

Welcome to the AAanalysis documentation!
========================================
..
    Developer Notes:
    Please make sure that badges in badges.rst (Read The Docs)
    and README.rst (GitHub) are the same.


.. =========================
.. Distribution
.. =========================

.. |License| image:: https://img.shields.io/github/license/breimanntools/aaanalysis.svg
   :target: https://github.com/breimanntools/aaanalysis/blob/master/LICENSE
   :alt: License

.. |PyPI Version| image:: https://img.shields.io/pypi/v/aaanalysis.svg
   :target: https://pypi.org/project/aaanalysis/
   :alt: PyPI - Package Version

.. |Supported Python Versions| image:: https://img.shields.io/pypi/pyversions/aaanalysis.svg
   :target: https://pypi.org/project/aaanalysis/
   :alt: Supported Python Versions

.. |Downloads| image:: https://pepy.tech/badge/aaanalysis
   :target: https://pepy.tech/project/aaanalysis
   :alt: Downloads

.. |GitHub Stars| image:: https://img.shields.io/github/stars/breimanntools/aaanalysis.svg?style=social
   :target: https://github.com/breimanntools/aaanalysis
   :alt: GitHub Stars


.. =========================
.. Status
.. =========================

.. |PyPI Status| image:: https://img.shields.io/pypi/status/aaanalysis.svg
   :target: https://pypi.org/project/aaanalysis/
   :alt: PyPI - Status

.. |Unit Tests| image:: https://github.com/breimanntools/aaanalysis/actions/workflows/main.yml/badge.svg
   :target: https://github.com/breimanntools/aaanalysis/actions/workflows/main.yml
   :alt: CI/CD Pipeline

.. |Codecov| image:: https://codecov.io/gh/breimanntools/aaanalysis/branch/master/graph/badge.svg
   :target: https://codecov.io/gh/breimanntools/aaanalysis
   :alt: Codecov

.. |CodeQL| image:: https://github.com/breimanntools/aaanalysis/actions/workflows/codeql_analysis.yml/badge.svg
   :target: https://github.com/breimanntools/aaanalysis/actions/workflows/codeql_analysis.yml
   :alt: CodeQL


.. =========================
.. Table
.. =========================

.. list-table::
   :widths: 15 85
   :header-rows: 1

   * - **Distribution**
     - |License| |PyPI Version| |Supported Python Versions| |Downloads|
   * - **Status**
     - |PyPI Status| |Unit Tests| |Codecov| |CodeQL| |GitHub Stars|

.. image:: docs/source/_artwork/logos/model_AAanalysis.png
   :alt: Overview of AAanalysis components
   :align: center
   :width: 100%

**AAanalysis** (Amino Acid analysis) is a Python framework for interpretable sequence-based protein prediction.
Its foundation are the following algorithms:

- **CPP**: Comparative Physicochemical Profiling, a feature engineering algorithm comparing two sets of protein
  sequences to identify the set of most distinctive features.
- **dPULearn**: deterministic Positive-Unlabeled (PU) Learning algorithm to enable training on
  unbalanced and small datasets.
- **AAclust**: k-optimized clustering wrapper framework to select redundancy-reduced sets of numerical scales
  (e.g., amino acid scales).

In addition, AAanalysis provide functions for loading various protein benchmark datasets, amino acid scales,
and their two-level classification (**AAontology**). We combined **CPP** with the explainable
AI  `SHAP <https://shap.readthedocs.io/en/latest/index.html>`_ framework to explain sample level predictions with
single-residue resolution.

If you are looking to make publication-ready plots with a view lines of code, see our
`Plotting Prelude <https://aaanalysis.readthedocs.io/en/latest/generated/plotting_prelude.html>`_.


You can find the official documentation at `Read the Docs <https://aaanalysis.readthedocs.io/en/latest/>`_.

Install
=======
**AAanalysis** can be installed from `PyPi <https://pypi.org/project/aaanalysis>`_:

.. code-block:: bash

   pip install aaanalysis

For extended features, including the explainable AI module:

.. code-block:: bash

    pip install "aaanalysis[pro]"

If you use uv, the equivalent commands are:

.. code-block:: bash

    uv pip install aaanalysis
    uv pip install "aaanalysis[pro]"

Contributing
============
We appreciate bug reports, feature requests, or updates on documentation and code. For details, please refer to
`Contributing Guidelines <CONTRIBUTING.rst>`_. These cover AAanalysis development conventions and the automated
quality gates every change must pass. For further questions or suggestions, please email stephanbreimann@gmail.com.

Cheat Sheet
===========
The cheat sheet distills AAanalysis into a three-page summary: the golden workflow, the main
classes grouped by capability, the prediction levels (residue / domain / protein), and the
*Part × Split × Scale* feature ontology. Click the image below to download the PDF.

.. image:: docs/source/_artwork/cheat_sheet_preview.png
   :alt: AAanalysis cheat sheet (page 1 of 3)
   :target: https://raw.githubusercontent.com/breimanntools/aaanalysis/master/docs/source/_static/AAanalysis_cheat_sheet.pdf
   :width: 90%
   :align: center

The AAanalysis Ecosystem
========================
AAanalysis is the interpretable middle layer between bioinformatics I/O and the downstream machine
learning, explainable AI, and protein-design stack. It *consumes* upstream representations (sequences,
embeddings, structures) and even competitor descriptor sets, and runs them through its interpretable
core (*Part × Split × Scale* · AAontology · CPP). Downstream machine-learning and explainable-AI
methods then either *consume* these features directly or are *integrated* into AAanalysis through
wrappers or native implementations — for example SHAP via ``ShapModel``, or machine-learning models
such as random forests via ``TreeModel`` — so the resulting features, explanations, and design
objectives feed straight into the standard ML / XAI / optimization tools.

Click the diagram to view and download the full map, or open the
`ecosystem positioning page <https://aaanalysis.readthedocs.io/en/latest/_static/aaanalysis_ecosystem.html>`_
— a self-contained walkthrough with the map, its introduction, and further background.

.. image:: https://raw.githubusercontent.com/breimanntools/aaanalysis/master/docs/source/_artwork/diagrams/aaanalysis_ecosystem.png
   :alt: The AAanalysis ecosystem — where AAanalysis fits in the protein-ML stack
   :target: https://raw.githubusercontent.com/breimanntools/aaanalysis/master/docs/source/_artwork/diagrams/aaanalysis_ecosystem.svg
   :width: 100%
   :align: center

Decision Map
============
Not sure which tool fits your question? The Decision Map routes you from your biological
task (residue, domain, or protein level, plus determinant discovery and design) to the
right AAanalysis workflow and classes. Click the map to open the full, downloadable
version (PNG / PDF / HTML).

.. image:: https://raw.githubusercontent.com/breimanntools/aaanalysis/master/docs/source/_artwork/diagrams/decision_map.png
   :alt: AAanalysis Decision Map: which tool for which task
   :target: https://aaanalysis.readthedocs.io/en/latest/_static/decision_map.html
   :width: 100%
   :align: center

Data Flow Map
=============
The Data Flow Map shows how the pieces connect end to end: external inputs (sequences,
embeddings, structures, annotations) feed the interpretable CPP core, which turns them
into the feature signature ``df_feat`` and the feature matrix ``X`` that the wrapper
classes use to predict, explain, and design. Click the map to open the full, downloadable
version.

.. image:: https://raw.githubusercontent.com/breimanntools/aaanalysis/master/docs/source/_artwork/diagrams/dataflow_map.png
   :alt: AAanalysis Data Flow Map: how data moves from inputs through CPP to predictions
   :target: https://aaanalysis.readthedocs.io/en/latest/_static/dataflow_map.html
   :width: 100%
   :align: center

Citations
=========
If you use AAanalysis in your work, please cite the respective publication as follows:

**AAclust**:
   Breimann and Frishman (2024a),
   *AAclust: k-optimized clustering for selecting redundancy-reduced sets of amino acid scales*,
   `Bioinformatics Advances <https://academic.oup.com/bioinformaticsadvances/article/4/1/vbae165/7852846>`__.

**AAontology**:
   Breimann *et al.* (2024b),
   *AAontology: An ontology of amino acid scales for interpretable machine learning*,
   `Journal of Molecular Biology <https://www.sciencedirect.com/science/article/pii/S0022283624003267>`__.

**CPP**:
   Breimann and Kamp *et al.* (2025),
   *Charting γ-secretase substrates by explainable AI*,
   `Nature Communications <https://www.nature.com/articles/s41467-025-60638-z>`__.

**dPULearn**:
   Breimann and Kamp *et al.* (2025),
   *Charting γ-secretase substrates by explainable AI*,
   `Nature Communications <https://www.nature.com/articles/s41467-025-60638-z>`__.
