PSDI Variability Plot

This project provides the code for a Flask-hosted web app to generate a variability plot of reaction data for the user. It publishes a service to https://organic-toolkit.psdi.ac.uk/variability-plot

For internal testing, the main branch of this project is published to https://organic-toolkit-dev.psdi.ac.uk/variability-plot, with a staging deployment at https://organic-toolkit-staging.psdi.ac.uk/variability-plot

Table of Contents

• Project Structure
• Requirements
  • Python
  • Other Dependencies
• Using the online app
• Running the Python/Flask app locally
  • Installation and Setup
  • Running the App
• Testing
• Troubleshooting
• Contributors
• Funding

Project Structure

• .github
  • workflows
    • (Automated workflows for various tasks related to project maintenance)
• deploy
  • (Files used as part of the deployment to STFC infrastructure)
• psdi_variability_plot (Primary source directory)
  • static (Static code and assets for the web app)
    • img
      • (Image assets for the web app)
    • js
      • (JavaScript code for the web app)
    • css
      • (CSS stylesheets for the web app)
  • templates
    • (HTML assets rendered by Flask for the web app)
  • __init.py__
  • (Python packages, modules, and scripts)
• scripts
  • (Scripts used for project maintenance)
• tests
  • gui
    • (Unit tests for the GUI, aka the local version of the web app)
  • python
    • (Unit tests for the Python library and command-line application)
• CHANGELOG.md (Updates since initial public release)
• CONTRIBUTING.md (Guidelines and information for contributors to the project)
• DOCKERFILE (Dockerfile for image containerising the service)
• LICENSE (Apache License version 2.0)
• pyproject.toml (Python project metadata and settings)
• README.md (This file)

Requirements

Python

Any local installation of this project requires Python 3.11 or greater. The best way to do this is dependant on your system, and you are likely to find the best tailored instructions by searching the web for e.g. "install Python 3.11 ". Some standard options are:

For Windows and MacOS: Download and run the installer for the latest version from the official site: https://www.python.org/downloads/

For Linux systems, Python is most readily installed with your distribution's package manager. For Ubuntu/Debian-based systems, this is apt, and the following series of commands can be used to install the latest version of Python compatible with your system:

sudo apt update # Make sure the package manager has access to the latest versions of all packages
sudo apt upgrade # Update all installed packages
sudo apt install python3 # Install the latest possible version of Python

Check the version of Python installed with one of the following:

python --version
python3 --version

Usually python will be set up as an alias to python3, but if you already have an older version installed on your system, this might not be the case. You may be able to set this behaviour up by installing the python-is-python3 package:

sudo apt install python-is-python3

Also check that this process installed Python's package manager, pip, on your system:

pip --version

If it didn't, you can manually install it with:

sudo apt install python3-pip

If this doesn't work, or the version installed is too low, an alternative is to install Python via the Anaconda package manager. For this, see the guide here: https://www.askpython.com/python/examples/install-python-with-conda. If you already have an earlier version of Python installed with Anaconda, you can install and activate a newer version with a command such as:

conda create --name myenv python=3.11 anaconda # Where 'myenv' is a possible conda environment name
conda activate myenv

You can also install a newer version of Python if you wish by substituting "3.11" in the above with e.g. "3.13".

Other Dependencies

This project depends on other projects available via pip, which will be installed automatically as required:

Required for all installations (pip install .):

• Flask

Required to run unit tests on the backend (pip install .[test]):

• pytest
• coverage

Required to run unit tests on the web app (pip install .[gui-test]):

• (all test requirements listed above)
• selenium
• webdriver_manager

In addition to the dependencies listed above, this project uses the assets made public by PSDI's common style project at https://github.com/PSDI-UK/psdi-common-style. The latest versions of these assets are copied to this project periodically (using the scripts in the scripts directory). In case a future release of these assets causes a breaking change in this project, the file fetch-common-style.conf can be modified to set a previous fixed version to download and use until this project is updated to work with the latest version of the assets.

Using the online app

Enter https://psdi_variability_plot.psdi.ac.uk/ in a browser. Guidance on usage is given on each page of the website.

Running the Python/Flask app locally

Installation and Setup

This project is available on PyPI, and so can be installed via pip, including the necessary dependencies for the GUI, with:

pip install psdi-variability-plot'[gui]'

If you wish to install the project locally from source, this can be done most easily by cloning the project and then executing:

pip install .'[gui]'

Note: This project uses git to determine the version number. If you clone the repository, you won't have to do anything special here, but if you get the source e.g. by extracting a release archive, you'll have to do one additional step before running the command above. If you have git installed, simply run git init in the project directory and it will be able to install. Otherwise, edit the project's pyproject.toml file to uncomment the line that sets a fixed version, and comment out the lines that set it up to determine the version from git - these are pointed out in the comments there.

If your system does not allow installation in this manner, it may be necessary to set up a virtual environment. See the instructions in the command-line application installation section above for how to do that, and then try to install again once you've set one up and activated it.

Running the App

Once installed, the command-line script psdi-variability-plot-gui will be made available, which can be called to start the server. You can then access the website by going to http://127.0.0.1:5000 in a browser (this will also be printed in the terminal, and you can CTRL+click it there to open it in your default browser). Guidance for using the app is given on each page of it. When you're finished with the app, key CTRL+C in the terminal where you called the script to shut down the server, or, if the process was backgrounded, kill the appropriate process.

In case of problems when using Chrome, try opening Chrome from the command line: open -a "Google Chrome.app" --args --allow-file-access-from-files

The local version has some customisable options for running it, which can can be seen by running psdi-variability-plot-gui --help.

Testing

To test the app, install the optional testing requirements locally (ideally within a virtual environment) and test with pytest by executing the following commands from this project's directory:

pip install .'[test]'
pytest tests/python

To test the local version of the web app, install the GUI testing requirements locally (which also include the standard GUI requirements and standard testing requirements), start the server, and test by executing the GUI test script:

pip install .'[gui-test]'
pytest tests/gui

Both of these sets of tests can also be run together if desired through:

pip install .'[gui-test]'
pytest

Troubleshooting

This section presents solutions for commonly-encountered issues.

Contributors

• Raymond Whorley (R.P.Whorley@soton.ac.uk)
• Don Cruickshank (dgc@ecs.soton.ac.uk)
• Bryan Gillis (7204836+brgillis@users.noreply.github.com)

Funding

PSDI acknowledges the funding support by the EPSRC grants EP/X032701/1, EP/X032663/1 and EP/W032252/1