From c228b6feab47ff7922b7bcf0832bb11867213269 Mon Sep 17 00:00:00 2001 From: RalfG Date: Fri, 20 Oct 2023 09:10:48 -0700 Subject: [PATCH] First merge of both existing docs sites --- CODE_OF_CONDUCT.md | 1 + CONTRIBUTING.md | 115 +-------- Results_Module2_quant_DDA | 1 - docs/_static/css/custom.css | 19 ++ .../proteobench-logo-horizontal-inverted.svg | 150 ++++++++++++ docs/_static/proteobench-logo-horizontal.svg | 159 +++++++++++++ docs/conf.py | 31 ++- docs/developer-guide/adding-module.rst | 110 +++++++++ .../developer-guide/api/proteobench/index.rst | 10 + .../api/proteobench/modules}/dda_quant.rst | 0 .../api/proteobench/modules/index.rst | 17 ++ .../api}/proteobench/template.rst | 0 .../api/webinterface/index.rst} | 0 docs/developer-guide/development-setup.md | 97 ++++++++ docs/developer-guide/index.rst | 18 ++ docs/developer-guide/local-usage.md | 10 + docs/developer-guide/modifying-module.rst | 12 + docs/index.rst | 34 +-- docs/modules/index.rst | 3 + docs/proteobench/modules.rst | 21 -- docs/user-guide/glossary.md | 2 + docs/user-guide/how-to-contribute.md | 5 + docs/user-guide/how-to-use.md | 3 + docs/user-guide/index.rst | 10 + docs/userguide/index.rst | 159 ------------- img/proteobench-favicon.png | Bin 0 -> 362 bytes img/proteobench-icon.svg | 87 +++++++ img/proteobench-logo-as-font.svg | 116 ++++++++++ img/proteobench-logo-horizontal-as-font.svg | 129 +++++++++++ img/proteobench-logo-horizontal-inverted.svg | 150 ++++++++++++ img/proteobench-logo-horizontal.svg | 159 +++++++++++++ img/proteobench-logo-inverted.svg | 218 ++++++++++++++++++ img/proteobench-logo.svg | 146 ++++++++++++ 33 files changed, 1672 insertions(+), 320 deletions(-) create mode 100644 CODE_OF_CONDUCT.md delete mode 160000 Results_Module2_quant_DDA create mode 100644 docs/_static/css/custom.css create mode 100644 docs/_static/proteobench-logo-horizontal-inverted.svg create mode 100644 docs/_static/proteobench-logo-horizontal.svg create mode 100644 docs/developer-guide/adding-module.rst create mode 100644 docs/developer-guide/api/proteobench/index.rst rename docs/{proteobench => developer-guide/api/proteobench/modules}/dda_quant.rst (100%) create mode 100644 docs/developer-guide/api/proteobench/modules/index.rst rename docs/{ => developer-guide/api}/proteobench/template.rst (100%) rename docs/{webinterface/webinterface.rst => developer-guide/api/webinterface/index.rst} (100%) create mode 100644 docs/developer-guide/development-setup.md create mode 100644 docs/developer-guide/index.rst create mode 100644 docs/developer-guide/local-usage.md create mode 100644 docs/developer-guide/modifying-module.rst create mode 100644 docs/modules/index.rst delete mode 100644 docs/proteobench/modules.rst create mode 100644 docs/user-guide/glossary.md create mode 100644 docs/user-guide/how-to-contribute.md create mode 100644 docs/user-guide/how-to-use.md create mode 100644 docs/user-guide/index.rst delete mode 100644 docs/userguide/index.rst create mode 100644 img/proteobench-favicon.png create mode 100644 img/proteobench-icon.svg create mode 100644 img/proteobench-logo-as-font.svg create mode 100644 img/proteobench-logo-horizontal-as-font.svg create mode 100644 img/proteobench-logo-horizontal-inverted.svg create mode 100644 img/proteobench-logo-horizontal.svg create mode 100644 img/proteobench-logo-inverted.svg create mode 100644 img/proteobench-logo.svg diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 00000000..2fe822c7 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1 @@ +# Code of conduct diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6993f95c..a6223ce1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,115 +1,4 @@ # Contributing -This document briefly describes how to contribute to -[ProteoBench](https://github.com/proteobench/proteobench). - - - -## Before you begin - -If you have an idea for a feature, use case to add or an approach for a bugfix, -you are welcome to communicate it with the community by opening a -thread in -[GitHub Discussions](https://github.com/proteobench/proteobench/discussions) -or in [GitHub Issues](https://github.com/proteobench/proteobench/issues). - -Not sure where to start? Great contributions to -[ProteoBench](https://github.com/proteobench/proteobench) include: - -[TODO] - -Also check out the [open issues](https://github.com/proteobench/proteobench/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22+label%3A%22help+wanted%22) -that carry the `good first issue` or `help wanted` labels. - - -## Development setup - -### Local installation -Install the package and dependencies with [Flit](https://flit.pypa.io/en/stable/): - -``` -pip install flit -flit install -s -``` - -Using a virtual environment is recommended. - - -### Unit tests - -To run the tests run the command: - -``` -python -m unittest test/test_module_dda_quant.py -``` - - -### Testing the web interface locally - -Start the web server locally with: - -``` -cd ./webinterface/ -streamlit run Home.py -``` - -This will launch the Proteobench application in your web browser. - - -Changes to the code in `./webinterface` will trigger a reload of the web server. -However, changes in `./proteobench` require a full restart of the webserver -to be included. - - -### Documentation - -To work on the documentation and get a live preview, install the requirements -and run `sphinx-autobuild`: - -``` -flit install -s -sphinx-autobuild --watch ./proteobench ./docs/ ./docs/_build/html/ -``` - -Then browse to http://localhost:8000 to watch the live preview. - - -## How to contribute - -- Fork [ProteoBench](https://github.com/proteobench/proteobench) on GitHub to - make your changes. -- Commit and push your changes to your - [fork](https://help.github.com/articles/pushing-to-a-remote/). -- Ensure that the tests and documentation (both Python docstrings and files in - `/docs/source/`) have been updated according to your changes. Python - docstrings are formatted in the - [numpydoc style](https://numpydoc.readthedocs.io/en/latest/format.html). -- Open a - [pull request](https://help.github.com/articles/creating-a-pull-request/) - with these changes. You pull request message ideally should include: - - - A description of why the changes should be made. - - A description of the implementation of the changes. - - A description of how to test the changes. - -- The pull request should pass all the continuous integration tests which are - automatically run by - [GitHub Actions](https://github.com/proteobench/proteobench/actions). - - - -## Release workflow - -- When a new version is ready to be published: - - 1. Change the `__version__` in `proteobench/__init__.py` following - [semantic versioning](https://semver.org/). - 2. Update the changelog (if not already done) in `CHANGELOG.md` according to - [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - 3. Merge all final changes with the `main` branch. - 4. Create a new release on GitHub. - -- When a new GitHub release is made, the `Publish` GitHub Action is automatically - triggered to build the Python package and publish it to PyPI. Upon a new PyPI release, - the Bioconda automations will automatically update the Bioconda package. However, - if dependencies are changed, the conda recipe will have to be updated accordingly. +Check out the [developer guide](https://proteobench.github.io/developer-guide/) +to learn how you can contribute to ProteoBench. diff --git a/Results_Module2_quant_DDA b/Results_Module2_quant_DDA deleted file mode 160000 index bcd1776d..00000000 --- a/Results_Module2_quant_DDA +++ /dev/null @@ -1 +0,0 @@ -Subproject commit bcd1776dd40b8e1d4fb07e6eccb4df1fce7817f8 diff --git a/docs/_static/css/custom.css b/docs/_static/css/custom.css new file mode 100644 index 00000000..8bca9bdb --- /dev/null +++ b/docs/_static/css/custom.css @@ -0,0 +1,19 @@ +@import url('https://fonts.googleapis.com/css2?family=Open+Sans&family=Roboto+Slab:wght@500&display=swap'); + +html { + --pst-font-family-base: 'Open Sans', sans-serif; + --pst-font-family-heading: 'Roboto Slab', serif; + --pst-font-weight-heading: 500; +} + +/* html[data-theme="light"] { + --pst-color-primary: #3b5880; +} + +html[data-theme="dark"] { + --pst-color-primary: #5c87c2; +} + +a:visited { + color: var(--pst-color-link); +} */ diff --git a/docs/_static/proteobench-logo-horizontal-inverted.svg b/docs/_static/proteobench-logo-horizontal-inverted.svg new file mode 100644 index 00000000..0e31173b --- /dev/null +++ b/docs/_static/proteobench-logo-horizontal-inverted.svg @@ -0,0 +1,150 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/_static/proteobench-logo-horizontal.svg b/docs/_static/proteobench-logo-horizontal.svg new file mode 100644 index 00000000..87c60852 --- /dev/null +++ b/docs/_static/proteobench-logo-horizontal.svg @@ -0,0 +1,159 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/conf.py b/docs/conf.py index 83e6a91b..e315a019 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -1,5 +1,4 @@ project = "ProteoBench" -copyright = "2023, EuBIC-MS" author = "EuBIC-MS" description = "A Python-base platform for benchmarking data analysis in proteomics." @@ -7,14 +6,38 @@ "myst_parser", "sphinx.ext.napoleon", "sphinx.ext.autodoc", + "sphinx.ext.autosectionlabel", "sphinx.ext.autosummary", + "sphinx.ext.intersphinx", "sphinx.ext.viewcode", "sphinx.ext.todo", ] source_suffix = [".rst"] master_doc = "index" -exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] +exclude_patterns = ["_build", "_autosummary", "Thumbs.db", ".DS_Store"] -html_theme = "sphinx_rtd_theme" -# html_static_path = ["_static"] +html_theme = "pydata_sphinx_theme" +html_static_path = ["_static"] +html_css_files = ["css/custom.css"] +html_theme_options = { + "icon_links": [ + { + "name": "GitHub", + "url": "https://github.com/proteobench/proteobench", + "icon": "fa-brands fa-github", + "type": "fontawesome", + } + ], + "logo": { + "image_light": "_static/img/proteobench-logo-horizontal.svg", + "image_dark": "_static/img/proteobench-logo-horizontal-inverted.svg", + }, +} + +# Intersphinx options +intersphinx_mapping = { + "python": ("https://docs.python.org/3", None), + "psims": ("https://mobiusklein.github.io/psims/docs/build/html/", None), + "pyteomics": ("https://pyteomics.readthedocs.io/en/stable/", None), +} diff --git a/docs/developer-guide/adding-module.rst b/docs/developer-guide/adding-module.rst new file mode 100644 index 00000000..9b8ae68c --- /dev/null +++ b/docs/developer-guide/adding-module.rst @@ -0,0 +1,110 @@ +################### +Adding a new module +################### + +Please use the template for adding a new benchmarking module. + +Here we provide a comprehensive overview of how to set up a new module in ProteoBench + + +Naming convention +================= + +We suggest to understand the following terms as they are crucial components: + + **Module**: All code and definitions for creating and comparing benchmarks of a new data type + + **Intermediate data structure** (`DataFrame`): Data structure needed for the calculation of the `datapoint`. It contains + the transformed and annotated data of an uploaded data file. + + **Datapoint**: Metadata and benchmarking metrics for a given data set. A `datapoint` is the + data needed for the benchmarking and should also be represented by a json object. + + +Programmatic structure +====================== + +The modules are located in the `proteobench/modules `\_ directory. We separated the benchmarking modules into a different steps +that allow for a more modular and portable implementation. + +**Backend** + +Each module implementation should contain the following classes: + +1. :func:`~proteobench.modules.template.module.Module` contains the main functions reading the and processing the uploaded data set, generating the _intermediate_ structure and creating the _datapoint_, as well as adding it to our collection of _datapoints_. +2. :func:`~proteobench.modules.template.parse.ParseInputs` interfaces with the Streamlit interface providing formatting parameter definitions to create a standardized format from the uploaded files with respect to the given file format (e.g. MaxQuant output file) +3. :func:`~proteobench.modules.template.datapoint.Datapoint` is the data structure of _Datapoint_. It contains data set properties from the acquisition and processing (e.g. used peptide fdr) and functions to calculate the benchmarking metrics. +4. :func:`~proteobench.modules.template.plot.PlotDataPoint` are the functions to visualize the benchmarking metrics from the data points. +5. :func:`~proteobench.modules.template.parse.ParseInputs` contains the functions to parse the uploaded data files into the _intermediate_ structure. The input file parameters should be defined in the toml file like `proteobench/modules/template/io_parse_settings/parse_settings_format1.toml `\_. + +**Web interface** + +The web interface is written in Streamlit. Each module gets assigned a specific "page". +There are only few changes necessary as the main calculations are done in + +:func:`~webinterface.pages.TEMPLATE.StreamlitUI` contains the functions to create the web interface for the module. + +_Relevant functions:_ + +:func:`~webinterface.pages.TEMPLATE.StreamlitUI.generate_input_field` creates the input fields for the metadate and the +input file format and type. They are given by in the `proteobench/modules/template/io_parse_settings `\_ folder, +same as for the backend of the module. + +:func:`webinterface.pages.TEMPLATE.StreamlitUI.generate_results` gathers the data from the backend +and displays them in several figures. Here you will need to edit and adapt the code +to show the respective figures with the right metadata. + +:func:`webinterface.pages.TEMPLATE.WebpageTexts` contains the text for the different parts of the web interface. + +Change the text and the field names accordingly + +**Documentation** + +We strongly recommend to keep documenting your code. The documentation is written in Sphinx and +can be found in the `docs `\_ folder. + +1. `docs/proteobench/modules.rst `\_ Here you can add a link to your new module +2. `docs/proteobench/template.rst `\_ This template can be used to creat your own documentation file in reStructuredText (rst) format. +3. `docs/webinterface/webinterface.rst `\_ Here you should add a link to the new page in the web interface. + +To work on the documentation and get a live preview, install the requirements and run +`sphinx-autobuild`: + +.. code-block:: sh + + pip install .[docs] + sphinx-autobuild --watch ./ms2rescore ./docs/source/ ./docs/_build/html/ + +Then browse to http://localhost:8000 to watch the live preview. + +.. note:: + + Ensure to have changed all occurrences of ``template`` to the name of your new module. + + +Checklist +========= + +This checklist is meant to help you add a new module to ProteoBench. It is not +meant to be exhaustive, but it should cover the most important steps. + +1. Copy the `template `_ + folder in the `proteobench/modules `_ + directory to a new folder in the same directory. The name of the new directory should be the name + of the module. +2. Define the input formats in the toml files of the `proteobench/modules/my_module/io_parse_settings` + directory and `proteobench.modules.my_module.parse_settings.py`. +3. Modify the upload prodecures in the `proteobench/modules/my_module/parse.py`. This will ensure a + standardized data structure for the benchmarking independently from the input file format. +4. Modify `proteobench/modules/my_module/datapoint.py` to define the requested metadata about the + data acquisition and the benchmarking metrics, all to be stored in a datapoint. You might need to + add some function(s) for further processing the standardized data structure. +5. Modify `proteobench/modules/my_module/plot.py` to create the figures for the web interface. +6. Modify `proteobench/modules/my_module/module.py` to harmonize all procedures called in the + `benchmarking` function. +7. Copy `webinterface.pages.TEMPLATE `\_ + to `webinterface.pages.my_module` and modify the functions to display the figures. Adapt the code + according to ensure loading the right figures and data points. +8. Copy :doc:`api/proteobench/template` to + `developer-guide/api/proteobench/my_module` and modify the documentation accordingly. Add entries + to :doc:`api/proteobench/modules/index` and :doc:`api/webinterface/index` diff --git a/docs/developer-guide/api/proteobench/index.rst b/docs/developer-guide/api/proteobench/index.rst new file mode 100644 index 00000000..1d7c4616 --- /dev/null +++ b/docs/developer-guide/api/proteobench/index.rst @@ -0,0 +1,10 @@ +################### +ProteoBench package +################### + + +.. toctree:: + :glob: + + * + */index diff --git a/docs/proteobench/dda_quant.rst b/docs/developer-guide/api/proteobench/modules/dda_quant.rst similarity index 100% rename from docs/proteobench/dda_quant.rst rename to docs/developer-guide/api/proteobench/modules/dda_quant.rst diff --git a/docs/developer-guide/api/proteobench/modules/index.rst b/docs/developer-guide/api/proteobench/modules/index.rst new file mode 100644 index 00000000..76855dd4 --- /dev/null +++ b/docs/developer-guide/api/proteobench/modules/index.rst @@ -0,0 +1,17 @@ +Modules +======= + +The different modules correspond to code to read the different input files and +to create the benchmarking metrics for visualization and comparison in the +:doc:`../../webinterface/index`. + + +The template module contains all needed files to create a new module. It is +recommended to copy the template module and rename it to the new module name. + + +.. toctree:: + :caption: Modules + :glob: + + * diff --git a/docs/proteobench/template.rst b/docs/developer-guide/api/proteobench/template.rst similarity index 100% rename from docs/proteobench/template.rst rename to docs/developer-guide/api/proteobench/template.rst diff --git a/docs/webinterface/webinterface.rst b/docs/developer-guide/api/webinterface/index.rst similarity index 100% rename from docs/webinterface/webinterface.rst rename to docs/developer-guide/api/webinterface/index.rst diff --git a/docs/developer-guide/development-setup.md b/docs/developer-guide/development-setup.md new file mode 100644 index 00000000..9ef84c89 --- /dev/null +++ b/docs/developer-guide/development-setup.md @@ -0,0 +1,97 @@ +## Development setup + +### Local installation +Install the package and dependencies with [Flit](https://flit.pypa.io/en/stable/): + +``` +pip install flit +flit install -s +``` + +Alternatively, use pip directly: + +``` +pip install --editable . +``` + +Using a virtual environment is highly recommended. + + +### Unit tests + +To run the tests run the command: + +``` +python -m unittest test/test_module_dda_quant.py +``` + + +### Testing the web interface locally + +Start the web server locally with: + +``` +cd ./webinterface/ +streamlit run Home.py +``` + +This will launch the Proteobench application in your web browser. + + +Changes to the code in `./webinterface` will trigger a reload of the web server. +However, changes in `./proteobench` require a full restart of the webserver +to be included. + + +### Documentation + +To work on the documentation and get a live preview, install the requirements +and run `sphinx-autobuild`: + +``` +flit install -s +sphinx-autobuild --watch ./proteobench ./docs/ ./docs/_build/html/ +``` + +Then browse to http://localhost:8000 to watch the live preview. + + +## How to contribute + +- Fork [ProteoBench](https://github.com/proteobench/proteobench) on GitHub to + make your changes. +- Commit and push your changes to your + [fork](https://help.github.com/articles/pushing-to-a-remote/). +- Ensure that the tests and documentation (both Python docstrings and files in + `/docs/source/`) have been updated according to your changes. Python + docstrings are formatted in the + [numpydoc style](https://numpydoc.readthedocs.io/en/latest/format.html). +- Open a + [pull request](https://help.github.com/articles/creating-a-pull-request/) + with these changes. You pull request message ideally should include: + + - A description of why the changes should be made. + - A description of the implementation of the changes. + - A description of how to test the changes. + +- The pull request should pass all the continuous integration tests which are + automatically run by + [GitHub Actions](https://github.com/proteobench/proteobench/actions). + + + +## Release workflow + +- When a new version is ready to be published: + + 1. Change the `__version__` in `proteobench/__init__.py` following + [semantic versioning](https://semver.org/). + 2. Update the changelog (if not already done) in `CHANGELOG.md` according to + [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). + 3. Merge all final changes with the `main` branch. + 4. Create a new release on GitHub. + +- When a new GitHub release is made, the `Publish` GitHub Action is automatically + triggered to build the Python package and publish it to PyPI. Upon a new PyPI release, + the Bioconda automations will automatically update the Bioconda package. However, + if dependencies are changed, the conda recipe will have to be updated accordingly. diff --git a/docs/developer-guide/index.rst b/docs/developer-guide/index.rst new file mode 100644 index 00000000..04d2bd9e --- /dev/null +++ b/docs/developer-guide/index.rst @@ -0,0 +1,18 @@ +############### +Developer guide +############### + +.. toctree:: + :caption: Getting started + :glob: + :maxdepth: 3 + + * + + +.. toctree:: + :caption: Python API + :glob: + :maxdepth: 3 + + api/*/index diff --git a/docs/developer-guide/local-usage.md b/docs/developer-guide/local-usage.md new file mode 100644 index 00000000..578af4e5 --- /dev/null +++ b/docs/developer-guide/local-usage.md @@ -0,0 +1,10 @@ +# Local usage + +All ProteoBench modules can be executed locally. Simply install the +`proteobench` Python package from PyPI: + +```bash +pip install proteobench +``` + +Check out the {ref}`proteobench` documentation for more information. diff --git a/docs/developer-guide/modifying-module.rst b/docs/developer-guide/modifying-module.rst new file mode 100644 index 00000000..08187f25 --- /dev/null +++ b/docs/developer-guide/modifying-module.rst @@ -0,0 +1,12 @@ +============================ +Modifying an existing module +============================ + +We recommend keeping the given structure in a module. + +_For adding new input file types_: Use the :func:`~proteobench.modules.template.ParseInputs` class to define the parsing of the input files and a specific toml file for its layout. + +_For adding new benchmarking metrics_: Add the new metrics to the ``datapoint.py`` file and the ``plot.py`` file for visualization. + +_Note_ that changing the intermediate format and the data point structure might have an impact on the other modules. Therefore we recommend +to define them stringently from the start. diff --git a/docs/index.rst b/docs/index.rst index c58de834..60c4a3f6 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,20 +1,17 @@ -.. ProteoBench documentation master file, created by - sphinx-quickstart on Fri Jun 16 09:58:17 2023. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. - -Welcome -======================================= +ProteoBench +=========== .. toctree:: :maxdepth: 1 :hidden: + :glob: - Home - userguide/index - proteobench/modules - webinterface/webinterface - changelog + About + Modules + User guide + Developer guide + Contributing + Changelog Project Overview ------------------ @@ -23,16 +20,9 @@ The ProteoBench project is divided into two main parts: Modules for Data Processing and Reporting ----------------------------------------- -These :doc:`proteobench/modules` process the data and generate reports. +These :doc:`developer-guide/api/proteobench/modules/index` process the data and generate reports. Web Interface for Result Visualization -------------------------------------- -The :doc:`webinterface/webinterface` displays the results and allows comparison with publicly available data. - - -Indices and tables -================== - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` +The :doc:`developer-guide/api/webinterface/index` displays the results and allows +comparison with publicly available data. diff --git a/docs/modules/index.rst b/docs/modules/index.rst new file mode 100644 index 00000000..02d29481 --- /dev/null +++ b/docs/modules/index.rst @@ -0,0 +1,3 @@ +####### +Modules +####### diff --git a/docs/proteobench/modules.rst b/docs/proteobench/modules.rst deleted file mode 100644 index ac79a331..00000000 --- a/docs/proteobench/modules.rst +++ /dev/null @@ -1,21 +0,0 @@ -Modules -=========================== - -The different modules correpond to code to read the different input files and -to create the benchmarking metrics for visualization and comparison in the :doc:`../webinterface/webinterface` - -.. toctree:: - :maxdepth: 1 - - dda_id - dda_quant - dia_id - dia_quant - metaproteomics - template - .. proteobench.modules.rescoring - - -The template module contains all needed files to create a new module. It is -recommended to copy the template module and rename it to the new module name. - diff --git a/docs/user-guide/glossary.md b/docs/user-guide/glossary.md new file mode 100644 index 00000000..e71c3364 --- /dev/null +++ b/docs/user-guide/glossary.md @@ -0,0 +1,2 @@ +# Glossary + diff --git a/docs/user-guide/how-to-contribute.md b/docs/user-guide/how-to-contribute.md new file mode 100644 index 00000000..8c61adea --- /dev/null +++ b/docs/user-guide/how-to-contribute.md @@ -0,0 +1,5 @@ +# How to contribute to ProteoBench + +## Proposing a new benchmark module + + diff --git a/docs/user-guide/how-to-use.md b/docs/user-guide/how-to-use.md new file mode 100644 index 00000000..c2534a6b --- /dev/null +++ b/docs/user-guide/how-to-use.md @@ -0,0 +1,3 @@ +# How to use ProteoBench + +## Guidelines for interpreting benchmark results diff --git a/docs/user-guide/index.rst b/docs/user-guide/index.rst new file mode 100644 index 00000000..ca0341b4 --- /dev/null +++ b/docs/user-guide/index.rst @@ -0,0 +1,10 @@ +########## +User guide +########## + +.. toctree:: + :caption: User guide + :glob: + :maxdepth: 1 + + * diff --git a/docs/userguide/index.rst b/docs/userguide/index.rst deleted file mode 100644 index eeb3d27e..00000000 --- a/docs/userguide/index.rst +++ /dev/null @@ -1,159 +0,0 @@ -########### -User guide -########### - -Welcome to the user guide of ProteoBench. - -***************** -Installation -***************** - - -ProteoBench can be installed as Python package using the usual pip command: - -.. code-block:: bash - - pip install proteobench - -or by cloning the repository and installing in editable mode: - -.. code-block:: bash - - git clone https://github.com/Proteobench/ProteoBench - cd proteobench - pip install --editable .[dev] - - -******************************** -Local usage -******************************** - -Start the streamlit GUI from your terminal with the following commands. - -.. code-block:: bash - - streamlit run Home.py - - -Alternatively, you can use the Jupyter notebook `Test_workflow.ipynb `_ to run the functions with more control over the parameters. - - -******************************** -Development -******************************** - -Please use the template for adding a new benchmarking module. - -======================= -Adding a new modules -======================= - -Here we provide a (hopefully) comprehensive documentation of how to set up a new module in ProteoBench - ------------------------ -Naming convention ------------------------ - -We suggest to understand the following terms as they are crucial components: - - **Module**: All code and definitions for creating and comparing benchmarks of a new data type - - **Intermediate data structure** (`DataFrame`): Data structure needed for the calculation of the `datapoint`. It contains - the transformed and annotated data of an uploaded data file. - - **Datapoint**: Metadata and benchmarking metrics for a given data set. A `datapoint` is the - data needed for the benchmarking and should also be represented by a json object. - ------------------------ -Programmatic structure ------------------------ - -The modules are located in the `proteobench/modules `_ directory. We separated the benchmarking modules into a different steps -that allow for a more modular and portable implementation. - -**Backend** - -Each module implementation should contain the following classes: - -1. :func:`~proteobench.modules.template.module.Module` contains the main functions reading the and processing the uploaded data set, generating the *intermediate* structure and creating the *datapoint*, as well as adding it to our collection of *datapoints*. -2. :func:`~proteobench.modules.template.parse.ParseInputs` interfaces with the Streamlit interface providing formatting parameter definitions to create a standardized format from the uploaded files with respect to the given file format (e.g. MaxQuant output file) -3. :func:`~proteobench.modules.template.datapoint.Datapoint` is the data structure of *Datapoint*. It contains data set properties from the acquisition and processing (e.g. used peptide fdr) and functions to calculate the benchmarking metrics. -4. :func:`~proteobench.modules.template.plot.PlotDataPoint` are the functions to visualize the benchmarking metrics from the data points. -5. :func:`~proteobench.modules.template.parse.ParseInputs` contains the functions to parse the uploaded data files into the *intermediate* structure. The input file parameters should be defined in the toml file like `proteobench/modules/template/io_parse_settings/parse_settings_format1.toml `_. - -**Web interface** - -The web interface is written in Streamlit. Each module gets assigned a specific "page". -There are only few changes necessary as the main calculations are done in - - :func:`~webinterface.pages.TEMPLATE.StreamlitUI` contains the functions to create the web interface for the module. - -*Relevant functions:* - - :func:`~webinterface.pages.TEMPLATE.StreamlitUI.generate_input_field` creates the input fields for the metadate and the - input file format and type. They are given by in the `proteobench/modules/template/io_parse_settings `_ folder, - same as for the backend of the module. - - :func:`webinterface.pages.TEMPLATE.StreamlitUI.generate_results` gathers the data from the backend - and displays them in several figures. Here you will need to edit and adapt the code - to show the respective figures with the right metadata. - - :func:`webinterface.pages.TEMPLATE.WebpageTexts` contains the text for the different parts of the web interface. - -Change the text and the field names accordingly - -**Documentation** - -We strongly recommend to keep documenting your code. The documentation is written in Sphinx and -can be found in the `docs `_ folder. - -1. `docs/proteobench/modules.rst `_ Here you can add a link to your new module -2. `docs/proteobench/template.rst `_ This template can be used to creat your own documentation file in reStructuredText (rst) format. -3. `docs/webinterface/webinterface.rst `_ Here you should add a link to the new page in the web interface. - - -To work on the documentation and get a live preview, install the requirements and run -``sphinx-autobuild``: - -.. code-block:: sh - - pip install .[docs] - sphinx-autobuild --watch ./ms2rescore ./docs/source/ ./docs/_build/html/ - -Then browse to http://localhost:8000 to watch the live preview. - - -.. note:: - - Ensure to have changed all occurrences of ``template`` to the name of your new module. - - ------------------------ -Checklist ------------------------ - -This checklist is meant to help you add a new module to ProteoBench. It is not -meant to be exhaustive, but it should cover the most important steps. - -1. Copy the `template `_ folder in the `proteobench/modules `_ directory to a new folder in the same directory. The name of the new directory should be the name of the module. -2. Define the input formats in the toml files of the `proteobench/modules/my_module/io_parse_settings` directory and `proteobench.modules.my_module.parse_settings.py`. -3. Modify the upload prodecures in the `proteobench/modules/my_module/parse.py`. This will ensure a standardized data structure for the benchmarking independently from the input file format. -4. Modify `proteobench/modules/my_module/datapoint.py` to define the requested metadata about the data acquisition and the benchmarking metrics, all to be stored in a datapoint. You might need to add some function(s) for further processing the standardized data structure. -5. Modify `proteobench/modules/my_module/plot.py` to create the figures for the web interface. -6. Modify `proteobench/modules/my_module/module.py` to harmonize all procedures called in the `benchmarking` function. -7. Copy `webinterface.pages.TEMPLATE `_ to `webinterface.pages.my_module` and modify the functions to display the figures. Adapt the code according to ensure loading the right figures and datapoints -8. Copy :doc:`../proteobench/template` to `docs/proteobench/my_module` and modify the documentation accordingly. Add entries to :doc:`../proteobench/modules` and :doc:`../webinterface/webinterface` - -================================ -Modifying an existing module -================================ - -We recommend keeping the given structure in a module. - -*For adding new input file types*: Use the :func:`~proteobench.modules.template.ParseInputs` class to define the parsing of the input files and a specific toml file for its layout. - -*For adding new benchmarking metrics*: Add the new metrics to the `datapoint.py` file and the `plot.py` file for visualization. - -*Note* that changing the intermediate format and the data point structure might have an impact on the other modules. Therefore we recommend -to define them stringently from the start. - diff --git a/img/proteobench-favicon.png b/img/proteobench-favicon.png new file mode 100644 index 0000000000000000000000000000000000000000..cbbf41a1dec9a46170b3368124209f23084ad57f GIT binary patch literal 362 zcmeAS@N?(olHy`uVBq!ia0vp^3LwnE1|*BCs=fdz&H|6fVjz77gc%o!I6MY2BuiW) zN`mv#O3D+9QW?t2%k?tzvWt@w3sUv+i_&MmvylQS`tIrC7!uL?cItkw!vP}g`zOa3 zv9>!MIBxJZu48w$V&2?2H4N-aAKVfb_|C<*uc7&ZrRYaZF2=x@Qxums*Lx^5I(fV+ z(x3D2)9yR(n~VQl1J1N$X2!`XeTpBrz z^^C7|3z)94`qXNjZ|eKSqV*|I`PRQa-UAg@-5gCB0Y!mN*1tafXF2P!{Y!M#vx^%1 z(=GU1&Sup3J8RvGm=F6L=I<&9v2^BOm3#Gj@?X6R$GRq$h^xPhj;_l%y8PvD&q;OL zpI%$PP}pE?X94T4n==<|`qHvEtmkd}i7M_n4Z;OX)q=j=i;E|1=LQA=gQu&X%Q~lo FCIGBPmyiGe literal 0 HcmV?d00001 diff --git a/img/proteobench-icon.svg b/img/proteobench-icon.svg new file mode 100644 index 00000000..be83c257 --- /dev/null +++ b/img/proteobench-icon.svg @@ -0,0 +1,87 @@ + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/img/proteobench-logo-as-font.svg b/img/proteobench-logo-as-font.svg new file mode 100644 index 00000000..6a253575 --- /dev/null +++ b/img/proteobench-logo-as-font.svg @@ -0,0 +1,116 @@ + + + + + + + + + + + + + + + + + + + + + + + + ProteoBench + + + + + + + + diff --git a/img/proteobench-logo-horizontal-as-font.svg b/img/proteobench-logo-horizontal-as-font.svg new file mode 100644 index 00000000..9e50b9e2 --- /dev/null +++ b/img/proteobench-logo-horizontal-as-font.svg @@ -0,0 +1,129 @@ + + + + + + + + + + + + + + + + + + + + + + ProteoBench + + + + + + + + + + + + diff --git a/img/proteobench-logo-horizontal-inverted.svg b/img/proteobench-logo-horizontal-inverted.svg new file mode 100644 index 00000000..0e31173b --- /dev/null +++ b/img/proteobench-logo-horizontal-inverted.svg @@ -0,0 +1,150 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/img/proteobench-logo-horizontal.svg b/img/proteobench-logo-horizontal.svg new file mode 100644 index 00000000..87c60852 --- /dev/null +++ b/img/proteobench-logo-horizontal.svg @@ -0,0 +1,159 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/img/proteobench-logo-inverted.svg b/img/proteobench-logo-inverted.svg new file mode 100644 index 00000000..5b001efa --- /dev/null +++ b/img/proteobench-logo-inverted.svg @@ -0,0 +1,218 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/img/proteobench-logo.svg b/img/proteobench-logo.svg new file mode 100644 index 00000000..135a731a --- /dev/null +++ b/img/proteobench-logo.svg @@ -0,0 +1,146 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +