Exporting analysis results#

Audience: everyone (especially wet lab + computational users preparing reports)
Time: 10–20 minutes
What you’ll learn:

  • What analysis artifacts can be exported (tables, plots)

  • What exports are “stable artifacts” vs ephemeral UI state

  • How analysis exports relate to Figure Export and Sessions

Prerequisites:

  • A dataset loaded

  • At least one analysis result generated (any mode)

What “export” means in Analysis (and what it does not mean)#

Cellucid’s Analysis UI supports exporting two kinds of artifacts:

  1. Plots (PNG / SVG)
    A snapshot of what you see in the analysis result plot at the time you export.

  2. Tables (CSV)
    A machine-readable artifact you can load into R/Python/Excel.

Exports are downloads from your browser:

  • files typically land in your OS/browser “Downloads” location,

  • filenames are generated by the app (you can rename them after download).

Exports are not:

Important

In the current build, most analysis CSVs do not embed full provenance (dataset id, page names, thresholds, etc.).

If you need paper-grade reproducibility, export the CSV and save a session (and/or keep a lab notebook record of settings).

Fast path (save something you can share)#

Goal: export one plot for reporting and one table for re-analysis.

  1. Run the analysis you care about (Detailed / Correlation / DE / Gene Signature / Marker Genes / Dot plot / Composition)

  2. Open the expanded view

    • click ⤢ Expand in the result’s action row

  3. In the expanded view, use the export buttons

    • PNG / SVG for plots

    • CSV for tables

  4. Immediately rename the downloaded files (recommended)

    • include dataset name, page names, method, and date, e.g.
      pbmc_demo__DE__T_cells_vs_rest__wilcox__2025-01-02.csv

Tip

For wet lab / reporting workflows:

  • export PNG for slides and lab meeting decks,

  • export SVG only if you need vector editing (Illustrator/Inkscape),

  • export CSV for anything you might re-plot or statistically analyze later.

Where export controls live (UI map)#

Exports are attached to the analysis result view, not to the overall app.

Typical patterns:

  • Detailed / Correlation / DE / Gene Signature / Marker Genes / Dot plot / Composition: every mode that produces an expandable result renders a ⤢ Expand button in its action row; export from the modal it opens. The button is the only way in — the preview itself is not clickable.

  • Quick: no formal “export” controls (use it as a summary; screenshot if needed).

In the expanded view you should see an Export: row with buttons:

  • PNG

  • SVG

  • CSV

If you don’t see export controls, it usually means:

  • no result has been computed yet, or

  • the mode does not support export, or

  • you are not in the expanded modal view.

What each mode exports (exact CSV schemas)#

This section is deliberately explicit so you can build downstream tooling.

Detailed Analysis#

  • Plot export: PNG / SVG of the currently selected plot type and options.

  • CSV export: per-cell values for the selected variable.

    • Filename: detailed-analysis-data.csv

    • Columns:

      • page: the page name

      • cell_index: the cell’s row in the whole dataset in its original order (0-based), also when a subsample is open

      • <variable>: the exported value: the number, or the category label for a categorical variable (empty for a missing value)

Note

This is always the schema. The plot type on screen changes the picture, never the file — a bar plot, a violin and a histogram of the same variable export the same per-cell rows.

It follows that the CSV can be large: one row per cell, per selected page. There is no summary-only variant, so if the file would be unmanageable, narrow the comparison (fewer or smaller pages) before exporting rather than looking for a different button.

The file is written by the analysis workers, each writing a range of rows, so even a half-million-row export does not hold up the page while it is built.

Correlation#

  • Plot export: PNG / SVG of the correlation scatter plot as rendered.

  • CSV export: one row per page with correlation statistics.

    • Filename: correlation_results.csv

    • Columns:

      • page

      • method (pearson or spearman)

      • x_type, x_key (what X is)

      • y_type, y_key (what Y is)

      • r, r_squared

      • p_value

      • n (paired values used)

Note

The exported plot may show a downsampled subset of points for rendering performance. The exported CSV statistics (r, p_value, n) are computed on the full paired data.

Differential Expression (DE)#

  • Plot export: PNG / SVG of the volcano plot with the current filters and labels.

  • CSV export: one row per gene — every gene tested or not, whatever the filters.

    • Filename: differential_expression.csv

    • Columns (scanpy’s rank_genes_groups_df names where one exists):

      • names (the gene’s identifier: the var index, what adata.var_names holds — Ensembl ids for a CELLxGENE file)

      • symbols (the name the viewer shows; only when it differs from the identifier for some gene)

      • scores (Wilcoxon z, or Welch’s t)

      • logfoldchanges (as Fold change from chose)

      • pvals, pvals_adj (Benjamini–Hochberg or Bonferroni)

      • pct_nz_group, pct_nz_reference (share of Group A’s / Group B’s cells not zero, 0–1)

      • auroc (Wilcoxon)

      • mean_a, mean_b, n_a, n_b (each group’s mean, and its cells with a measured value)

    • A gene that was not tested has empty statistics.

Important

The DE CSV does not include the group names or the test options. Record them yourself (file rename, notes, or session).

Gene Signature#

  • Plot export: PNG / SVG of the signature score plot.

  • CSV export: one row per scored cell and gene set.

    • Filename: gene_signature_scores.csv

    • Columns:

      • page

      • set (the gene set’s name)

      • cell_index (the cell’s row in the whole dataset in its original order, 0-based)

      • score (as computed: Rescale changes the plot, not the file)

cell_index joins the scores back to adata.obs (row cell_index) of the whole dataset in its original order, and each page’s rows ascend by it: with a subsample open it names rows of every cell, and a file Cellucid wrote (stored in priority order) is read back in that order with cellucid.restore_original_order() (R: cellucid_restore_original_order()).

Marker Genes (Genes Panel)#

From the expanded view:

  • CSV — the markers shown, one row per group and marker.

    • Filename: marker_genes.csv

    • Columns: group, rank, names, (symbols), scores, logfoldchanges, pvals, pvals_adj, pct_nz_group, pct_nz_reference, auroc, small_group

  • All genes CSV — every gene of every group, whatever the filters, in dataset gene order.

    • Filename: marker_genes_all.csv

    • Columns: group, names, (symbols), scores, logfoldchanges, pvals, pvals_adj, pct_nz_group, pct_nz_reference, auroc, small_group, tested

    • tested is false for a skipped group and for the reference group; their statistics are empty. A gene not tested in a tested group has empty statistics too.

  • GMT — the markers shown, one gene set per group.

    • Filename: marker_genes.gmt

    • One line per group: the group name, Cellucid marker genes, then its genes, tab-separated (MSigDB’s format; Gene signature and Dot plot import it).

names is each gene’s identifier, as scanpy’s names and every other place Cellucid hands a gene back (sessions, gene sets, the notebook) name it, so the table joins to adata.var_names; symbols, the names the viewer shows, is written beside it only when the two differ (a CELLxGENE file: Ensembl ids in the var index, symbols shown). The column names are scanpy’s rank_genes_groups_df; pct_nz_group and pct_nz_reference are fractions (0–1). group is the category name exactly as the heatmap and the group picker show it. small_group is true for a group with fewer cells than Min cells per group (a pool of small groups counts as one group).

Dot plot#

  • CSV export: one row per group and gene, unscaled means.

    • Filename: dot_plot.csv

    • Columns: group, gene, gene_group (the gene set), mean, fraction_expressing, n_cells

    • See Analysis mode: Dot plot.

Composition#

  • CSV export (expanded view): with a condition, one row per cell type.

    • Filename: composition_results.csv

    • Columns: cell_type, mean_proportion_<condition> per condition, log2_ratio, test, statistic, pvalue, pvalue_adjusted, n_samples_<condition> per condition

    • Without a condition it downloads the counts instead.

  • Counts CSV (under the summary): composition_counts.csv, cell_type and one column of cell counts per sample (or condition).

  • See Analysis mode: Composition.

Note

Every CSV quotes any field that contains a comma, a quote or a newline, and doubles an embedded quote, so a comma inside a category name is carried into one cell rather than splitting the row. Read them with a real CSV parser (pandas.read_csv, readr::read_csv) rather than by splitting on commas.

Reproducibility notes (what to record)#

If you need to reproduce an export later, record:

  • dataset identity (dataset name/id, dataset file version)

  • active view/snapshot (if relevant to your workflow)

  • selected pages (names + sizes)

  • selected variables (obs key / gene id + how genes are resolved)

  • method settings (Pearson vs Spearman; the DE / marker test, p-value convention, correction and fold change; the signature method)

  • filters and plot options (DE and marker filters; ranking; log axes; labels)

Recommended workflow:

  1. Save a session: Session Saving, Restoring, and Sharing

  2. Export CSV(s)

  3. Export plot(s) (PNG for sharing; SVG for editing)

  4. Rename files with the important settings

Troubleshooting exports#

Symptom: “Nothing downloads when I click PNG/SVG/CSV”#

Likely causes:

  • browser blocked automatic downloads,

  • you are not in the expanded view (no export toolbar),

  • the analysis did not produce a result yet.

Fix:

  • re-run the analysis and open the expanded view,

  • allow downloads for the site,

  • if a managed-browser policy blocks downloads, ask the administrator to allow downloads from the Cellucid origin.

Symptom: “The CSV is empty”#

Likely causes:

  • the analysis returned no valid values (missing data, tiny pages, all-NaN),

  • gene expression is unavailable (expression-based modes),

  • the mode exports a different artifact than you expected (e.g., correlation exports summary statistics, not point-level data).

Fix:

  • confirm you have non-empty pages,

  • confirm gene expression is available,

  • verify the mode’s expected CSV schema above,

  • see Troubleshooting (analysis) for analysis-wide diagnosis.

Interface reference#

The export row of an expanded analysis result: an Export label followed by PNG, SVG and CSV buttons.

The export row, identical in every mode: PNG, SVG, CSV. There is no PDF export anywhere in the analysis panel.#

The expanded Marker genes view of cell_type with a clustered heatmap and dendrograms in the plot area, an Export row of PNG, SVG and CSV buttons above the plot options, the summary statistics naming the field, method and counts, and the table of top marker genes, with a pointer on the CSV button; the run-time Duration row is omitted.

The expanded Marker Genes result combines the heatmap, the method summary, the ranked table, and the PNG, SVG and CSV export actions. Exports exist only here — the sidebar preview has none.#

Next steps#