Get your computer ready for the GORDIAN score workshop

If you already have conda or Miniforge, you can use a conda environment instead of the venv steps below. One of the packages, gseapy, comes from the bioconda channel, so configure the channels first:

conda config --add channels conda-forge
conda config --add channels bioconda

conda create -n gordian python=3.11
conda activate gordian

conda install numpy pandas matplotlib seaborn bioconda::gseapy \
  statsmodels umap-learn scikit-learn scipy jupyterlab ipywidgets

Then start JupyterLab from the activated environment:

jupyter lab

Step 1 · Check whether Python is already installed

Open the Start menu and type Wiersz polecenia (or Command Prompt), or PowerShell, and open it. In the window that appears, type:

py --version

If that shows nothing useful, try:

python --version

✓ See something like Python 3.11.x? → skip to Step 3. Nothing found? → do Step 2.

Step 2 · Install Python

1. Go to python.org/downloads/windows and download the latest stable Python 3 installer.
2. Run the installer.
3. Very important: on the first screen, tick “Add python.exe to PATH” at the bottom before clicking Install. This is what lets the terminal find Python.
4. Click Install Now and wait for it to finish.
5. Close and reopen the Command Prompt / PowerShell window (it only picks up the new PATH in a fresh window).
6. Check again: python --version

Step 3 · Move into the workshop folder

Put all workshop materials in one folder — for example a folder called GORDIAN_hands_on on your Desktop (any name is fine). Then move into it with cd (“change directory” — it points the terminal at that folder):

cd Desktop
cd GORDIAN_hands_on

Confirm the workshop files are here by listing the folder contents:

dir

Step 4 · Create the virtual environment

This makes a .venv folder inside your project that holds a private Python just for this workshop. You only do this once.

py -m venv .venv

Step 5 · Activate the environment

.venv\Scripts\activate

You should now see (.venv) at the start of the line — that means the terminal is now using the workshop's Python.

Step 6 · Upgrade pip and install the libraries

pip installs Python libraries. Upgrade it first (fewer install errors), then install everything listed in requirements.txt:

python -m pip install --upgrade pip
python -m pip install -r requirements.txt

✓ This can take a few minutes. If it finishes with no error at the end, you're installed and ready.

Step 7 · Start JupyterLab

See the How to run and use JupyterLab section below (with screenshots), or if you already know it, launch it and start on the tasks.

cd Desktop\GORDIAN_hands_on
.venv\Scripts\activate

Step 1 · Open Terminal and check for Python

Open Terminal: press Cmd + Space, type Terminal, press Enter. Then type:

python3 --version

✓ See Python 3.11.x (or similar)? → skip to Step 3. Nothing? → do Step 2.

Step 2 · Install Python

The simplest option: download the latest stable Python 3 for macOS from python.org/downloads/macos and run the installer. Then close Terminal and open it again, and check:

python3 --version

Advanced users can install with Homebrew instead, but that's not required for the workshop.

Step 3 · Move into the workshop folder

Put the materials in one folder (e.g. GORDIAN_hands_on on your Desktop), then move into it with cd:

cd ~/Desktop/GORDIAN_hands_on

List the contents to confirm the files are there:

ls

Step 4 · Create the virtual environment

Creates a .venv folder with a private Python for this workshop. Do this once.

python3 -m venv .venv

Step 5 · Activate the environment

source .venv/bin/activate

You should see (.venv) at the start of the line.

Step 6 · Upgrade pip and install the libraries

With (.venv) active, run:

python -m pip install --upgrade pip
python -m pip install -r requirements.txt

✓ A few minutes is normal. No error at the end = success.

Step 7 · Start JupyterLab

See the How to run and use JupyterLab section below (with screenshots), or launch it yourself and begin the tasks.

cd ~/Desktop/GORDIAN_hands_on
source .venv/bin/activate

Step 1 · Open Terminal and check for Python

python3 --version

✓ See Python 3.11.x (or similar)? → skip to Step 3. Nothing? → do Step 2.

Step 2 · Install Python

On Ubuntu, Debian or Linux Mint:

sudo apt update
sudo apt install python3 python3-pip python3-venv

You may be asked for your system password — that's normal, and it stays invisible as you type (no dots appear). This installs Python, pip, and the venv tool. Then check again:

python3 --version

On other distributions, use your system's package manager to install Python 3, pip, and venv.

Step 3 · Move into the workshop folder

Put the materials in one folder (e.g. GORDIAN_hands_on on your Desktop), then:

cd ~/Desktop/GORDIAN_hands_on

List the contents:

ls

Step 4 · Create the virtual environment

python3 -m venv .venv

Do this once — it creates the .venv workspace for this project.

Step 5 · Activate the environment

source .venv/bin/activate

Look for (.venv) at the start of the line.

Step 6 · Upgrade pip and install the libraries

python -m pip install --upgrade pip
python -m pip install -r requirements.txt

✓ A few minutes is normal. No error at the end = success.

Step 7 · Start JupyterLab

See the How to run and use JupyterLab section below (with screenshots), or launch it and begin the tasks.

cd ~/Desktop/GORDIAN_hands_on
source .venv/bin/activate

Start JupyterLab

Start JupyterLab inside the command window of your system (Command Prompt / Terminal / PowerShell) with:

jupyter lab

JupyterLab should open automatically in your web browser. If it does not open automatically, the command window will show a link — copy that link and paste it into your browser.

What is JupyterLab?

JupyterLab is a working environment for Python. It opens in a web browser, but it runs on your computer. We will use it to work with notebook files, which usually end with .ipynb

A notebook is divided into cells. A cell can contain code, text, results, tables or plots. This is useful during a workshop because we can run the code step by step and immediately see the results.

Basic work in JupyterLab

Open a notebook

In JupyterLab, use the file browser on the left side and open the workshop notebook (a file ending in .ipynb) that the instructor shares.

A notebook is divided into smaller blocks called cells. A cell is one separate part of the notebook. You can run cells one by one. This is useful because we can build the analysis step by step, check intermediate results and correct mistakes without running the whole file every time.

There are two cell types that we will use most often.

A code cell contains Python code. For example:

print("Hello from Python")

When you run a code cell, Python executes the code and shows the result below the cell. Code cells are used for loading data, calculations, analysis, plots and model training.

A Markdown cell contains text, notes, explanations, headings or instructions. Markdown cells are not Python code. They are used to make the notebook easier to read.

Run a cell

Click inside a cell and press:

Shift + Enter

This runs the selected cell and moves to the next one (it creates an empty cell if there is none). You can also use the Run button at the top of the notebook (the pink panel in the image above).

Edit and rerun a cell

Click inside a code cell, change the code, and run it again with Shift + Enter — the output below the cell will update. To update a Markdown cell, double-click on it.

Add a new cell

Click the + button in the notebook toolbar (pink box in the image above).

Save your notebook

Use Ctrl + S. Save your work regularly. To rename the notebook, right-click it and select “Rename Notebook…”.

Stop code that runs too long

If a cell runs for too long, click the square Stop button in the notebook toolbar.

Restart Python inside the notebook

The Python process running the notebook is called the kernel. If something behaves strangely, restart it via the Kernel > Restart Kernel menu, then run the notebook again from the beginning.

How to close JupyterLab

1. Save your notebook.
2. Close the browser tab.
3. Return to the command window.
4. Press Ctrl + C.
5. Confirm if the command window asks whether to stop JupyterLab.