v3.0.0

CerebroNexus 3.0.0

Renamed package and application

• Unified the R package, Shiny application, and GitHub repository under the
  CerebroNexus name. Install from mihem/CerebroNexus and load the package
  with library(CerebroNexus).
• Kept the established Cerebro data model and public API, including .crb
  files, Cerebro_v1.3, Cerebro.options, launchCerebro(), and
  convertSeuratToCerebro().
• Updated the HLA export metadata field to CerebroNexus_version.

What's Changed

• Rename package and app to CerebroNexus by @mihem in #89
• style: format code via air by @mihem in #90

Full Changelog: v2.3.0...v3.0.0

v2.3.0

cerebroAppLite 2.3.0

HLA & TCR Motifs

• New page: HLA & TCR Motifs. A standalone top-level tab (peer of Immune
  Repertoire) that draws a CDR3 motif network — every unique CDR3 is a node and
  an edge joins two equal-length CDR3s at Hamming distance 1 — alongside
  donor-level HLA context. It appears conditionally, only when the loaded .crb
  carries a TRA/TRB chain. Three sub-tabs: Motif Network (colour by motif
  cluster, cell type, MHC context, HLA carrier status, or sample of origin),
  HLA Associations (descriptive carrier vs. non-carrier overlap — no p-value,
  no restriction claim), and Data & QC (coverage, normalized typing, and a
  session-only HLA upload).
• HLA typing on the data class. Cerebro_v1.3 gained an optional
  hla_typing slot with addHLATyping() / getHLATyping(); the getter is
  backward-compatible with older .crb files. Typing accepts a canonical long
  table, a wide sample + HLA-*_1/_2 table, or a named list, and carries
  provenance (genotyped / imputed / synthetic / unknown) so a synthetic
  or imputed genotype is never treated as directly typed.
• Export picks it up automatically. exportFromSeurat() now reads
  object@misc$hla_typing (with object@misc$hla_typing_source_type), parallel
  to the existing immune_repertoire slot.
• Declared contracts for bulk data. A .crb may declare
  observation_unit, receptor_key, and tcr_selection in technical_info, so
  the page states honestly when rows are analysis units rather than cells, when a
  receptor is keyed by V gene + CDR3, and when a carrier contrast is a positive
  control rather than independent evidence.
• One demo data set. demo_hla_tcr_dextramer.crb: 12,000 real CD8+ T cells,
  every one with a paired αβ clonotype, plus the donors' published HLA
  genotypes, from 10x Genomics' dextramer cohort (Zhang et al., Sci Adv 2021,
  CC-BY). The repertoire is antigen-selected, which is what makes its motif
  network legible on measured sequences, where an unselected repertoire gives a
  handful of disconnected dots. Class I only (sorted CD8+), so the Class I ×
  Class II pair scope stays hidden on this demo and appears when a data set
  carries Class II typing plus a lineage column.
  The per-cell dextramer_* columns are 10x's raw binder calls for a
  reagent, not validated peptide specificity: staining is heavily
  cross-reactive here, and a restriction_in_genotype (yes / no /
  unknown) column ships beside them so that is visible in the app rather than
  only in the vignette. unknown is not padding: table S1 publishes one HLA-B
  allele for two donors, and absence from an incompletely called locus is not
  evidence of absence. The HLA association contrasts use the published genotypes
  and are therefore not circular — though the repertoire was still captured by a
  reagent panel, so ascertainment and donor/panel confounding remain, which the
  caveat above the tables now states.
• Three new vignettes. "HLA & TCR Motifs: from synthetic data to an
  interactive app" (single-cell, runnable end to end), "HLA Associations on
  bulk TCRβ with real donor HLA" (bring your own bulk cohort, with its
  positive-control caveat), and "Antigen-selected single-cell TCR" (the
  shipped demo's full download → .crb pipeline).

What's Changed

• feat(hla): HLA & TCR Motifs page (2.3.0) by @duocang in #88

Full Changelog: v2.2.0...v2.3.0

v2.2.0

cerebroAppLite 2.2.0

Trekker single-cell spatial mapping

• New page: Trekker. A standalone top-level tab (peer of Spatial) for Curio
  Bioscience / Takara Bio Trekker single-cell spatial-mapping output — real single
  nuclei × whole transcriptome, with positions inferred from bead spatial barcodes
  and (usually) no matched histology image. It appears conditionally, only when the
  loaded .crb carries a trekker slot.
• Physical space and transcriptome space, linked. Because every nucleus has
  both a spatial and a UMAP position, the two scatterplots are shown side by side
  and cross-linked: a box- or lasso-select in one pane highlights the same nuclei
  in the other, and hovering a nucleus rings the same cell in both panes so its
  location reads off instantly. A toolbar matching the app's plotly modebar
  (box / lasso select, pan, zoom, reset, download) sits over the panes. The View
  control switches between side-by-side, a single enlarged Spatial-only or
  UMAP-only pane, and a Transition view that animates each nucleus from its UMAP
  position to its physical position. Colour by cell type, cluster, or any
  of the whole-transcriptome genes, and use the Group filters panel (the same
  per-grouping pickers as the projection tabs) to restrict the view to selected
  cell types or clusters.
• Positioning evidence is auditable. Trekker positions are inferred, so the page
  surfaces the vendor's per-nucleus positioning-evidence images (the bead-barcode
  cloud plus a UMI knee plot) for the sampled nuclei, and a Cell inspector reports
  each nucleus's identity together with the real physical-neighbour cell-type
  counts within a chosen radius (not a deconvolution estimate).
• Colour the physical map by any per-cell value — analysis, not just a view.
  Beyond cell type / cluster / gene, the page colours by cross-space metrics
  computed on the full positioned set — spatial-neighbourhood purity and
  expression-vs-physical neighbourhood concordance (who forms tight anatomical
  domains vs. who is dispersed or infiltrating, with a per-cell-type summary and
  the honest reminder that in a healthy brain low microglial purity is baseline
  tiling, not activation) — and by any numeric per-cell meta column the object
  carries (pseudotime, a signature/module score, velocity magnitude, a signaling
  score), so an existing single-cell analysis result gains a physical-space
  projection with no page change. The demo ships a myelination signature score as
  a worked example. Only Trekker can do this: it needs true single-cell identity
  and true physical position for the same nuclei.
• Canonical coordinates. The panes use the vendor's Location CSV, the canonical
  coordinate authority. The generic @images slot is axis-transposed and the
  SPATIAL reduction is y-mirrored relative to it; the vignette documents that
  discrepancy so the tissue is never silently drawn rotated.
• Honest QC. Positioning QC is shown in the vendor's own field names (a missing
  metric stays missing); "confidently positioned" is disclosed as including
  vendor-salvaged multi-location nuclei (labelled vendor_confidently_positioned);
  values below the vendor's reference range are flagged without adjudicating sample
  usability; and Moran's I is the upstream vendor value, labelled and never mixed
  with Cerebro's own.
• Data class. Cerebro_v1.3 gained an optional trekker slot with
  addTrekker() / getTrekker(); the getter is backward-compatible with older
  .crb files that predate the field.
• Demo data and vignette. A real, down-sampled demo .crb
  (demo_trekker.crb, from the smallest official Trekker bundle: 2,532 nuclei ×
  all 21,374 genes, with positioning-evidence images embedded) and a runnable
  vignette, "Trekker single-cell spatial mapping: from a vendor bundle to an
  interactive app", covering the registration-gated download, the bundle
  contents, and the reproducible build (data-raw/build_trekker_demo.R).

What's Changed

• feat(trekker): single-cell spatial-mapping page (2.2.0) by @duocang in #87

Full Changelog: v2.1.1...v2.2.0

v2.1.1

cerebroAppLite 2.1.1

Robustness and interface

• Plots fill the viewport. Projection and other plot panels grow to fit the
  available height through a single shared mechanism, so tall screens no longer
  leave large empty bands.
• Unified info buttons and tidier styling. The per-tab info buttons were
  consolidated onto one shared component and assorted inline CSS moved into the
  stylesheet.

Fixes

• Spatial axis sliders. Guard against empty coordinate ranges so the axis
  range sliders no longer emit Inf/-Inf warnings on data sets without
  spatial coordinates.

Testing / CI

• Raise the default shinytest2 load_timeout to 60s and wait for
  asynchronously inserted tabs before navigating, de-flaking the app tests on
  slower runners.
• Preserve the last shinytest2 output error when a retry times out, so failures
  report their original cause instead of an unexplained NULL value.

What's Changed

• feat: framework hardening, UI polish, and fixes by @duocang in #79

Full Changelog: v2.1.0...v2.1.1

v2.1.0

cerebroAppLite 2.1.0

Projection overhaul, unified interface, and cross-tab selection

• Shared projection renderer: the Overview, Gene expression, Trajectory and
  Clonal UMAP scatterplots now share one WebGL renderer instead of per-tab
  copies, so sizing, legend, hover and selection behave consistently across
  tabs. Each projection sizes itself to the available viewport and no longer
  flashes at the wrong size on first paint.
• Cell selection: box- and lasso-select persist across parameter changes,
  with a Clear button and a zoom-to-selection toggle on every projection tab.
  Hiding a group in the legend also excludes it from selected-cell counts, and
  the plot toolbar (lasso / box-select / zoom / pan / reset / PNG download) is
  available again.
• Interactive Clonal Diversity: the Clonal Diversity plot is now an
  interactive figure — hovering a point shows that group's bootstrap value.
• Interface: a lighter "Console" visual language with coloured sidebar
  icons, one warm palette shared by every chart (plotly and ggplot), and a fluid
  projection layout that reclaims the space freed by the removed top bar. A
  floating menu button keeps the sidebar reachable on phone-sized screens.
• Render feedback: a parameter change dims the projection while the new
  render is in flight, and the sliders are debounced so dragging no longer fires
  a render per step.
• Fewer empty tabs: the Marker genes and Most expressed genes sidebar items
  appear only for datasets that carry them (e.g. hidden for the spatial demos).
• Fixes: the spatial histology background is no longer cleared when another
  tab renders; the Clonal UMAP host reveals correctly after faceting is toggled;
  gene-expression multi-panel selection is restored; hidden-group state stays in
  sync with the server across re-renders; and the trajectory projection keeps
  its view on redraw.

What's Changed

• Projection viz cleanup, viewport sizing, and UI theme pass by @duocang in #76

Full Changelog: v2.0.1...v2.1.0

v2.0.1

cerebroAppLite 2.0.1

Robustness, performance, and deprecation cleanup

• Fixes: table rendering no longer errors on selected-cell slices whose
  percent_mt / percent_ribo columns are all NA, and the details table
  tolerates the transient NULL / NA a materialSwitch can emit while its UI
  re-renders; the group-centre helper returns an empty result instead of
  crashing when its grouping column is missing.
• Plot caching: projection hover-info, the groups and trajectory
  expression-metric violins, the groups composition bar/Sankey plot, and the
  Moran's I score are now cached per dataset (session-scoped, invalidated on
  dataset switch), so switching genes or re-rendering no longer recomputes them.
  The pseudotime plot selects scattergl up-front instead of converting the
  whole figure afterwards.
• Deprecations: replaced aes_string() with the .data[[ ]] pronoun and
  wrapped tidy-select group variables in all_of(), which also removes the
  per-call warning and roughly halves the composition cross-tabulation on large
  tables.

What's Changed

• Add later to explicit R environment dependencies by @mihem in #73
• chore: update default.nix by @mihem in #74
• Robustness fixes, plot caching, and deprecation cleanup by @duocang in #75

Full Changelog: v2.0.0...v2.0.1

v2.0.0

cerebroAppLite 2.0.0

Spatial analysis and overlay improvements

• Multi-gene co-expression: a new "Co-expression (RGB)" plot type maps up to
  three genes onto the red / green / blue channels, so each cell's colour blends
  the genes it expresses and spatial co-localisation reads as a mixed hue.
• Spatial autocorrelation: ImageFeaturePlot now reports the displayed gene's
  Moran's I — how spatially clustered its expression is (large slides are
  down-sampled for a responsive, stable score).
• Region outlines: an opt-in toggle outlines each colour group's spatial
  region with its convex hull.
• Copy alignment as preset: after hand-aligning a histology overlay, a button
  emits the matching spatial_images_* Cerebro.options lines to paste into an
  app so the dataset ships pre-aligned.
• Honest single-source overlay scale: the background scale is now applied
  once (a squared-scale bug is fixed), the image is clipped to the plot area so
  it no longer covers the axes, and the default view is evenly framed.
• Overlay controls UX: interacting with any Additional-parameters control
  collapses the Main-parameters box, and the Additional panel scrolls internally
  (hidden scrollbar with soft top/bottom fades), so the plot stays visible while
  adjusting Move/Rotate.
• Fixes: switching from an image-bearing platform to a bead-only one
  (Slide-seq) no longer leaves a stale tissue image behind, and the embedded-image
  option is offered only for datasets that actually carry one.

Spatial transcriptomics (interactive tab + histology overlay)

• Spatial tab: the interactive Spatial projection is now wired into the app.
  It mounts conditionally (via insertConditionalTab()) whenever the loaded
  dataset carries spatial data, with plotly-based coloring, group filters, and
  box/lasso cell selection.
• Histology background overlay: createShinyApp() gains spatial_images
  plus per-dataset spatial_images_flip_x, spatial_images_flip_y,
  spatial_images_scale_x, spatial_images_scale_y, and spatial_plot_rotation
  parameters. Matched images are copied into the app bundle and shown behind the
  cells, controlled by a Background image dropdown and an Image opacity
  slider. Unmatched entries are ignored with a warning rather than an error.
• Bundled demo: the "Cortex - Spatial (synthetic)" demo pairs fully
  synthetic cortical-depth cell coordinates (illustrative cell-type labels such
  as Excitatory L2/3 … Oligodendrocyte) with a synthetic H&E cortex-section SVG
  whose layer bands align with the cells, so cell types visibly stratify across
  the cortex out of the box. Both the coordinates and the image are synthetic —
  no patient data.
• Documentation: added the vignette("spatial_analysis") guide.
• Bundled demo set: the app now opens on demo_full_tcr_bcr.crb (PBMC,
  TCR + BCR + trajectory) plus four real spatial sections (Visium, Slide-seq v2,
  MERFISH, Xenium), so the dataset switcher spans immune-repertoire, trajectory,
  and spatial content. The two narrower PBMC subsets (demo_healthy_t.crb,
  demo_bcell_rich.crb) are no longer shipped — the Full set is their superset;
  data-raw/build_ir_demos.R can still rebuild them for a multi-sample demo.

Spatial transcriptomics (backend)

• Spatial data layer: the Cerebro_v1.3 class gains a spatial field with
  addSpatialData(), getSpatialData(), and availableSpatial() accessors.
• Export support: exportFromSeurat() now extracts spatial coordinates and
  expression from Seurat v5 image slots (Visium / Xenium / FOV) via the internal
  .getSpatialData() helper, storing them per image in the exported .crb.
• Utility wrappers: added availableSpatial(), getSpatialData(), and
  serverSideGeneSelector() in the Shiny utility layer.
• Demo dataset: bundled a synthetic Xenium spatial demo
  (demo_spatial.crb, 1,000 cells) as a fifth demo dataset.

What's Changed

• feat: interactive Spatial transcriptomics tab by @duocang in #71

Full Changelog: v1.7.8...v2.0.0

v.1.7.8

cerebroAppLite 1.7.8

Trajectory tab

• Trajectory module: restores the pseudotime trajectory explorer from the
  original cerebroApp v1.3 (projection coloured by state/pseudotime, states by
  group, expression metrics along pseudotime, per-state gene/transcript counts).
  The code is Roman Hillje's original implementation, restructured into the
  v1.4 sub-file layout with no functional change.
• Conditional tab: the Trajectory tab is inserted dynamically
  (insertConditionalTab) only for data sets whose .crb carries trajectory
  data — the same content-driven sidebar mechanism used by the Immune
  Repertoire and Extra material tabs.
• Demo data: the monocle2 pseudotime trajectory is now bundled inside the
  demo_full_tcr_bcr.crb demo (computed on its B-cell subset) instead of a
  separate demo_trajectory.crb, so one demo shows TCR + BCR + trajectory. The
  trajectory is reproducible via data-raw/build_trajectory_demo.R.

What's Changed

• feat: pseudotime Trajectory tab by @duocang in #69
• style: format code via air by @mihem in #70

Full Changelog: v1.7.7...v1.7.8

v1.7.7

cerebroAppLite 1.7.7

Multiple data sets (multi-crb)

• Dataset switcher: createShinyApp() now accepts a named vector of several
  .crb files and renders a "Select dataset:" dropdown in the sidebar, letting
  users move between data sets without restarting the app. Single-file usage is
  unchanged and shows no switcher. By default the smallest file is loaded first
  (crb_pick_smallest_file, default TRUE).
• URL selection: a data set can be opened directly via the URL, matched by
  the name given in cerebro_data or by file basename — either as a query
  string (?dataset=TCR) or as the last path segment (/TCR).
• Demo data sets: three genuinely distinct demo .crb files ship in
  inst/extdata/v1.4/ — demo_full_tcr_bcr.crb (all cells, TCR + BCR),
  demo_healthy_t.crb (T + monocytes, TCR) and demo_bcell_rich.crb (B-cell
  rich, BCR). They differ in cell composition, so the UMAP and cell-type mix
  change as you switch, and clonotypes are assigned by lineage (TCR to T cells,
  BCR to B cells) rather than at random. Group-level analyses (marker genes,
  most-expressed genes, enriched pathways) are filtered to the cell types kept
  in each subset, so the demos are internally consistent. Built from the public
  10x Genomics vdj_v1_hs_pbmc3 dataset; see data-raw/README.md for the
  reproducible build. The bundled app (shiny::runApp("inst")) now opens on
  these three data sets so the switcher is visible out of the box; pass a named
  vector to createShinyApp() for your own data (see vignette("multi_crb")).
  New vignette: Loading multiple data sets (multi-crb) with a dataset
  switcher.

Immune repertoire

• Clonal UMAP no longer renders blank when the Immune repertoire tab is
  opened after visiting another tab (e.g. Main). The plotly renderer was gated
  on server-reported plot dimensions, which are not yet available when its
  output element is created on tab switch; plotly sizes itself client-side, so
  that gate was removed.

What's Changed

• feat: multi-dataset switcher (multi-crb) + Clonal UMAP fixes by @duocang in #68

Full Changelog: v1.7.6...v1.7.7

v1.7.6

cerebroAppLite 1.7.6

Immune repertoire

• Clone Sharing tab: classifies every clonotype (V+J+CDR3 of the active
  chain) as Private (in a single unit), Public within-group, or Public
  cross-group, using a configurable "sharing unit" (any categorical metadata
  column, default sample) and the active group column. With no group selected
  it degrades to Private / Shared. Interactive plotly bars with on-bar
  count/percentage labels and a clean hover tooltip (one class per bar, no raw
  aesthetic names).
• Definition (clone-definition resolution waterfall) is available but hidden
  from the default tab strip: it is an exploratory check for choosing a
  clone-call resolution rather than a reader-facing figure. Uncomment its
  tabPanel to re-enable.

What's Changed

• feat(ir): add Definition & Clone Sharing analysis tabs by @duocang in #65

Full Changelog: v1.7.5...v1.7.6