The Release page

Release has three pages in the side: Releases, New release and Session schemes. It opens for a person with see on Release. Making a release, handing it over, withdrawing it and keeping a scheme need work on Release.

Make a release

1. Open Releases and press New release. From a cohort on Data, Release opens the same dialog with the cohort chosen.
2. Of: a cohort (every current member and every stack of theirs), or a query card’s answer (a complete answer at stack grain, kept on this desk and not stale).
3. Name: filled in for what the release is of, the day and the next number of that day. Change it if you want.
4. Layout: BIDS or Descriptive. Beside BIDS, names asks for Full names or Minimal names. How the files are named says what each writes.
5. How it leaves: read it. It says, for each dataset the files come from, how that dataset’s files leave. Nothing to choose unless you override.
6. Sessions: choose a session scheme, or press New scheme to make one here. A scheme says how a subject’s studies become sessions and what each is called.
7. Override: leave it on UIDs: each dataset’s own, or choose UIDs remapped or UIDs kept for every file of this release. The release row says so.
8. Written to: an export place. Settings, Places makes one.
9. For a cohort, press Select first. It says what the release reaches (subjects, sessions, stacks, size) and writes nothing.
10. Open Expert options below the form only if you need one; see expert options.
11. Press Release. It queues the job, and the page says which job and where it writes.

A cohort with stacks still waiting on Review says so before it leaves: they leave with the rules’ verdict as it stands, marked unsure in the dataset’s report. Sort them first to release them settled. A release from a card sends the card’s answer as its handle, which the engine reads itself and refuses when it no longer reproduces.

A BIDS release needs dcm2niix. Where it is missing the release is refused before it starts and says what to do: Settings, Parts, Tools, Install, or Install from a file where the engine cannot reach the releases.

How it leaves

A dataset’s files leave under that dataset’s own policy for UIDs: remapped from the key, or kept. A release spanning datasets applies each dataset’s to its own files. A file under no dataset leaves with its UIDs remapped. The row records what each dataset’s files left under.

Every release keeps the real date. A release is pseudonymous, not anonymous: the date is what a clinical join reads, and the intervals between visits are the science. Where a date must not show in a path, name a session scheme that labels sessions by months since baseline (M00, M06).

Releases written before 1.0.0-alpha.37 that shifted their dates or cut them to the year still read as they were written.

The releases made

Releases is a table. Each row is a release: its name, version and layout, how its dates and UIDs left, its subjects and sessions, when and by whom, whether it was handed over, and whether it was withdrawn and why.

Hand over a release

A release stays a plain folder. Handing it over is an optional step that packs it for a receiver.

1. On the newest version of a name, press Hand over.
2. Choose the exchange place the archives go to.
3. Encrypt the archives is on. Under Password, choose Made by NILS, this handover’s own, or I type one and type it twice. Typing one is for the release’s maker and a holder of Handover passwords at work; anyone else sees the choice disabled, with what it needs.
4. To hand over unencrypted, turn Encrypt the archives off and say why. The reason is kept on the handover and in the audit.
5. Press Hand over. The newest version is packed into archives in the exchange place, apart from the tree, and read back once written.

Give the receiver the password

Each handover has a password of its own.

1. On Releases, press a version’s handed-over date. Its handovers open, each with where it went and how it is kept closed.
2. Press Show the password. It is offered to the release’s maker and to a holder of Handover passwords at see.
3. Copy it, tick I copied it, and press Done. The password is shown once, in a dialog of its own, and is gone when it closes.

Give it to the receiver apart from the archives. A password NILS made is never stored: it is made again from the key and the handover when asked. A typed one is kept sealed under the registry’s key. Neither is ever in an address, the browser’s storage or a log, and each showing is audited.

At the keyboard, a handover is nils handover run --release NAME --out DIR. Its password is made from the registry’s key, or the key --key names; --password-stdin takes a typed one from standard input, never from the command line; and --no-encrypt --why TEXT writes the archives unencrypted. nils handover password --handover ID prints one handover’s password. nils handover password --key NAME prints the old shared password, which opens the handovers made before each had its own. With an engine before 1.0.0-alpha.88, the dialog asks for the name of the key instead, and the password comes from that command.

Withdraw a version

1. On the row, press Withdraw.
2. Give a reason. It stays on the release for everyone to read.
3. Press Withdraw.

A release is never removed. Its files stay where they were written, and the row reads that it was withdrawn and why.

Session schemes

Session schemes lists the schemes the registry keeps. A kept name is never replaced, and a release names the scheme it used. Without one a release uses the registry’s own.

1. Press New scheme.
2. Give it a name.
3. Choose how sessions are named: Months from the first, By date or In order.
4. For months, give the visit months (0, 6, 12, 24 gives M00, M06, M12, M24) and within, months: how far from a visit’s month a session may sit and still take its label.
5. Give one session within, days: a study joins a session when it falls within that many days of its first study. 0 is the same day.
6. Press Keep it.

Rebuild visits

After a scheme changes, the visits are built again under it.

1. On Session schemes, press Rebuild visits. It needs work on Pipelines.
2. Under Under, choose the registry’s own scheme or a kept one. The dialog says what it will do: it builds the visits again under that scheme, for every subject whose studies changed.
3. Read the hint: a pick on a visit that moves follows it, and a pick on a visit that goes is withdrawn and asked about in Review.
4. Press Rebuild visits. It runs as a job, and the page says which.

How the files are named

There are three ways to name a stack, chosen per release: the descriptive layout, and two styles of BIDS.

Style	Written as	What it names
Descriptive	Ax_T2w_2D_FLAIR_TIRM_ND_3mm	everything, in the earlier NILS’s grammar
BIDS, full names	acq-Ax+2D+FLAIR+IRTSE_T2w	every axis that has no BIDS entity, in acq-, joined by +
BIDS, minimal names	acq-2D+FLAIR+IRTSE_T2w	only 2D or 3D, the modifiers and the technique

In both BIDS styles the suffix is the base contrast, or a construct suffix BIDS defines (ADC, FA, T1map, angio, asl). A FLAIR is always a modifier in acq-, never the suffix. Entities carry what BIDS has a place for: ce-, rec-, part-, echo-, inv-. Two stacks of one session that would share a name each carry what separates them, and a BIDS release is never refused for a name conflict. Every axis is in the sidecar either way. The descriptive layout is the earlier grammar whatever is asked, so names shows only beside BIDS, and Full names is what the engine writes unless asked. The releases table marks a release written with minimal names.

A BIDS release also writes a DICOM export under sourcedata/dicom/, at the path of each NIfTI, unless DICOM copies says otherwise, and a NILS object in every sidecar: each axis with the tier and confidence that decided it, the descriptive name, and the acquisition as measured. SyMRI’s images stay together under anat/SyMRI/. Re-running a release renames the files it moves.

Expert options

Below the release form, Expert options folds the release’s other options. Each starts at the engine’s own default and is sent only once changed, and the fold says how many are changed.

Option	Choices
Localizers	in sourcedata (default), in their datatype, in anat, or left out
Synthetic contrasts	in their folder (default), in anat, or in derivatives
DICOM copies	of every stack (default), of the stacks in a folder of their own, or none
Converter	dcm2niix as the engine finds it; a path to another dcm2niix only for a person with work on the install
Uncompressed NIfTI	.nii instead of .nii.gz
Authors	for dataset_description.json; whoever releases it unless named
Categories of element removed	patient, trial, provider, institution, times and IDs, all unless some are taken off; at least one
UID root	the arc new UIDs hang from: numbers joined by dots; DICOM’s UUID arc unless given
Only the picked scans	the stacks a pick chose
Only some roles	every role unless named

A value the engine would refuse holds Release, with the reason. Only the options the engine names are drawn, so an engine before 1.0.0-alpha.88 shows no fold.

At the keyboard they are flags of nils release:

nils release --name NAME --cohort COHORT --layout bids --localizers drop --out DIR

Option	Choices
--naming	full (default), minimal; the desk’s names
--localizers	sourcedata (default), datatype, anat, drop
--synthetic	folder (default), anat, derivatives
--dicom	all (default), folders, none
--converter PATH, --no-compress, --author NAME	the converter, .nii, and an author, which repeats
--categories LIST, --uid-root OID	the categories removed, and the UID root
--picked, --role ROLE	only the picked stacks, only a role, which repeats
--uids	overrides every dataset’s policy for this release
--dataset NAME	only the files under that dataset’s tree

The engine’s door is POST /api/releases, which takes datasets beside cohorts, and the expert options, each checked as its flag is before a job is queued. GET /api/capabilities names the options it reads in releases.expert.