Column Notes

Core Feature

This feature is available in all Portrai Explorer deployments.

A Note is one block of free text attached to a feature column: what the column is, how it was produced, and anything a reader should watch out for. Two columns both named celltype — one from an in-house pipeline, one from a public reference atlas — are otherwise indistinguishable; a note is what tells them apart.

Notes are kept separately from the cell data, so writing or editing one never touches the underlying data.

Stored in this browser only

Notes are stored locally in the browser they were written in. Clearing site data removes them, and they are not shared with other devices or other users. See Storage and Limitations.

Which Columns Can Have a Note

Every column can, including genes. There is no separate list of annotatable columns — select a column and the Note section is there. Signatures are scores rather than columns, and do not carry notes.

Annotating individual genes matters most for targeted panels. On platforms such as Xenium and CosMx, where the panel is a fixed set of probes rather than a whole transcriptome, per-probe caveats are exactly the kind of knowledge that otherwise lives in someone's head:

• "Ambient in this tissue — high background outside cells"
• "Below limit of detection in this run; do not interpret low values"
• "Probe cross-reacts with the family member; treat as pan-family"

Reading a Note

In the Details Panel

Select a column in the Explorer sidebar. The Note section sits at the top of the Details panel, above the column's Categories or Distribution:

• The note is shown with its line breaks preserved
• Updated <date> below it says when the note was last saved — useful for judging whether the note predates the last time the column itself changed
• If the column has no note yet, the section invites you to add one

There is no author name: notes never leave the browser that wrote them, so the reader is always the author.

On Hover

Hovering a column name in the feature list opens the usual column preview tooltip. If the column has a note, it appears below the scatter preview, separated by a divider.

The tooltip is a preview, so it differs from the Details panel in two ways:

• Long notes are trimmed to roughly four lines
• Links are shown as plain text — a link inside a tooltip cannot reliably be clicked, since the tooltip closes as the pointer travels toward it. Select the column to follow its links.

Finding Columns That Have Notes

A note is only worth writing if you can find it again, and on a Genes tab holding thousands of columns, scrolling is not finding. Two things in the feature list toolbar answer that:

• The Has note checkbox, at the right end of the search field, limits the list to columns that carry a note. Hover it to see how many the current tab holds before ticking it. See Filtering to Features with Notes.
• The search field matches note text as well as column names, so a word you wrote in a note finds its column. Searching ambient turns up every probe you flagged as ambient, whatever those probes are called.

Columns with a note are marked in the list with a small note icon, next to the column name. The icon is what tells you that a search result you did not expect matched on its note rather than on its name.

Everywhere a Column Is Picked

A note is worth writing because of the moment it is read, and that moment is usually not in the feature list - it is when you are about to plot the column, filter on it, or put it in a comparison. So the same search field, the same Has note checkbox and the same note icon appear in every column picker:

Where	What you are choosing
Explorer feature list	The column to colour the map by
Scatter plot X, Y and Color by	Plotted columns
Bar, box, dot, violin and stacked bar selectors	Group-by columns and plotted variables
Subset condition editor	The column a condition tests
Signature variable picker	The columns a score is built from

The caveat you recorded once is therefore in front of you at the point where ignoring it would cost you something, rather than filed somewhere you would have to think to look.

Signatures never carry notes

A signature is a score rather than a column, so there is nowhere to write a note on one. In pickers that list signatures alongside columns, ticking Has note empties the Signatures tab. That is the honest answer, not a fault.

Notes are keyed by column name, so a note written on a column in one tab is found by both tabs when two tabs hold a column with that name. See Notes Are Keyed by Column Name.

Writing a Note

1. Select the column in the feature list
2. In the Note section, click Add note — or Edit, if the column already has one
3. The section turns into an editor in place
4. Type the note and click Save

Cancel discards the edit. Remove deletes the note entirely and is only offered for a column that already has one; clearing the text and saving removes it just the same. Leading and trailing whitespace is trimmed when the note is saved.

There is no template — one text field, deliberately. What tends to be worth writing:

• The method or tool, with its version if it matters
• A reference: a URL or a DOI
• Whatever a reader should be careful about — a confidence floor, a category that is unreliable, a known artifact

For example:

Cell types called with TACCO against the HCA Lung Atlas v2
(https://doi.org/10.1038/...). Rare types are unreliable below ~5% of cells.

Links and DOIs

In the Details panel, references inside a note become clickable automatically:

• A full http or https URL
• A bare DOI such as 10.1038/s41586-021-03634-9, which links through doi.org

Links open in a new tab. Surrounding punctuation is handled the way prose actually writes references, so (https://doi.org/10.1038/...) links the address without swallowing the brackets.

Only http and https addresses ever become links, and a link is refused — rendered as plain text instead — when the address it would navigate to is not the address written in the note. That check is what stops a lookalike address from reading as one site while going to another. If something you expected to be a link is showing as plain text, the address is most likely malformed rather than the note being broken.

Notes on Imported Columns

The Import Metadata dialog has an optional Note field that attaches the same note to every column produced by that import, including any matched companion column. Recording the source of an annotation while importing it is far easier than reconstructing it later.

Notes on imported columns follow the column:

• Renaming an imported column carries its note over to the new name
• Deleting an imported column deletes its note as well, so it cannot re-attach itself to a future column that reuses the name

Notes can be edited afterwards from the Details panel like any other column's.

Storage and Limitations

Where Notes Are Stored

Notes are stored locally in your browser, per project:

• They are not shared with other devices, other browsers, or other users
• Clearing the site's browser data removes them
• Notes persist across sessions and page reloads

If a colleague needs the same annotations, the note text has to be shared some other way.

No local storage available

In a deployment that provides no local storage for notes, the editor says so while you type: notes are kept for the current session only and are lost when the tab closes.

Notes Are Keyed by Column Name

A note is attached to a column name, not to a particular version of the column's data. Two consequences:

• If a column is regenerated with different values under the same name, its note stays. The Updated date is what tells you whether the note predates the change.
• If two tabs contain a column with the same name, they share one note.

If a Note Cannot Be Saved

Saving is all-or-nothing, and a failure never leaves the panel showing something that was not stored:

• If the save fails, the note reverts to what was stored, an error is shown, and the button becomes Retry. Nothing you typed is lost — retry, or cancel to discard the edit.
• If the stored notes could not be read when the dataset opened, saving is refused with a message asking you to reload. This is deliberate: a save rewrites the whole set of notes, so saving on top of an unread set would erase the rest.

When a note changes as a side effect of renaming or deleting a column, a failure is reported as a notification with a Retry action instead.

Tips

1. Write the note when you create the column — the import dialog's bulk note is the cheapest moment to do it
2. Record the caveat, not just the method — the method is often recoverable later; the caveat rarely is
3. Paste the DOI — it becomes a link, and it dates the reference for you
4. Check the Updated date before trusting a note on a column that has been rebuilt
5. Annotate probes as you learn about them — one line per gene, at the moment you notice the problem
6. Write a word you will search for - notes are searchable, so a consistent term like ambient or below LOD gathers every column you flagged that way

Related Topics

• Import Metadata - Attach one note to every column of a CSV import
• Features - The feature list and Details panel where notes are read and written
• Signatures - Group continuous columns into a score