Import Metadata

Core Feature

This feature is available in all Portrai Explorer deployments.

Import Metadata adds new feature columns to the current dataset from a CSV file. Any per-cell annotation you produced outside Portrai Explorer — cell type calls from another tool, a manual region label, a score computed in a notebook — can be joined onto the dataset and then used exactly like a pipeline column: for color mapping, subsetting, plots, and CSV export.

The join is keyed by the dataset's index column, so the CSV does not have to be in dataset row order and does not have to cover every cell.

Stored in this browser only

Imported columns are stored locally in the browser you imported them in. They are not uploaded to the server, and they are not shared with other devices, other browsers, or other users. Clearing site data removes them. See Storage and Limitations.

Opening the Import Dialog

There are three ways to start an import:

1. In the Explorer sidebar, click the Import metadata button (upload icon) in the Features panel header
2. Or drag a .csv file from your file manager onto the feature list — the dialog opens with that file already loaded
3. Or open the dialog first and drop a CSV anywhere inside it, onto the marked area or not

TIP

The Import metadata button is hidden while the Signatures tab is active, where the header offers Create Signature instead. Switch to any feature tab to import. Dropping a CSV works from any tab.

Both drop targets accept only files whose name ends in .csv, and both take a single file. They differ in what they say about it: the sidebar ignores anything else without comment and quietly keeps only the first of several files, while the dialog reports why it refused and asks for one file at a time.

Opened from the toolbar button, the dialog starts empty — click Choose CSV to pick a file, drop one onto the dialog, or use Download template to get a file with the right keys first (see Starting From a Template). The loaded file's name is shown next to the Choose CSV button.

Dropping a CSV while a file is already loaded replaces it, unless an import is running, which the dialog says rather than ignoring the drop. A file or a link dropped on the dimmed area outside the dialog does nothing at all, rather than sending the browser off to open it and taking your settings with it.

Preparing the CSV

The file needs one column of cell keys plus one column per annotation you want to add:

index,celltype,confidence
cell_00001,T cell,0.94
cell_00002,B cell,0.71
cell_00003,Macrophage,0.88

Starting From a Template

The surest way to get the keys right is Download template in the import dialog. It writes a CSV holding just this dataset's index column, one row per cell:

index
cell_00001
cell_00002
cell_00003

Add your own columns beside it and import the result.

This matters more than it looks. When a dataset has no ID column, or an individual cell's ID is missing, that cell is keyed by its row number, and nothing else in the interface tells you so. A template always carries the keys the join actually uses.

The template covers the whole dataset, not the current filter or subset. An import may still cover only part of it, which is what Filling Missing Cells is for.

A template is a snapshot of the rows as they are now. If the dataset is later regenerated with different cells, an old template's keys no longer match, and the import is blocked as unrecognized keys rather than joined to the wrong rows.

If you would rather start from values you already have, download a column and edit it instead — see CSV Export. The per-column download writes the same index column.

Accepted formatting:

Aspect	Supported
Line endings	LF or CRLF; a trailing newline is fine
Quoting	Standard CSV quoting — quoted fields may contain commas, newlines, doubled quotes
Short rows	Padded with empty cells
Extra cells	Cells beyond the header width are ignored, so stray trailing commas do not shift columns
Blank rows	Ignored, and counted next to the row total
Blank cells	Given the column's fill value (see Cells With No Value)

A file is rejected outright, with the reason shown in the dialog, when it is empty, has no header row, has duplicate column headers, or has an unterminated quoted field.

Blank Rows

A row holding nothing at all is dropped before the join, whatever its width. That covers a trailing newline, a line of nothing but spaces, and the ,,, line that spreadsheet and dataframe exports often leave at the end of a file. The dialog reports how many were dropped beside the row count, so an ignored row is never silent.

A row that has values but no key is a different case: it cannot be joined to anything, so it is skipped and reported as a warning naming the count and the key column. If the key column is one that holds nothing, every row is skipped this way and the import is blocked outright rather than producing columns of pure fill.

Choosing the Key Column

The dialog picks the key column automatically: a header named index if the file has one (the match ignores case and surrounding spaces), otherwise the first column. Use the Key column selector to choose a different one.

Next to the selector, the dialog reports how the keys line up:

• A badge showing <matched> / <total> matched — how many rows in the file matched a cell in this dataset, against the dataset's total number of cells. The badge is green only when every key in the file is recognized and at least one row matched; it is red when some keys are unrecognized, and also when nothing matched at all.
• The number of data rows in the file, followed by the number of blank rows that were ignored when the file has any

Changing the key column re-analyzes the file immediately, so you can try another column if the match count looks wrong.

Datasets without an ID column

If the dataset has no ID column configured, cells are keyed by their row index (0, 1, 2, …) — the same keys the Explorer's CSV export writes for such a dataset. Download template hands you those keys directly, so you do not have to guess.

Configuring Each Column

Every column in the file except the key column gets a row in the dialog's table.

Control	What it does
Import	Whether to import this column. Selected by default, except for a column that holds no values at all.
Name	The name the column will have in the Explorer. Pre-filled from the CSV header, and editable.
Type	categorical or continuous.
Order	Category order, for categorical columns. See Ordering Categories.
Fill missing	The value given to every cell the file does not supply one for. See Filling Missing Cells.

Names and Collisions

If the suggested name is already taken — by a pipeline column, a gene, or another column in the same import — the dialog appends _1, _2, and so on to make it unique. You can still edit the name freely; a name that collides is reported as a blocking issue rather than silently renamed.

Type Inference

The type is inferred from the cell values and can be overridden:

• continuous when the column has at least one non-empty cell and all of them parse as finite numbers
• categorical otherwise

Switching a numeric column to categorical is useful for cluster IDs and other numbers that are really labels. Switching a categorical column to continuous is the escape hatch for a column with too many distinct values to be a category (see Validation).

Filling Missing Cells

A cell can end up without a value for two reasons: the file does not cover that cell's row at all, or the row is there but the cell is empty. Both get the Fill missing value:

• Categorical — a label, defaulting to Unassigned. The fill label is only added as a category if at least one cell actually needs it, so a file covering every cell produces no empty extra category.
• Continuous — a number, defaulting to one less than the column's minimum value so filled cells are visually separable from real values (or 0, for a column with no numeric values).

Cells With No Value

A cell the file carries but leaves empty takes the fill value, exactly like a cell in a row the file omits. A cell holding only spaces counts as empty too.

The imported column alone therefore cannot tell the two apart, so the dialog reports how many blank cells the file has, and in which columns, as a warning above the table. When the distinction matters, add the matched companion column: it records per cell whether the file supplied a value, so both kinds of filled cell read as unmatched there while every real value reads as matched.

A column with no values anywhere in the file would import as a single fill category carrying no information, so it starts unchecked and the dialog says why. You can still import it if you want the placeholder.

Ordering Categories

For a categorical column, the Order cell lists the column's categories with the number of cells in each. This order becomes the column's category order everywhere it is used — the legend and the assigned colors both follow it.

• Drag a row by its handle to move it (keyboard drag is supported as well)
• Or apply one of the sort buttons:

Button	Order
Natural	Numeric-aware alphabetical, so cluster_2 comes before cluster_10
By count	Most cells first, ties broken by natural order
A-Z	Alphabetical, ascending
Z-A	Alphabetical, descending

The fill label for missing cells is added after the categories you ordered, unless it happens to be one of them — in which case it keeps the position you gave it.

The matched Companion Column

A matched column checkbox appears under the fill value of every column, whatever its type. Enabling it adds a second, categorical column named <name> matched that records, per cell, whether the file supplied a value:

• Categories are matched and unmatched, and only the ones that actually occur are created
• A cell reads as unmatched both when the file omits its row and when the file leaves its cell empty, so this is the column to use whenever a filled cell has to be told from a real one
• Color or subset by it to see exactly which cells the import covered — useful when the fill value is inside the real data range and the imported column alone cannot tell you

The companion counts as an imported column for naming purposes, so <name> matched must also be free.

Validation

Issues are listed above the column table and update as you edit. Red issues block the import; amber issues are warnings you can proceed past.

Blocking:

Issue	Meaning
Unrecognized keys	Keys in the file are not in this dataset. The count and a few examples are shown — usually the wrong key column, or a file from another dataset.
Duplicate keys	A key appears more than once in the file. Remove the duplicates and import again.
No data rows	The file has a header but no rows left to import, because it had none or every row was blank.
Nothing matched	No row in the file joins to this dataset, and no key was unrecognized either. Usually the key column selected holds no keys at all.
Only the key column	The file has nothing but the key column, as a freshly downloaded template does. Add at least one column of values beside it.
No column selected	At least one column must be checked under Import.
Empty name	A column's name cannot be blank.
Name already exists	The name is taken by a column already in the dataset.
Companion name taken	<name> matched is taken by a column already in the dataset. Rename the column, or clear its matched column checkbox.
Name used twice	Two columns in this import resolve to the same name.
Too many categories	A categorical column has more than 64 categories, counting the fill label when any cell needs it. Import it as continuous, or reduce the number of categories.
Non-numeric fill value	A continuous column's fill value must be a number.

Warnings:

Issue	Meaning
Fill value within range	The fill value falls inside the column's own data range, so unmatched cells will be indistinguishable from real values. Pick a value outside the range, or add the matched companion column.
Non-numeric cells	Some cells in a continuous column do not parse as numbers and will receive the fill value instead.
Rows with no key	Rows in the file have an empty key cell and were skipped, since there is nothing to join them on. The count and the key column are named.
Blank cells	A column has cells the file leaves empty. They take the fill, so they cannot be told from rows the file does not cover. See Cells With No Value.
Column with no values	Every cell of the column is blank in the file, so importing it produces a single fill category. Such a column starts unchecked.

Adding a Note to the Import

At the bottom of the dialog, Note (optional) expands into a text field whose contents are attached as the Note of every column this import creates, including any matched companion — they all came from the same file and the same method.

This is the fastest way to record where an annotation came from while you still have the details at hand. Each column's note can be edited individually afterwards from the Details panel — see Column Notes.

Completing the Import

Click Add columns. The columns are built off the main thread, injected into the dataset, and a confirmation notification reports how many were added.

The Features panel then takes you to the result: the User tab becomes active, the feature list scrolls to the first of the imported columns, and the columns the import added are tinted for a couple of seconds so you can see what arrived. Any text in the feature search box is cleared, since a leftover search would filter the new columns out of the list.

Coloring is left as it was. The imported columns are not selected for you, so the map behind the dialog does not change until you pick one.

Working with Imported Columns

Imported columns are collected in a User tab in the Features panel, created the first time you import and removed again when the last imported column is deleted.

They behave like any other feature column — color mapping, subsetting, plots, and CSV export all work the same way.

Two controls appear on imported column rows that pipeline columns do not have:

• Rename (pencil) — opens a rename dialog. A name already in use is rejected. The column's Note follows the new name.
• Delete (trash) — removes the column and its note.

Pipeline columns are read-only and offer neither.

Storage and Limitations

Where Imported Columns Are Stored

Imported columns are stored locally in your browser and restored the next time you open the same project:

• They are not sent to the server
• They are not shared with other devices, other browsers, or other users
• Clearing the site's browser data removes them

Anyone else who needs the same columns has to import the CSV themselves.

Restoring After the Dataset Changes

An imported column is stored as one value per dataset row, aligned by row position. If the dataset is regenerated with a different number of rows, the stored values no longer line up, so the column is not restored. Instead it is skipped and a warning notification lists the columns that were dropped:

Some imported columns were not restored — <column names> no longer match this dataset's rows (the data may have changed). Import again to restore.

Import the CSV again to get those columns back. Because the join is keyed by the index column, re-importing the same file against the updated dataset is safe.

WARNING

A dataset regenerated with the same number of rows but a different row order cannot be detected. The columns will be restored and will be silently misaligned. If a dataset has been rebuilt, re-import rather than relying on the restored columns.

Tips

1. Round-trip through export — download an existing column as CSV, edit it, and import it back; the keys are already correct
2. Check the matched badge first — a much smaller number than expected almost always means the wrong key column
3. Use the matched companion for partial imports, so "no value" is never mistaken for a real measurement
4. Set the category order in the dialog — it is what the legend and the colors follow
5. Write the note while importing — the bulk note field costs one paragraph now and saves guessing later

Related Topics

• Column Notes - Record what a column is and how it was produced
• Features - How feature columns are browsed and used
• CSV Export - Export a column to get a correctly keyed file
• Color Mapping - Color the map by an imported column
• Subset - Subset by an imported column