Merge pull request #108 from wilhelm-lab/feature/api

Feature/api

.cookietemple.yml

@@ -15,5 +15,5 @@ full_name: Victor Giurcoiu
 email: [email protected]
 project_name: oktoberfest
 project_short_description: Public repo oktoberfest
-version: 0.4.0
+version: 0.5.0
 license: MIT

.flake8

@@ -1,11 +1,11 @@
 [flake8]
 select = B,B9,C,D,DAR,E,F,N,RST,S,W
-ignore = E203,E501,RST201,RST203,RST301,W503,D100,D212,S404,S602,B905
+ignore = E203,E501,RST201,RST203,RST301,RST304,W503,D100,D212,S404,S602,B905
 max-line-length = 120
 max-complexity = 10
 docstring-convention = google
 per-file-ignores =
 	tests/*:S101
-	oktoberfest/__init__.py:F401
+	**/__init__.py:F401,F403
         docs/conf.py:S404,S607,S603
 docstring_style = sphinx

.github/release-drafter.yml

@@ -1,5 +1,5 @@
-name-template: "0.4.0 🌈" # <<COOKIETEMPLE_FORCE_BUMP>>
-tag-template: 0.4.0 # <<COOKIETEMPLE_FORCE_BUMP>>
+name-template: "0.5.0 🌈" # <<COOKIETEMPLE_FORCE_BUMP>>
+tag-template: 0.5.0 # <<COOKIETEMPLE_FORCE_BUMP>>
 exclude-labels:
     - "skip-changelog"
 

.gitignore

@@ -52,6 +52,12 @@ coverage.xml
 .hypothesis/
 .pytest_cache/
 
+# ignore unit test data folder
+tests/unit_tests/data/mokapot/**
+!tests/unit_tests/data/mokapot/*.tab
+!tests/unit_tests/data/predictions/
+
+
 # Translations
 *.mo
 *.pot
@@ -71,6 +77,7 @@ instance/
 
 # Sphinx documentation
 docs/_build/
+docs/api/
 
 # PyBuilder
 target/
@@ -139,3 +146,8 @@ dmypy.json
 
 # Used by ProteomicsDB runs to describe the oktoberfest version
 hash.file
+
+
+# output files in tutorials folder
+tutorials/
+!tutorials/Oktoberfest Tutorial.ipynb

.readthedocs.yml

@@ -3,19 +3,20 @@
 
 version: 2
 
-# Build documentation in the docs/ directory with Sphinx
+# Set the OS, Python version and other tools you might need
+build:
+    os: ubuntu-22.04
+    tools:
+        python: "3.10"
+
+# Build documentation in the "docs/" directory with Sphinx
 sphinx:
     configuration: docs/conf.py
 
-# Build documentation with MkDocs
-#mkdocs:
-#  configuration: mkdocs.yml
-
 # Optionally build your docs in additional formats such as PDF and ePub
 formats: all
 
 # Optionally set the version of Python and requirements required to build your docs
 python:
-    version: 3.8
     install:
         - requirements: docs/requirements.txt

Dockerfile

@@ -25,12 +25,10 @@ ADD poetry.lock /root/poetry.lock
 RUN poetry install --no-root
 
 # install percolator
-RUN ZIP=ubuntu.tar.gz && \
-    wget https://github.com/percolator/percolator/releases/download/rel-3-05/$ZIP -O /tmp/$ZIP && \
-    tar xvzf /tmp/$ZIP && \
-    chmod -R 755 /tmp/* && \
-    dpkg -i percolator-v3-05-linux-amd64.deb && \
-    rm /tmp/$ZIP
+RUN DEB=percolator-v3-06-linux-amd64.deb && \
+    wget https://github.com/percolator/percolator/releases/download/rel-3-06-01/$DEB -O /tmp/$DEB && \
+    dpkg -i /tmp/$DEB && \
+    rm /tmp/$DEB
 
 # install ThermoRawFileParser
 RUN ZIP=ThermoRawFileParser1.4.2.zip && \

README.rst

@@ -1,3 +1,6 @@
+Oktoberfest: Rescoring and Spectral Library Generation for Proteomics
+=====================================================================
+
 |PyPI| |Python Version| |License| |Read the Docs| |Build| |Tests| |Codecov| |pre-commit| |Black|
 
 .. |PyPI| image:: https://img.shields.io/pypi/v/oktoberfest.svg
@@ -28,9 +31,6 @@
    :target: https://github.com/psf/black
    :alt: Black
 
-Oktoberfest: Rescoring and Spectral Library Generation for Proteomics
-=====================================================================
-
 Oktoberfest is a python tool for rescoring search results and generating spectral libraries for proteomics research within the Prosit ecosystem. It offers an end to end pipeline that takes search results, predicts peptide properties using koina, plots summaries and quality control figures and performs FDR estimation with either mokapot or percolator.
 
 Installation
@@ -41,11 +41,14 @@ Prerequisites
 
 Oktoberfest requires python >=3.8,<=3.11. Best practise is to use a clean conda environment (`Miniconda <https://docs.conda.io/en/latest/miniconda.html>`_).
 
-If you provide thermo raw files, make sure `ThermoRawFileParser <https://github.com/compomics/ThermoRawFileParser>`_ is installed.
+If you provide RAW files, you need ThermoRawFileParser for conversion to mzML.
+Please download the latest release from the `github repository <https://github.com/compomics/ThermoRawFileParser>`_ using the provided zip file and unpack it in the desired location.
+On linux and MacOS, the default location is "/opt/compomics/". On Windows, the default location is the directory from which Oktoberfest is executed.
+You can provide the location of the executable in the config file when starting an Oktoberfest run.
 
-If you are on linux or MacOS, make sure `mono <https://www.mono-project.com/>`_ is installed.
+To make ThermoRawFileParser work on linux or MacOS, make sure mono `mono <https://www.mono-project.com/>`_ is installed.
 
-If you want to use percolator, make sure you install version 3.05 (`percolator <https://github.com/percolator/percolator/releases/tag/rel-3-05>`_).
+If you want to use percolator for rescoring, make sure you install version 3.06.1 (`percolator <https://github.com/percolator/percolator/releases/tag/rel-3-06-01>`_).
 
 Using pip (recommended)
 ~~~~~~~~~~~~~~~~~~~~~~~
@@ -58,8 +61,8 @@ Docker image
 ~~~~~~~~~~~~
 
 Prerequisites:
-- `make <https://www.gnu.org/software/make/>`_
-- `docker <https://www.docker.com/>`_
+  - `make <https://www.gnu.org/software/make/>`_
+  - `docker <https://www.docker.com/>`_
 
 After cloning the repository of oktoberfest, checkout the branch you want to build the container from.
 The latest stable version is always on the main branch.

ReadMe.md

@@ -16,11 +16,14 @@
 
 Oktoberfest requires python >=3.8,<=3.11. Best practise is to use a clean conda environment (https://docs.conda.io/en/latest/miniconda.html).
 
-If you provide thermo raw files, make sure ThermoRawFileParser(https://github.com/compomics/ThermoRawFileParser) is installed.
+If you provide RAW files, you need ThermoRawFileParser for conversion to mzML.
+Please download the latest release from the github repository (https://github.com/compomics/ThermoRawFileParser) using the provided zip file and unpack it in the desired location.
+On linux and MacOS, the default location is "/opt/compomics/". On Windows, the default location is the directory from which Oktoberfest is executed.
+You can provide the location of the executable in the config file when starting an Oktoberfest run.
 
-If you are on linux or MacOS, make sure mono (https://www.mono-project.com/) is installed.
+To make ThermoRawFileParser work on linux or MacOS, make sure mono (https://www.mono-project.com/) is installed.
 
-If you want to use percolator, make sure you install version 3.05 (https://github.com/percolator/percolator/releases/tag/rel-3-05)
+If you want to use percolator for rescoring, make sure you install version 3.06.1 (https://github.com/percolator/percolator/releases/tag/rel-3-06-01).
 
 ### Using pip (recommended)
 

cookietemple.cfg

@@ -1,5 +1,5 @@
 [bumpversion]
-current_version = 0.4.0
+current_version = 0.5.0
 
 [bumpversion_files_whitelisted]
 init_file = oktoberfest/__init__.py

docs/API.rst

@@ -1,9 +1,117 @@
-API (under development)
-=======================
+.. module:: oktoberfest
 
-.. toctree::
-   :maxdepth: 4
+.. automodule:: oktoberfest
+   :noindex:
 
-   oktoberfest
-   oktoberfest.data
-   oktoberfest.utils
+API
+===
+
+Import Oktoberfest using
+
+.. code-block:: python
+
+   import oktoberfest as ok
+
+Preprocessing: :code:`pp`
+-------------------------
+
+.. module:: oktoberfest.pp
+
+.. currentmodule:: oktoberfest
+
+Generating libraries
+
+.. autosummary::
+   :toctree: api/pp
+
+   pp.digest
+   pp.gen_lib
+   pp.merge_spectra_and_peptides
+
+Spectra preprocessing
+
+.. autosummary::
+   :toctree: api/pp
+
+   pp.list_spectra
+   pp.convert_spectra
+   pp.load_spectra
+
+
+Peptide preprocessing
+
+.. autosummary::
+   :toctree: api/pp
+
+   pp.convert_search
+   pp.load_search
+   pp.filter_peptides
+
+
+Predicting: :code:`pr`
+----------------------
+
+.. module:: oktoberfest.pr
+
+.. currentmodule:: oktoberfest
+
+All things predictions
+
+Koina interface
+~~~~~~~~~~~~~~~
+
+.. autosummary::
+   :toctree: api/pr
+
+   pr.grpc_predict
+   pr.infer_predictions
+
+Postprocessing koina response
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. autosummary::
+   :toctree: api/pr
+
+
+   pr.parse_fragment_labels
+
+
+Rescoring: :code:`re`
+---------------------
+
+.. module:: oktoberfest.re
+
+.. currentmodule:: oktoberfest
+
+General
+~~~~~~~
+
+.. autosummary::
+   :toctree: api/re
+
+   re.generate_features
+   re.merge_input
+   re.rescore_with_mokapot
+   re.rescore_with_percolator
+
+
+Plotting: :code:`pl`
+---------------------
+
+.. module:: oktoberfest.pl
+
+.. currentmodule:: oktoberfest
+
+General
+~~~~~~~
+
+.. autosummary::
+   :toctree: api/pl
+
+   pl.plot_score_distribution
+   pl.joint_plot
+   pl.plot_gain_loss
+   pl.plot_mean_sa_ce
+   pl.plot_violin_sa_ce
+   pl.plot_pred_rt_vs_irt
+   pl.plot_all

docs/_static/custom_cookietemple.css

@@ -13,19 +13,32 @@ table.align-default {
 }
 
 .fixed-table th:first-child,
-.fixed-table td:first-child {
+.fixed-table td:first-child,
+.autosummary th:first-child,
+.autosummary td:first-child {
     min-width: 250px;
 }
 
+.autosummary th:first-child,
+.autosummary td:first-child {
+    min-width: 400px;
+}
+
 .fixed-table th:last-child,
-.fixed-table td:last-child {
+.fixed-table td:last-child,
+.autosummary th:last-child,
+.autosummary td:last-child {
     width: 100%;
 }
 
 .fixed-table {
     margin-left: 0;
 }
 
+.autosummary {
+    margin-left: 0 !important;
+}
+
 .main-config-table tbody tr:nth-child(n + 4):nth-child(-n + 5) td:nth-child(1) {
     padding-left: 50px;
 }

docs/_templates/autosummary/base.rst

@@ -0,0 +1,5 @@
+:github_url: {{ fullname | modurl }}
+
+{% extends "!autosummary/base.rst" %}
+
+.. http://www.sphinx-doc.org/en/stable/ext/autosummary.html#customizing-templates