pyglotaran starter kit

Read me first 👋

A ready-to-run kit for doing global and target analysis with pyglotaran — even if you have never used Python, a notebook, or a command line before. Nothing is installed on your system permanently, and it works on Windows, macOS, and Linux.

What you need before you start

You do not need to install Python, git, or anything else yourself. The starter kit does it for you.

Start in one step

Pick your operating system:

  1. Open the starter kit folder in File Explorer.
  2. Double-click START_HERE_Windows.bat.
  3. If Windows shows a blue “Windows protected your PC” box, click More info → Run anyway. (This appears because the file was downloaded; it is safe.)
  4. A black window opens and sets things up. Leave it open.
  5. After a few minutes your web browser opens with the analysis environment. Go to the “Now do this” section below.
  1. Open the starter kit folder in Finder.
  2. Right-click (or Ctrl-click) START_HERE_Mac.command and choose Open.
  3. macOS will warn that it is from an unidentified developer. Click Open to confirm. (You only need the right-click the first time; after that a normal double-click works.)
  4. A Terminal window opens and sets things up. Leave it open.
  5. After a few minutes your web browser opens with the analysis environment. Go to the “Now do this” section below.
  1. Open a terminal in the starter kit folder.
  2. Run: bash START_HERE_Linux.sh
  3. It installs a Python manager, sets things up, and opens the analysis environment in your browser. Leave the terminal open.
  4. Go to the “Now do this” section below.

Requires curl (pre-installed on most systems).

Keep the black / terminal window open while you work. It is running the analysis environment behind the scenes. When you are finished, save your notebook, close the browser tab, then close that window.

Now do this

When the analysis environment (called JupyterLab) opens in your browser, you will see a file list on the left. Work through the five notebooks in order — just open each one and follow the instructions inside:

  1. 01_welcome.ipynb — learn how a notebook works (2 minutes) and confirm everything is installed.
  2. 02_two_component.ipynb — run a complete analysis on a two-component dataset loaded from a CSV file.
  3. 03_three_component.ipynb — the same workflow on a richer three-component dataset.
  4. 04_fluorescence.ipynb — the same workflow on a real, published fluorescence measurement.
  5. 05_going_further.ipynb — where to go next: target analysis, multi-dataset fits, and case studies.

The single skill you need inside a notebook: click a code cell and press Shift + Enter to run it. Everything is explained as you go.

Starting again later

Just double-click the same START_HERE file for your system. The second time it skips the download and opens in seconds — and works offline.

If something goes wrong

The setup window closed immediately / flashed and disappeared

Something failed before it could show a message. Most often this is no internet connection or a corporate firewall. Try again on a normal network. On Windows, you can also open the folder, hold Shift and right-click an empty area, choose “Open PowerShell/Terminal here”, and run the batch file from there so the error stays visible.

“uv is required” or the download fails

The kit needs to download a small tool called uv and the analysis packages. If you are behind a company proxy or firewall, this can be blocked. Ask your IT department to allow access to astral.sh and pypi.org, or run the kit from a network without those restrictions.

The browser did not open, but the window says it is running

Look in the black/terminal window for a line containing http://localhost:8888/.... Copy that whole address (including the part after ?token=) and paste it into your web browser.

macOS says the file is “damaged” or won’t open

Use right-click → Open rather than double-clicking, and choose Open in the dialog. This tells macOS you trust the file. You only need to do this once.

A notebook cell shows a red error

The most reliable fix is to start the notebook fresh: in the JupyterLab menu choose Kernel → Restart Kernel and Run All Cells, and make sure you run cells from the top in order. If an error mentions a missing file, check you did not rename the models or data folders.

Where to learn more

Built on pyglotaran 0.7.4 and pyglotaran-extras 0.7.4. See DATA_AND_LICENSES.txt for data provenance and licensing.