Setting up your environment

The BODAQS analysis software uses an interactive computing platform called Jupyter Lab to process, analyze and present logger data. Jupyter Lab is widely used in science, engineering, finance and other quantitative disciplines.

To use Jupyter Lab you will need to do some setting up on your computer. This will include:

• Downloading the BODAQS analysis files to a local folder on your computer
• Installing Python. Python is a programming language that is used for data analysis. We need it because Jupyter Lab runs Python code, among its other capabilities.
• Creating a Python virtual environment. This is a ring-fenced area of your computer where the BODAQS software runs. Having it in its own environment keeps it isolated from everything else on your computer so that nothing breaks anything else.
• Installing the BODAQS dependencies, including Jupyter Lab. These are additional software packages that BODAQS uses.

To do these steps, you will need to use a command line interface like PowerShell on Windows or Terminal on macOS.

Note

If you work in science, engineering, finance or some other area where numbers are a big deal, the notebook-style way of working may feel familiar to you. If you don’t spend all of your time in front of a computer, you may have a bit of a learning curve.

The reason we made the software this way is that it makes it quick and easy to try out new ideas. This is important if, like us, you start without a clear idea of where you are going to end up. It makes it easier for users to modify the functionality too.

This isn’t the end state for the project. Ideally we would like to have a range of analysis tools available to suit different kinds of users. These might include a web application to display basic suspension metrics; a suite of Jupyter Lab notebooks for exploratory analysis, and other things besides.

Get the BODAQS analysis files

Most users should download the latest BODAQS analysis release as a .zip file and extract it to a local folder such as C:\Users\YourName\Documents\BODAQS on Windows or ~/Documents/BODAQS on macOS.

Go to the ‘releases’ page in the BODAQS github repository here and download the latest analysis package.

You do not need Git to run the notebooks. Cloning the repo is still fine if you are contributing to development or want the latest in-progress version.

Extract the zip first

Don’t try to run the notebooks from inside the downloaded .zip file. Extract the folder completely before continuing.

Install Python

BODAQS currently uses Python 3.14.3.

Windows

Download Python 3.14.3 from the official Python website:

• https://www.python.org/downloads/windows/

Run the installer and make sure you tick:

• Add python.exe to PATH
• Install launcher for all users (recommended)

Then open a new PowerShell window and check that Python is available:

python --version
pip --version

If python is not recognised, close and reopen PowerShell. If that still doesn’t work, rerun the installer and make sure Add python.exe to PATH was ticked.

Mac

Hands off the macOS system Python

Never modify or replace the Python at /usr/bin/python3 on macOS, and avoid using sudo to install Python packages. That interpreter belongs to the operating system and breaking it is painful.

Install Homebrew if you don’t have it already, then install pyenv:

brew install pyenv

Add pyenv to your shell so it initialises automatically. For zsh (the default on modern Macs):

echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.zshrc
echo 'export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.zshrc
echo 'eval "$(pyenv init -)"' >> ~/.zshrc
source ~/.zshrc

Then install the Python version used by BODAQS:

pyenv install 3.14.3
pyenv local 3.14.3

Note

On macOS, pyenv keeps the BODAQS Python separate from the system Python. On Windows, this guide uses the standard Python installer because it is simpler for most users.

Create the virtual environment

Open a terminal in the BODAQS folder you unzipped (or cloned), then create the virtual environment:

Windows

cd C:\path\to\BODAQS
python -m venv .venv

Mac / Linux

cd /path/to/BODAQS
python -m venv .venv

Activate the virtual environment

Windows

.\.venv\Scripts\Activate.ps1

Mac / Linux

source .venv/bin/activate

If PowerShell blocks activation

On some Windows systems, PowerShell will refuse to run the activation script the first time. If that happens, run:

Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

Then try:

.\.venv\Scripts\Activate.ps1

Note

Once activated, your terminal prompt will show (.venv) at the start - that’s your confirmation the environment is live.

Upgrade pip

With the virtual environment active, upgrade pip:

python -m pip install --upgrade pip

Install the dependencies

requirements.txt pins every BODAQS dependency, including JupyterLab, ipykernel, pandas, numpy, scipy, plotly, and the interactive notebook widgets. Install them all with:

python -m pip install -r requirements.txt

Note

This installs a large number of packages and may take a few minutes on first run. Subsequent installs are much faster because pip caches what it’s already downloaded.

No separate pip install jupyterlab step is needed after this; the repo-root requirements.txt is the canonical live environment specification.

Once this finishes, continue to Loading your data.