← Back to Isom Lab on GitHub

Getting started with a lab tool

Every Isom Lab tool works the same way: download its folder, double-click the launcher inside, and work in the window that opens. This page covers those shared steps once, so each tool’s own guide only has to tell you the things that are genuinely its own — what its launcher is called, and what to do with it once it is running.

Expect about ten minutes the first time. After that, starting the tool is a double-click. You do not need to know how to code.

Do the one-time computer setup first. If you have never installed a lab tool on this computer, start with Setting up your computer and come back here.

On Windows everything below works the same. Where this page says “Terminal”, use Miniforge Prompt for a tool that uses conda, or Command Prompt for one that doesn’t. The tool’s own guide says which it is.

Get the code

Every tool lives in its own repository on GitHub. A repository is just the tool’s folder, kept online, with a record of every change ever made to it. Getting the code means copying that folder onto your computer, where it becomes an ordinary folder you can open in Finder or File Explorer.

The tool’s own guide links to its repository and says whether it is public (anyone can download it) or private (only people Dan has invited). That affects nothing except how you download it.

Which way should I choose?

There are three routes, and they differ mainly in what updating looks like later:

If you are unsure, take the ZIP. Nothing is lost by starting there: you can switch to GitHub Desktop later by downloading the tool again and deleting the first folder, since your records are kept outside the code folder either way.

Public tools

Most lab tools are public, so no account, password or token is involved. Any of these three works.

Option A — Download ZIP. Nothing to install; it all happens in your browser.

  1. Open the tool’s page on GitHub.
  2. Click the green Code ▾ button near the top right, then Download ZIP.
  3. On Windows, unblock it before extracting — right-click the downloaded ZIP, choose Properties, tick Unblock, then OK. This saves you a SmartScreen warning when you launch.
  4. Unzip it: double-click on a Mac, or right-click and choose Extract All on Windows. Then move the folder somewhere sensible, like your Documents.

Option B — GitHub Desktop. Best if you expect to update often.

  1. Open GitHub Desktop, then File ▸ Clone repository… ▸ URL.
  2. Paste the tool’s GitHub address — the https://github.com/isomlab/… link from its guide.
  3. Pick where it should go in the Local path box, then click Clone.

Option C — git clone in Terminal. Because the repository is public, this just works, with no password:

cd ~/Documents
git clone https://github.com/isomlab/TOOL.git

Private tools

A few tools are private, and those need you signed in to a GitHub account that has been given access. If you have not done that yet, it is step 1 of Setting up your computer — send Dan your GitHub username and accept the invitation email.

Use one of these two ways: both avoid passwords and tokens.

Option A — Download ZIP.

  1. In a web browser, sign in at github.com. This step is what makes the download work, and it is the one people skip.
  2. Open the tool’s page on GitHub.
  3. Click the green Code ▾ button, then Download ZIP, and unblock it first if you are on Windows, as above.
  4. Unzip it and move the folder somewhere easy, like your Documents.

Option B — GitHub Desktop.

  1. Open GitHub Desktop and sign in with your GitHub account.
  2. File ▸ Clone repository…, find the tool in the list of repositories you have access to, choose where to put it, and click Clone.

Do not use git clone for a private repository. It asks for a password that no longer works, and gets confusing fast. Use one of the two ways above.

What you should end up with

Either way, you now have the tool’s folder on your computer. Open it and you should see at least:

If you downloaded a ZIP, the folder is called something like TOOL-main rather than TOOL. main is the name of the current version line on GitHub, and the ZIP is named after it. That is normal and changes nothing.

Put it somewhere you will find it again — Documents is a good default. Try not to leave it in Downloads, which is the folder people empty when they are short of space.

“404 — page not found”

If the tool’s GitHub link gives you a 404, the repository is private and GitHub cannot see that you are allowed in. Check two things: that you are signed in to github.com with the same account whose username you sent Dan, and that you have accepted the invitation email. Until both are true a private repository is invisible to you, which is why GitHub says “not found” rather than telling you that you lack access.

Launch it

Inside the folder you downloaded there is a folder called launchers. Open it and double-click the file for your computer:

Each tool’s own guide names its launcher exactly, because the name has the tool in it: Launch cellog.command, PAM Scanning.bat, and so on.

If you downloaded a ZIP, your folder is called something like TOOL-main rather than TOOL. The launchers folder is inside it just the same.

What the launcher is

It is a short script whose entire job is to spare you the command line. When you double-click it, it finds conda on your computer, builds the tool’s environment if this is the first time, and starts the app.

You do not need to type anything, and nothing is installed system-wide. Whatever a tool needs, it keeps inside its own environment, where it cannot disturb anything else on your computer.

What you will see

A text window opens first. That is Terminal on a Mac, or a Command Prompt window on Windows, and seeing it is normal — the launcher runs there. Lines will scroll past; on a first launch with conda it works through phrases like “Solving environment” for a while. None of it needs anything from you.

Then the tool’s own window appears, and you can get on with your work. A couple of tools open in your web browser instead of a window of their own, and their guides say so.

Leave the text window open while you work. It is not left-over clutter: the tool is running inside it. Closing that window, or quitting Terminal, closes the tool with it. When you have finished, close the tool first and the text window is then safe to close.

How long the first launch takes depends on which kind of tool it is:

The first-time hiccups

Both systems are wary of a file that arrived from the internet, so your first double-click may produce a warning instead of the app. Neither warning means anything is wrong.

Mac — “cannot be opened because it is from an unidentified developer”. Right-click (or Control-click) the launcher, choose Open, then Open again in the dialog that follows. You only do this once; a plain double-click works from then on.

Windows — “Windows protected your PC”. That is SmartScreen. Click More info, then Run anyway. You can avoid it entirely by unblocking the ZIP before extracting: right-click the ZIP, Properties, tick Unblock, then OK.

Mac — double-clicking does nothing at all. The file has probably lost its executable flag, which happens easily when a ZIP is unzipped. Run this once in Terminal, then double-click again:

chmod +x "<the tool's folder>/launchers/<the launcher>.command"

If instead a window flashes open and disappears too quickly to read, something failed rather than was blocked — see If something goes wrong, which shows you how to run the same launcher with the message left on screen.

Making it quicker to open next time

You do not have to dig through folders every time:

Make a shortcut or alias rather than moving the launcher itself. It expects the rest of the tool to be around it, so it stops working if you drag it out of the launchers folder.

Updating later

Tools change over time: a bug gets fixed, a feature appears, a calculator gets added. Updating means bringing that newer code into the folder you already have.

There is no schedule to keep. Nothing updates behind your back, and nothing nags you — if a tool is doing what you need, it is perfectly fine to leave it as it is until you want something newer.

Your saved work is not in the code folder. Each tool keeps your records somewhere separate in your home folder, and its own guide says where. That is why updating the code — or rebuilding it, or deleting the folder and starting over — never touches what you have entered.

How do I know there is an update?

Updating, the way you downloaded

If you used GitHub Desktop. Open it, pick the tool in the list on the left, click Fetch origin, then click Pull origin when it appears. That is the whole job — no typing, and it keeps the same folder you already launch from.

If you used git clone. Open Terminal and run:

cd ~/Documents/TOOL
git pull

If you downloaded a ZIP. There is no update button; you fetch a fresh copy. Download the new ZIP exactly as in Get the code, unzip it, and put the new contents where the old ones were. Two things worth getting right:

If replacing the contents feels fiddly, it is just as good to delete the old folder and keep the new one. Your records are elsewhere, so nothing is lost.

Do I have to reinstall anything?

Usually not. Tools that use conda are installed in what is called editable mode, which means the environment points at the folder you downloaded rather than keeping a copy of its own. The moment that folder has newer code in it, the next launch runs it. Nothing to reinstall, nothing to set up again.

The exception is a new version that needs a package it never needed before. The environment is then out of date rather than the code, and the usual sign is the tool failing to start with a message about a module it cannot find. The fix is to throw the environment away and let the launcher build a fresh one:

conda env remove -n ENVIRONMENT

Put your tool’s environment name in place of ENVIRONMENT — each tool’s guide names its own. Then double-click the launcher as usual and wait the few minutes it took the very first time, while it rebuilds. Your records are untouched by any of this.

Tools that need no conda have no environment at all, so refreshing the folder is the entire update.

It updated, but nothing looks different

Nearly always one of two things:

If something goes wrong

Nearly every failure here is one of a handful of things, and none of them can harm your computer or lose your records — those live outside the code folder, so you can delete an environment, or the whole folder, and start again without losing a single entry.

Try these first

Before hunting for your exact message, three things fix most of it:

  1. Close the tool and launch it again. Close the text window too, then double-click the launcher afresh.
  2. Open a brand-new Terminal or Miniforge Prompt if you have been typing commands. Anything installed since you opened the old window is invisible to it.
  3. Check you are launching the folder you think you are. A TOOL-main from a ZIP sitting next to a TOOL from GitHub Desktop catches people out constantly.

The launcher will not start

It starts, then fails

Downloading problems

Reading the actual error

The launcher window often closes before you can read why it failed. Making the message stay on screen is the single most useful thing you can do, and it is what turns “it doesn’t work” into something fixable:

The same thing runs, but now the text stays put. The useful part is usually the last few lines, not the first.

Still stuck?

Email Dan at disom@miami.edu. Four things make it quick to sort out, and a screenshot covers most of them:

There is no such thing as a silly one. Most of these turn out to be a window that needed reopening.

Alternative: plain pip

The launcher is the recommended route, because the environment it builds is guaranteed to include the GUI toolkit. If you would rather manage things yourself, from inside the tool’s folder:

python3 -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate
pip install -e .

This only works if your Python includes tkinter: macOS’s built-in python3 does, Homebrew Python needs brew install python-tk, and conda always does.

Install the tool by its GitHub address rather than by name, unless its own guide says otherwise — a short name on PyPI may well belong to an unrelated project:

pip install git+https://github.com/isomlab/TOOL

Now use it

That is the part every tool shares. What to actually do with the window that opens is in the tool’s own docs/getting_started.md, which you will find in the folder you just downloaded, and on its GitHub page.

Every lab tool is listed on the Isom Lab on GitHub main page.

← Back to Isom Lab on GitHub