release: 2.0.0 #61

New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
gcroci2 merged 13 commits into main from release_2.0.0_gcroci2
May 23, 2025
README.md
            
                      Original file line number
                      Diff line number
                      Diff line change
                  
    @@ -1,35 +1,55 @@
  
    # NPLinker Web Application

    This is the [NPLinker](https://nplinker.github.io/nplinker/latest/) web application (webapp), developed with [Plotly Dash](https://dash.plotly.com/). It enables interactive visualization of NPLinker predictions and is designed to be run locally or in a containerized environment. [A lightweight online demo](https://nplinker-webapp.onrender.com) is available for quick exploration.

    👉 **[Webapp Live Demo](https://nplinker-webapp.onrender.com)**

    <p align="center">

      <img src="app/assets/dash1.png" width="600" alt="Dashboard Screenshot 1">

    </p>

    This is the [NPLinker](https://nplinker.github.io/nplinker/latest/) web application (webapp), developed with [Plotly Dash](https://dash.plotly.com/), which enables you to visualize NPLinker predictions in an interactive way.

    <p align="center">

      <img src="app/assets/dash2.png" width="600" alt="Dashboard Screenshot 2">

    </p>

    NPLinker is a Python framework for data mining microbial natural products by integrating genomics and metabolomics data. For a deep understanding of NPLinker, please refer to the [original paper](https://journals.plos.org/ploscompbiol/article?id=10.1371/journal.pcbi.1008920).

    <p align="center">

      <img src="app/assets/dash3.png" width="600" alt="Dashboard Screenshot 3">

    </p>

    ## Online Demo

    A live demo of the NPLinker webapp is automatically deployed to [Render](https://render.com/) from `main` branch.

    You can try out the webapp directly in your browser [here](https://nplinker-webapp.onrender.com).

    ### Getting Started with Demo Data

    The webapp includes a convenient **"Load Demo Data"** button that automatically loads some sample data for you to try. Simply:

    1. Open the [live demo link](https://nplinker-webapp.onrender.com/)

    2. Click the **"Load Demo Data"** button below the file uploader

    3. The app will automatically download and process the sample dataset from [`tests/data/mock_obj_data.pkl`](https://github.com/NPLinker/nplinker-webapp/blob/main/tests/data/mock_obj_data.pkl)

    4. Start exploring natural product linking features!

    NPLinker is a Python framework for data mining microbial natural products by integrating genomics and metabolomics data.

    This demo web server is intended only for lightweight demo purposes. For full functionality, including large-scale data processing and persistent storage, please install the application locally or via Docker as described below.

    For a deep understanding of NPLinker, please refer to the [original paper](https://journals.plos.org/ploscompbiol/article?id=10.1371/journal.pcbi.1008920).

    <details>

    <summary>⚠️ Demo Server Limitations</summary>

    Please note the following limitations of the hosted demo:

    * **Cold start delay**: Free-tier apps on Render sleep after 15 minutes of inactivity and may take 20–30 seconds to wake up.

    * **Performance**: This is a minimal deployment on a free tier and is not optimized for large datasets or concurrent users.

    * **File size limits**: The demo data button loads a small sample dataset suitable for testing. Uploading large datasets via the file uploader may lead to errors or timeouts.

    * **No persistent storage**: Uploaded files are not saved between sessions.

    </details>

    ## Using the webapp

    ### Input Data

    The webapp accepts data generated by NPLinker and saved as described in the [NPLinker quickstart section](https://nplinker.github.io/nplinker/latest/quickstart/). For testing purposes, a small sample dataset is provided in [`tests/data/mock_obj_data.pkl`](https://github.com/NPLinker/nplinker-webapp/blob/main/tests/data/mock_obj_data.pkl) that can be used to try out the webapp.

    Please note that links between genomic and metabolomic data must currently be computed using the NPLinker API separately, as this functionality is not yet implemented in the webapp (see [issue #19](https://github.com/NPLinker/nplinker-webapp/issues/19)). If no links are present in your data, the scoring table will be disabled.

    ## Prerequisites

    ## Installation

    Before installing NPLinker webapp, ensure you have:

    - [Python 3.10](https://www.python.org/downloads/)

    - [Python ≥3.10](https://www.python.org/downloads/)

    - [Git](https://git-scm.com/downloads)

    - [Conda](https://docs.conda.io/en/latest/miniconda.html)

    ## Installation Options

    You can install and run the NPLinker webapp in two ways: directly on your local machine or using Docker.

    You can install and run the NPLinker dashboard in two ways: directly on your local machine or using Docker.

    ### Option 1: Local Installation

    ### Option 1: Local Installation (using Conda)

    Follow these steps to install the application directly on your system:

    @@ -39,16 +59,13 @@ Follow these steps to install the application directly on your system:
  
       cd nplinker-webapp

       ```

    2. **Set up a virtual environment**

    2. **Set up a conda environment**

       ```bash

       # Create a virtual environment

       python3.10 -m venv venv

       # Activate the virtual environment

       # For Windows:

       venv\Scripts\activate

       # For macOS/Linux:

       source venv/bin/activate

        # Create a new conda environment with Python 3.10

        conda create -n nplinker-webapp python=3.10

        # Activate the environment

        conda activate nplinker-webapp

       ```

    3. **Install dependencies**

    @@ -61,19 +78,22 @@ Follow these steps to install the application directly on your system:
  
       python app/main.py

       ```

    5. **Access the dashboard**

    5. **Access the webapp**

       Open your web browser and navigate to `http://0.0.0.0:8050/`

    #### Troubleshooting Local Installation

    <details>

    <summary>Troubleshooting Local Installation</summary>

    Common issues and solutions:

    #### Common issues and solutions

    - **Port already in use**: If port 8050 is already in use, modify the port in `app/main.py` by changing `app.run_server(debug=True, port=8050)`

    - **Package installation errors**: Make sure you're using Python 3.10 and that your pip is up-to-date

    If you encounter other problems, please check the [Issues](https://github.com/NPLinker/nplinker-webapp/issues) page or create a new issue.

    </details>

    ### Option 2: Docker Installation

    Using Docker is the quickest way to get started with NPLinker webapp. Make sure you have [Docker](https://www.docker.com/) installed on your system before proceeding:

    @@ -88,11 +108,12 @@ Using Docker is the quickest way to get started with NPLinker webapp. Make sure
  
       docker run -p 8050:8050 ghcr.io/nplinker/nplinker-webapp:latest

       ```

    3. **Access the dashboard**

    3. **Access the webapp**

       Open your web browser and navigate to `http://0.0.0.0:8050/`

    #### Docker Image Information

    <details>

    <summary>Docker Image Information</summary>

    - **Available Tags**:

      - `latest`: The most recent build

    @@ -102,32 +123,24 @@ Using Docker is the quickest way to get started with NPLinker webapp. Make sure
  
    - **More Details**: For additional information about the Docker image, see its [GitHub Container Registry page](https://github.com/NPLinker/nplinker-webapp/pkgs/container/nplinker-webapp).

    ## Online Demo

    </details>

    A live demo of the NPLinker webapp is automatically deployed to [Render](https://render.com/) and updated every time the `main` branch is updated.

    ### Filtering Table Data

    You can try out the dashboard directly in your browser here:

    The "Candidate Links" tables support data filtering to help you focus on relevant results. You can enter filter criteria directly into each column’s filter cell by hovering over the cell.

    👉 **[Live Demo](https://nplinker-webapp.onrender.com)**

    For numeric columns like "Average Score" or "# Links":

    - `34.6` or `= 34.6` (exact match)

    - `> 30` (greater than)

    - `<= 50` (less than or equal to)

    ### ⚠️ Demo Limitations

    For text columns like "BGC Classes" or "MiBIG IDs":

    - `Polyketide` or `contains Polyketide` (contains text)

    - `= Polyketide` (exact match)

    Please note the following limitations of the hosted demo:

    Multiple filters can be applied simultaneously across different columns to narrow down results.

    * **Cold start delay**: Free-tier apps on Render sleep after 15 minutes of inactivity and may take 20–30 seconds to wake up.

    * **Performance**: This is a minimal deployment on a free tier and is not optimized for large datasets or concurrent users.

    * **File size limits**: Use the small sample data provided in [`tests/data/mock_obj_data.pkl`](https://github.com/NPLinker/nplinker-webapp/blob/main/tests/data/mock_obj_data.pkl) for testing. Uploading large datasets may lead to errors or timeouts.

    * **No persistent storage**: Uploaded files are not saved between sessions.

    This hosted version is intended only for lightweight demo purposes. For full functionality, including large-scale data processing and persistent storage, please install the application locally or via Docker as described above.

    ## Using the Dashboard

    ### Input Data

    The dashboard accepts data generated by NPLinker and saved as described in the [NPLinker quickstart section](https://nplinker.github.io/nplinker/latest/quickstart/). For testing purposes, a small sample dataset is provided in [`tests/data/mock_obj_data.pkl`](https://github.com/NPLinker/nplinker-webapp/blob/main/tests/data/mock_obj_data.pkl) that can be used to try out the webapp.

    Please note that links between genomic and metabolomic data must currently be computed using the NPLinker API separately, as this functionality is not yet implemented in the webapp (see [issue #19](https://github.com/NPLinker/nplinker-webapp/issues/19)). If no links are present in your data, the scoring table will be disabled.

    For a full list of supported filter operators, see the [official Plotly documentation](https://dash.plotly.com/datatable/filtering#filtering-operators).

    ## Contributing
Provide feedback

Saved searches

Use saved searches to filter your results more quickly

release: 2.0.0 #61

Uh oh!

Diff view

Diff view

There are no files selected for viewing

Uh oh!
