Skip to content

Allow users to define canonical experiment channel names and record them in the run manifest #170

Open

Description

@guijacquemet

Problem

Preprocessing currently records per-file channel names only when image metadata provides them. They are observational metadata in each FileEntry; unnamed channels remain unnamed.

The notebook should let the user explicitly name the experiment's channels when metadata are missing or incomplete.

This is also needed before we can sensibly verify/channel-map heterogeneous acquisitions.

Design rule

Keep source metadata separate from user-stated experiment identity.

Do not overwrite FileEntry.channel_names: those fields should continue to mean “what this source file's metadata said”.

Add an experiment-level canonical channel schema, for example conceptually:

index   name        source
0       DAPI        stated
1       ACTIN       stated
2       PAXILLIN    header

The exact storage can be decided during implementation, but it should be reproducible and editable. A small input file such as channels.csv / channel_schema.csv in the output folder, with its SHA-256 recorded by run_manifest.json, would preserve the same source-vs-stated provenance pattern used for calibration/design.

The final resolved canonical names should also be directly available from the run manifest / RunInputs so later bricks do not reinterpret them.

Notebook

After channel count/axis roles are known:

  • show one row per canonical channel index;
  • prefill names from metadata only when all relevant named metadata agree;
  • otherwise leave the name explicitly unset;
  • let the user state/edit names;
  • show where each name came from: header / stated / unnamed;
  • show representative channel images alongside or near this card (see the representative-image QC issue).

Nothing is guessed from image appearance.

Consistency rules

  • A stated name applies to the canonical experiment channel index, not to filenames.
  • Duplicate canonical names should be refused unless we explicitly decide they are allowed.
  • Empty/NA-like names should be refused with the same identity discipline as other MorphoBricks identifiers.
  • Existing source metadata that contradict a stated canonical mapping must be shown explicitly; do not silently override the mismatch.
  • A change to channel names should not require histogram pixels to be recomputed if channel indices/order are unchanged, but it must create a new manifest/provenance generation.
  • Later bricks should read canonical names from preprocessing, not invent their own naming mechanism.

Acceptance

  • Notebook can name unnamed fluorescence channels.
  • Metadata names and user-stated names remain distinguishable in provenance.
  • Canonical channel names are recorded in/with the preprocessing run and exposed through RunInputs.
  • Reruns restore the stated names.
  • Renaming a channel without changing order does not reread image pixels.
  • Contradictory source metadata are never silently hidden.
  • Channel names are validated as strict text identities.
  • CLI/API has an equivalent way to provide/read the same channel schema.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions