Your first project#

This page takes about ten minutes. You make a small practice folder, have Ingence read it, and look at what it found. Nothing here touches a folder of yours.

You need Ingence installed (Install) and a terminal.

Tip

Typing ingence see with nothing after it is a shorter way in. It opens a page in your browser that makes a project, asks the few things the engine needs, and runs the steps below when you click. This page does the same steps by hand, one command each, so you can see what each one does.

Make a practice folder#

A project is the folder where Ingence keeps what it finds and what you decide. The root is the folder it reads. They are two different folders. Ingence writes only into the project.

First make a working folder. Inside it, make a practice root that holds the files of two HeLa imaging experiments. The names are built the way real names are: a date, a cell line, a treatment, a number.

mkdir ingence-tutorial && cd ingence-tutorial
mkdir -p practice-lab/20261012_HeLa_DAPI-GFP practice-lab/20261019_HeLa_DAPI-GFP practice-lab/scripts
printf 'TIFF stand-in\n' > practice-lab/20261012_HeLa_DAPI-GFP/20261012_HeLa_DMSO_001.tif
printf 'TIFF stand-in\n' > practice-lab/20261012_HeLa_DAPI-GFP/20261012_HeLa_DMSO_002.tif
printf 'cell,GFP,DAPI\n1,0.41,0.88\n2,0.44,0.91\n3,0.39,0.86\n' > practice-lab/20261012_HeLa_DAPI-GFP/20261012_HeLa_DMSO_quant.csv
printf 'Imaged on the confocal. Control wells only.\n' > practice-lab/20261012_HeLa_DAPI-GFP/notes.txt
printf 'TIFF stand-in\n' > practice-lab/20261019_HeLa_DAPI-GFP/20261019_HeLa_DMSO_001.tif
printf 'cell,GFP,DAPI\n1,0.61,0.84\n2,0.58,0.83\n' > practice-lab/20261019_HeLa_DAPI-GFP/20261019_HeLa_DMSO_quant.csv
printf 'import csv\n\n# average GFP per cell\n' > practice-lab/scripts/quantify_gfp.py

New-Item -ItemType Directory ingence-tutorial | Out-Null
Set-Location ingence-tutorial
New-Item -ItemType Directory practice-lab\20261012_HeLa_DAPI-GFP, practice-lab\20261019_HeLa_DAPI-GFP, practice-lab\scripts | Out-Null
Set-Content practice-lab\20261012_HeLa_DAPI-GFP\20261012_HeLa_DMSO_001.tif "TIFF stand-in"
Set-Content practice-lab\20261012_HeLa_DAPI-GFP\20261012_HeLa_DMSO_002.tif "TIFF stand-in"
Set-Content practice-lab\20261012_HeLa_DAPI-GFP\20261012_HeLa_DMSO_quant.csv "cell,GFP,DAPI","1,0.41,0.88","2,0.44,0.91","3,0.39,0.86"
Set-Content practice-lab\20261012_HeLa_DAPI-GFP\notes.txt "Imaged on the confocal. Control wells only."
Set-Content practice-lab\20261019_HeLa_DAPI-GFP\20261019_HeLa_DMSO_001.tif "TIFF stand-in"
Set-Content practice-lab\20261019_HeLa_DAPI-GFP\20261019_HeLa_DMSO_quant.csv "cell,GFP,DAPI","1,0.61,0.84","2,0.58,0.83"
Set-Content practice-lab\scripts\quantify_gfp.py "import csv","","# average GFP per cell"

You now have seven files in three folders:

practice-lab/
  20261012_HeLa_DAPI-GFP/   20261012_HeLa_DMSO_001.tif  20261012_HeLa_DMSO_002.tif
                            20261012_HeLa_DMSO_quant.csv  notes.txt
  20261019_HeLa_DAPI-GFP/   20261019_HeLa_DMSO_001.tif  20261019_HeLa_DMSO_quant.csv
  scripts/                  quantify_gfp.py

The .tif files are stand-ins. Each holds one line of text and no picture, so Ingence can read their names and not their pixels. A real folder of images gives Ingence far more to read. You can point the commands below at any other small folder of your own instead. Ingence reads it and changes nothing in it.

Or use the sample collection#

For a larger practice folder, the sample collection writes an invented laboratory drive of about five hundred files. Run it in the environment where Ingence is installed, and use its pool folder as the root in the steps below, in place of practice-lab. The numbers on this page are for the small folder above.

python -m ingence.evaluation sample-lab sample-collection --tier S --seed 1

Step 1. Make the project#

ingence init project --root practice-lab --domain microscopy

init creates a project folder called project, next to practice-lab, and declares practice-lab as the root to read. It opens no file yet. It does look at the folder’s names once, to learn whether the drive treats capital and small letters as different, and it says what it found. It prints where the project is, which domain packs it will load, the root, and the next command to run.

--domain microscopy loads the microscopy pack, the words for imaging: DAPI, GFP, confocal and others. A pack is a set of words for one science (see Domain packs). Without --domain, Ingence loads the core Dictionary and proposes packs from what it finds.

ingence init --help lists the other choices. One is worth knowing now: --depth metadata declares that no dive opens a file unless someone asks for a deeper one (Read someone else’s folder).

Step 2. Take the census#

ingence index -p project

index takes a census: it walks the root and records what the filesystem states about every file and folder (name, size, dates and links). It opens no file. It also reads each name into its parts, such as a date, a number or a word, and looks the words up in the Dictionary, which holds what words mean.

It ends by saying what it read. For the practice folder:

  • it indexed eleven entries as one run: 7 files and 4 folders (the root counts as a folder);

  • it read 24 words in the names. Nine were understood, because the Dictionary holds a meaning for them, such as DAPI, GFP and quant. Fifteen were unknown, with none contested. HeLa and DMSO are among the unknown: the microscopy pack has no entry for either. The biochemistry pack does, and --domain biochemistry would read them. An unknown word is not an error. It is the engine saying it has no meaning for the word in the packs this project loads, and you can give it one later (Teaching Ingence your words);

  • it names the next command.

Step 3. Dive#

ingence dive -p project --budget 60

dive opens files, one type at a time, for as long as you allow. --budget is that time in seconds. It reads headers, text and tables, and it never runs anything it finds. The practice files are tiny, so it opens all seven at once and says so. In a large folder the budget runs out first. The files not reached are marked unexamined, which is different from “nothing found”, and running dive again with a fresh budget carries on.

Step 4. Infer#

ingence infer -p project

infer applies the Rulebook to what was read. Each conclusion is a claim: it carries the rule that made it, the rule’s version and the evidence. A rule that cannot decide says so and says why. For the practice folder it reports 41 claims.

It also says that some rules are “not built to run yet”. The shipped Rulebook declares rules that are not implemented. Adding --verbose lists them, and shows each rule’s counts.

Step 5. Look at it#

ingence see -p project

see starts the Dashboard and opens it in your browser. It prints an address that begins http://127.0.0.1:. That address works only on your computer, and the page fetches nothing from the internet. Press Ctrl-C in the terminal to stop it.

The Dashboard opens on your experiments laid out by date. For the practice folder it finds two, one for each dated folder. Two parts of it matter most at first:

  • Explore shows what is there and what could not be read, and lets you search. Open any file to see what was read from it and every conclusion about it, each with its rule.

  • Questions shows what is waiting for you. For the practice folder it holds a sheet of eight questions, such as whether the two folders read as experiments are right. Where the rules cannot settle something alone, Ingence proposes and does not decide, and nothing happens until you answer. Your answer is kept in the project’s Record under your name, beside every earlier one. It never replaces one.

An answer, a word’s meaning or a changed setting does not change what you see at once. It waits for Re-run, a button whose count says how many changes are waiting. Re-run reads the affected names again and runs the rules again.

What you have now#

The project folder holds one run for each command that read something, your Record, and your settings. The practice-lab folder is exactly as you made it. You can delete both, and the ingence-tutorial folder, whenever you like.

Where to go next: