Domain packs#

A domain pack is a set of words and file types for one science. A pack adds vocabulary and no rules of its own: it tells the Dictionary that brightfield and bf mean the same thing in microscopy, or that rnaseq names a kind of sequencing, and the rules do the rest.

The core Dictionary reads what every laboratory holds: file formats, dates, units and the stages of work. Packs add what is particular to a field.

The packs that ship#

Eight packs ship with Ingence. Each is a YAML file inside the package.

Pack	What it adds
`microscopy`	Imaging modalities, optical configuration, labels and image processing.
`biochemistry`	Wet-laboratory techniques, reagent classes, cell culture and genetics.
`sequencing`	Library types, platforms, read structure, processing steps and measures.
`spectrometry`	Mass spectrometry, optical and magnetic spectroscopy, and their measures.
`electrophysiology`	Recording configurations, protocols, measured quantities and formats.
`clinical`	Study design, specimens, imaging modalities and the vocabulary of identifiers. The pack names identifier words and marks them as sensitive. No rule yet flags a file that seems to hold identifiers, so do not rely on Ingence to find them.
`computational`	Simulation, numerical methods, scheduling and scientific file formats.
`programs`	Scientific programs a laboratory keeps installed beside its data, recognized by the parts their installations hold side by side.

programs is about software, not a science, and it loads in every new project. The other seven are your choice.

Which packs a project loads#

You choose when you make the project:

ingence init project --root my-data --domain microscopy --domain biochemistry

--domain can be repeated. --all-domains loads every shipped pack. With neither, a new project loads the core and programs, and Ingence proposes the others from what it finds:

It proposes a pack when that pack would read enough names that nothing else reads.
It accepts a pack without asking when your folder holds three or more files in a format that declares its pack. Today only one format does: Nikon’s ND2 files accept microscopy. Folders of other instruments’ files accept nothing this way. The number is a setting (dictionary.files_to_accept_a_pack), and a refusal from you on the Questions page wins.
In a project that loads every pack, it asks whether to keep a pack when none of your names holds one of its words. Refusing stops loading it from the next run.

Nothing is loaded or dropped until it is accepted, except the automatic case above, which you can refuse. A change to which packs load waits for Re-run like any other change.

When a pack and the core disagree#

Two meanings can claim one spelling, and Ingence settles it in a fixed order. ingence teach collisions -p PROJECT lists every spelling that two meanings claim and whether Ingence decides it or reports it. Where the project has accepted a shipped pack, it also names the pack and states the rule below; where it prints neither, the project is in the third case. Add --decided to see only the ones where one meaning wins without a tie being reported, which are the ones to look at: Ingence is answering a question for you without saying there was one. It also lists the ones your own answers settled.

Your answer wins over everything.
In a project that has accepted a shipped pack, the packs the project chose stand above the core. Those are the accepted shipped packs and your laboratory’s own. A project accepts a shipped pack when you name it with init --domain, say yes when Ingence proposes loading it, or hold files in a format that declares it (see above). The core’s meaning is then kept as the alternative. Every other shipped pack stands level with the core there, so a word only one of them and the core claim is a tie. On the Dictionary page you can answer “not over the core” for a pack, which keeps it loaded without this standing.
Otherwise the core’s meaning is used over a shipped pack’s, and a pack of your own stands level with the core. A word that both hold is a tie, and a tie waits for your answer. Your pack stands above the shipped packs the project has not accepted.

A pack of your own can therefore win a common word without asking, in a project that has accepted a shipped pack. Writing a pack says what that means for the words you put in one.

How a laboratory adds its own words#

A laboratory’s own words are a question only that laboratory can answer, so Ingence gives you controls rather than guessing.

Answer once in the Dashboard. Where words appear in your file names and nothing reads them, Ingence asks, on the Questions page, what they mean. Your answer goes into the project’s Record under your name. See Teaching Ingence your words.

Export what you taught as a pack. This writes the answers your project holds as one YAML file, each with who answered and when:

ingence teach export-answers -p PROJECT --out ours.yaml --author "A. Person" --licence MIT

An answer that applies to one folder only is left out, and the command says how many, because those answers name that project’s folders.

Install a pack. A pack is a file, a folder that holds a pack.yaml, or a web address:

ingence teach pack install ours.yaml -p PROJECT
ingence teach pack list -p PROJECT
ingence teach pack remove NAME -p PROJECT

An installed pack is read from the next run. Installing says how many spellings now tie with the shipped vocabulary, if any. Where your pack wins a word it says nothing, so run ingence teach collisions -p PROJECT --decided afterward. Removing a pack deletes the project’s copy and never touches the file you installed it from.

A pack states its name, version, author, license (the field is spelled licence), the schema version it needs and a digest of its words. Ingence refuses a pack whose words do not match its digest, or that needs a newer Ingence. It also refuses a name that a shipped pack already uses. An address is fetched only when you run teach pack install with it. A pack from an address is refused if it is larger than four megabytes (--largest changes that) or if the address takes longer than 30 seconds to answer (--timeout changes that).

Sharing a pack is sending that file. Writing a pack shows how to make one by hand.