Writing a pack for your laboratory’s words#

A domain pack is a file of words. It tells Ingence that noco and nocodazole name the same thing in your laboratory’s file names, and what kind of thing that is. A pack adds words and no rules of its own: the rules still do the reading. Where two meanings claim one word, the order set out below decides which one a project uses, and your own answer always wins. This guide shows how to make a pack, install it, test it and share it.

You need a project to install it into (Your first project) and a text editor. You do not need to write any code.

When a pack is the right tool#

A word that only one project uses is best answered in the Dashboard. Ingence asks what it means, and your answer is kept in that project’s Record under your name (Teaching Ingence your words). A pack is for words you want to carry:

to every project your laboratory makes, so nobody has to answer the same question twice;
to a colleague, or to another laboratory that names things the way yours does;
to the Ingence project, if the words belong to a whole field and not to one bench.

A pack offers a meaning, and in some projects it wins over another meaning without asking (see “When a pack and the core disagree” below). If a word means two things in your laboratory, do not settle it in a pack: answer it, because an answer always wins.

Two ways to start#

From what you already taught. If a project holds answers, export them as a pack:

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

--section gives the pack its name, hela-bench here. Without it the name is taught, and a second pack exported the same way would clash with the first in any project that installs both. The file lists each word you defined or assigned, with who answered and when. Answers that apply to one folder only are left out, and the command says how many, because they name that project’s folders. Read every line of the file before you share it: it holds the names of the people who answered, and it may hold words that only your laboratory uses (see “What never goes in a shared pack”).

By hand. Make a file such as this one. The words are real and the bench is invented: in this bench, a wound healing assay is the technique, nocodazole is the drug and the Leica SP8 is the confocal microscope.

hela-bench.yaml#

pack:
  name: hela-bench
  version: "1"
  author: A. Person
  licence: MIT
section: hela-bench
theme_kind: technique
summary: The techniques, drugs and microscopes of one invented bench.

entries:
  - {term: wound_healing_assay, canonical: wound healing assay,
     surfaces: [woundhealing, "wound-healing", woundassay]}
  - {term: nocodazole_drug, canonical: nocodazole,
     surfaces: [nocodazole, noco], theme_kind: reagent}
  - {term: leica_sp8, canonical: Leica SP8 confocal,
     surfaces: [sp8, leicasp8], theme_kind: instrument}

What each part says#

The pack: block is the pack’s manifest, its description of itself. It sits at the top of the file so that the pack travels as one file.

name is what a project calls the pack. It uses lowercase letters, digits, _ and -, up to 64 characters. Ingence refuses a name that a shipped pack already uses (microscopy, biochemistry and the others).
version is text. Write it in quotes, because an unquoted 1.10 is read as the number 1.1. Raise it when the words change.
author and licence say who wrote it and under what terms. The field is spelled licence; a field spelled license is ignored without a message. Choose terms you are willing to stand behind: a pack is meant to be shared.
schema and digest are for a pack that has been through teach export-answers, which writes both. schema is the version of the record format the pack was written against, in quotes. digest is a fingerprint of the pack’s words, so that a damaged or edited pack can be recognized. Leave both out of a pack you write by hand. Ingence checks them only where they are named.

Below the block the file follows the shape the shipped words use.

section names the group of words, and names the pack where a file has no pack: block. A pack exported with teach export-answers takes it from --section. summary says in a line what the words are, and a project’s Dictionary page shows it.
theme_kind is the kind of thing the words are, as a default for every entry: technique, reagent, instrument, software, format, measurement and so on. An entry can name its own kind, as nocodazole_drug does. Where a kind the shipped words already use fits, use it; the Dictionary reference lists them with their words.
entries is the list of words. Each entry has a term, which names the meaning; its surfaces, which are the spellings that carry it; and optionally a canonical, the name shown to people.

Spellings are text, written in a list in brackets. Capitals do not matter, and a hyphen or an underscore inside a spelling does not stop it matching. List the spellings people really write: the short form, the long form and the form with a hyphen. A spelling can be a phrase of several words, such as "leica sp8", which matches those words written with spaces or with underscores between them. Put quotation marks around a spelling that holds punctuation ("wound-healing") or a space, or that looks like a number ("2"). A bare word where a list belongs, or a number where a spelling belongs, is refused with a message naming the entry.

A few optional fields exist for words with special behavior, such as a spelling that counts only as a file ending (extension_only). The shipped packs use them; read the microscopy pack before you use one.

A pack can also be a folder: a pack.yaml that holds the name, version and summary, beside one or more section files. Use a folder when the words are long enough to split across files.

Install it, test it, remove it#

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

install reads the whole pack first and refuses it, in words, if it cannot be loaded: a spelling list that is not a list, a name already taken, a pack that needs a newer Ingence, or words that do not match their digest. Nothing is installed from a pack that is refused. Otherwise it says how many spellings your pack and the shipped vocabulary both claim and now tie on, if there are any.

The pack is copied into the project, so install it into every project that should read it. list shows each installed pack, its version, a short fingerprint and whether a run loads it. remove deletes the project’s copy and never touches the file you installed from. To install a changed pack under the same name, remove the old one first.

A pack is read from the next run. By hand, that is ingence index --rebind -p PROJECT and then ingence infer -p PROJECT; in the Dashboard it is Re-run. A project that has not been indexed yet has nothing to re-read, so run ingence index -p PROJECT instead.

To see whether your words fire, try the pack on a small folder of your own with the same kind of names, or on a copy of the practice folder from Your first project with a file named for one of your words added. Then:

ingence teach vocabulary -p PROJECT
ingence teach collisions -p PROJECT --decided

vocabulary lists the words Ingence recognized, with where each came from; yours show pack as their origin. collisions --decided lists the spellings where one meaning won without a tie being reported. Those are the ones to check. It also lists spellings that an answer of yours settled.

When a pack and the core disagree#

Two meanings can claim one spelling. The core Dictionary holds the words every laboratory uses, so this happens whenever a pack uses a common word. Ingence settles it in a fixed order. Where a project has accepted a shipped pack, teach collisions names it and states the rule; where it prints neither, the project is in the third case.

Your answer always wins. An answer you give in the Dashboard, or write to the Record, beats every pack and the core.
A project that has accepted a shipped pack stands the packs it chose above the core. A project accepts one when you name it as you make the project (init --domain microscopy), say yes when Ingence proposes loading it, or hold three or more files in a format that declares it (Nikon’s ND2 files for the microscopy pack; the files are counted at one reading and the pack takes effect at the next). In such a project your pack’s meaning is used over the core’s, and the core’s is kept as the alternative. Your pack and an accepted shipped pack are level with each other, so a word both claim is a tie. 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 a person can answer “not over the core” for a pack, which keeps it loaded without this standing.
Otherwise the core stands first. Your pack is level with it, so a word both hold is a tie: Ingence names both meanings, abstains on that word and asks you. Shipped packs that the project has not accepted stand just below both, so your pack’s meaning is used over theirs.

The consequence is that a common word in your pack can change what a project reads, in some projects and not in others. In the third case, install tells you how many words became ties. In the second, where your pack wins, it says nothing, so run ingence teach collisions -p PROJECT --decided after you install and read that list. If a spelling is there that you did not mean to claim, take it out of your pack. Two packs of your own that claim one spelling are level with each other, and the word is a tie.

What never goes in a shared pack#

A pack you keep inside your laboratory can hold your laboratory’s words. A pack you post, send to another laboratory or offer to the Ingence project is public, and a word in a public file cannot be taken back. Before you share one, read the whole file and take out:

People’s names: a colleague’s name or initials, a folder named for a person, and the names of the people who answered in an exported pack. The author line is the one place a name belongs, and it is yours to choose.
Names of unpublished work: a construct, a gene, a strain, a cell line, a compound, a project or a grant, and any word that would tell a reader what your laboratory is working on.
Identifiers: participant, specimen, sample or instrument serial numbers, and anything that looks like a code from a real study.
Paths and server names: anything that reveals where your data lives.

What is left should be words that many laboratories in your field would recognize: techniques, reagent classes, instruments by kind, file types, measures. A pack offered for the Ingence project itself is held to that standard word by word. Brand and supplier names can be proposed with a reason, and are weighed one at a time, because they help real folders and also go out of date.

Because an exported pack records who answered, taking out an answers block changes the pack’s words. The digest then no longer matches, and Ingence says so when you install it. Delete the digest line. A pack with no digest installs from a file, but it cannot yet be installed from a web address, which requires one.