@genome-spy/app 0.74.0 → 0.76.0

package/src/sampleView/types.d.ts

@@ -0,0 +1,125 @@
+import { ViewAttributeSpecifier } from "./sampleViewTypes.js";
+import { SampleHierarchy } from "./state/sampleState.js";
+import { ChromosomalLocus } from "@genome-spy/core/spec/genome.js";
+import { Scale } from "@genome-spy/core/spec/scale.js";
+
+/**
+ * Stable identifier for an abstract attribute used by actions and agent
+ * context.
+ *
+ * `type` identifies the attribute source kind, and `specifier` contains the
+ * concrete lookup information for that source.
+ *
+ * Examples:
+ * - `{ type: "SAMPLE_ATTRIBUTE", specifier: "age" }`
+ */
+export type AttributeIdentifierType =
+    | "SAMPLE_ATTRIBUTE"
+    | "VALUE_AT_LOCUS"
+    | "SAMPLE_NAME"
+    | "VIEW_ATTRIBUTE";
+
+export interface AttributeIdentifier {
+    type: AttributeIdentifierType;
+    specifier?: string | ViewAttributeSpecifier;
+}
+
+/**
+ * One endpoint of an interval.
+ */
+export type IntervalPoint = number | ChromosomalLocus;
+
+/**
+ * Interval expressed as two scalar or locus points.
+ */
+export type Interval = [IntervalPoint, IntervalPoint];
+
+/**
+ * Aggregation operators supported by interval-based attribute access.
+ */
+export type AggregationOp =
+    | "itemCount"
+    | "min"
+    | "max"
+    | "weightedMean"
+    | "variance"
+    | "count";
+
+/**
+ * Aggregation configuration for interval-derived attribute access.
+ */
+export interface AggregationSpec {
+    op: AggregationOp;
+}
+
+/**
+ * Arguments passed to attribute value providers, including the current
+ * selection of sample ids and optional interval/aggregation context.
+ */
+export interface AttributeValuesScope {
+    sampleIds: string[];
+    sampleHierarchy: SampleHierarchy;
+    interval?: Interval;
+    aggregation?: AggregationSpec;
+}
+
+/**
+ * Context passed to attribute availability hooks.
+ */
+export interface AttributeEnsureContext {
+    signal?: AbortSignal;
+}
+
+export interface AttributeInfo {
+    /**
+     * A concise name of the attribute: TODO: Used for what?
+     * @deprecated Use attribute instead
+     */
+    name: string;
+
+    attribute: AttributeIdentifier;
+
+    /** More detailed name with optional formatting */
+    title: string | import("lit").TemplateResult;
+
+    /** Formatted attribute name for context menus (e.g., with selective emphasis). */
+    emphasizedName: string | import("lit").TemplateResult;
+
+    /**
+     * Optional description of the attribute. Can be used in UI and agent
+     * context to explain the meaning of the attribute.
+     */
+    description?: string;
+
+    /** Function that maps a sampleId to an attribute value */
+    accessor: (sampleId: string, sampleHierarchy: SampleHierarchy) => any;
+
+    /**
+     * Provides values for dialogs (e.g., histograms) with optional interval aggregation.
+     * Use `extractAttributeValues` for the default fallback implementation.
+     */
+    valuesProvider: (scope: AttributeValuesScope) => any[];
+
+    /** e.g., "quantitative" */
+    type: string;
+
+    /**
+     * Optional hook for ensuring attribute availability before access.
+     * Used by async intent processing to resolve lazy data dependencies.
+     */
+    ensureAvailability?: (context: AttributeEnsureContext) => Promise<void>;
+
+    /**
+     * Optional hook for awaiting post-dispatch readiness.
+     * Used by async intent processing to guarantee that state and data are ready.
+     */
+    awaitProcessed?: (context: AttributeEnsureContext) => Promise<void>;
+
+    scale?: any;
+
+    /**
+     * Authored scale definition for the source encoding, when available.
+     * Unlike `scale`, this does not include runtime-inferred defaults.
+     */
+    scaleSpec?: Scale;
+}

package/src/spec/appSpec.d.ts

@@ -0,0 +1,54 @@
+import { RootConfig } from "@genome-spy/core/spec/root.js";
+import { AppViewSpec } from "./view.js";
+
+export interface RemoteBookmarkConfig {
+    /**
+     * URL to the remote bookmark file.
+     */
+    url: string;
+
+    /**
+     * Should the user be shown a tour of the remote bookmarks when the visualization
+     * is launched? If the `initialBookmark` property is not defined, the tour starts
+     * from the first bookmark.
+     *
+     * __Default value:__ `false`
+     */
+    tour?: boolean;
+
+    /**
+     * Name of the bookmark that should be loaded as the initial state. The bookmark
+     * description dialog is shown only if the `tour` property is set to `true`.
+     */
+    initialBookmark?: string;
+
+    /**
+     * Name of the bookmark that should be loaded when the user ends the tour.
+     * If `null`, the dialog will be closed and the current state is retained.
+     * If undefined, the default state without any performed actions will be loaded.
+     */
+    afterTourBookmark?: string;
+}
+
+export interface BookmarkConfig {
+    /**
+     * Configuration for loading bookmarks from a remote JSON file.
+     */
+    remote?: RemoteBookmarkConfig;
+}
+
+interface AppRootConfig {
+    /**
+     * A unique identifier that is used in storing state bookmarks to browser's
+     * IndexedDB. This is needed to make distinction between visualizations that
+     * are served from the same origin, i.e., the same host and port.
+     */
+    specId?: string;
+
+    /**
+     * Bookmark configuration.
+     */
+    bookmarks?: BookmarkConfig;
+}
+
+export type AppRootSpec = AppViewSpec & RootConfig & AppRootConfig;

package/src/spec/sampleView.d.ts

@@ -0,0 +1,487 @@
+import { Data, InlineData, UrlData } from "@genome-spy/core/spec/data.js";
+import { Align, FontStyle, FontWeight } from "@genome-spy/core/spec/font.js";
+import { Scale } from "@genome-spy/core/spec/scale.js";
+import { ViewSpecBase, ViewBackground } from "@genome-spy/core/spec/view.js";
+import {
+    AppConfigurableVisibilitySpec,
+    AppLayerSpec,
+    AppNestedViewSpec,
+    AppUnitSpec,
+} from "./view.js";
+
+/**
+ * A view specification for a SampleView.
+ */
+export interface SampleSpec extends Omit<ViewSpecBase, "templates"> {
+    /**
+     * Is the SampleView visibility configurable from the GenomeSpy App toolbar.
+     *
+     * __Default value:__ `true`
+     */
+    configurableVisibility?: AppConfigurableVisibilitySpec["configurableVisibility"];
+
+    /**
+     * Sample identity and label configuration.
+     *
+     * If `identity` is omitted, sample identifiers are inferred from the data.
+     */
+    samples: SampleDef;
+
+    /**
+     * Metadata sources and metadata matrix layout.
+     */
+    metadata?: MetadataDef;
+
+    /**
+     * An object defining the view background and outline. The background is
+     * repeated for each group.
+     */
+    view?: ViewBackground;
+
+    /**
+     * The view specification to be repeated for each sample.
+     */
+    spec: AppLayerSpec | AppUnitSpec;
+
+    // Templates inside a SampleSpec may only produce non-sample descendants.
+    // This keeps SampleView as a top-level/sibling concept instead of nestable.
+    templates?: Record<string, AppNestedViewSpec>;
+
+    /**
+     * Keep summary tracks visible while scrolling samples.
+     *
+     * __Default value:__ `true`
+     */
+    stickySummaries?: boolean;
+}
+
+export type SampleAttributeType = "nominal" | "ordinal" | "quantitative";
+
+export type SampleAttributeSemanticType =
+    | "subjectId"
+    | "modelSystemId"
+    | "timeToEvent"
+    | "eventStatus"
+    | "category";
+
+export interface SampleAttributeDef {
+    /**
+     * User-facing description of the metadata attribute.
+     */
+    description?: string;
+
+    /**
+     * The attribute type. One of `"nominal"`, `"ordinal"`, or `"quantitative"`.
+     */
+    type?: SampleAttributeType;
+
+    /**
+     * Domain-specific meaning of the metadata attribute.
+     */
+    semanticType?: SampleAttributeSemanticType;
+
+    /**
+     * Color scale for metadata cells.
+     */
+    scale?: Scale;
+
+    /**
+     * Scale for mapping quantitative values to metadata cell width.
+     */
+    barScale?: Scale;
+
+    /**
+     * Width of the column in pixels.
+     */
+    width?: number;
+
+    /**
+     * Whether the attribute is visible when the view opens.
+     */
+    visible?: boolean;
+
+    /**
+     * Attribute label shown in the metadata header.
+     *
+     * If omitted, the attribute name is used.
+     */
+    title?: string;
+}
+
+export interface SampleIdentityDef {
+    /**
+     * Data source that defines the sample set for the view.
+     *
+     * The source must contain one row per sample. Metadata imports are matched
+     * against these sample ids.
+     */
+    data: Data;
+
+    /**
+     * Field that contains the canonical sample id.
+     *
+     * __Default value:__ `"sample"`
+     */
+    idField?: string;
+
+    /**
+     * Field containing a user-visible sample label.
+     *
+     * If omitted, sample ids are used.
+     */
+    displayNameField?: string;
+}
+
+export interface ColumnIdentifierField {
+    /**
+     * Name of the identifier field shown in UI and diagnostics.
+     *
+     * Example values: `"symbol"`, `"ensembl"`, `"entrez"`.
+     */
+    name: string;
+
+    /**
+     * Backend path to identifier values aligned to matrix columns.
+     *
+     * The array length must equal the number of columns in the matrix.
+     */
+    path: string;
+
+    /**
+     * Marks this identifier as the primary, canonical identifier.
+     */
+    primary?: boolean;
+
+    /**
+     * Enables case-insensitive matching for this identifier field.
+     */
+    caseInsensitive?: boolean;
+
+    /**
+     * Remove version suffixes during matching (for example, ENSG...`.12`).
+     *
+     * Useful for identifiers such as Ensembl ids that may contain version
+     * suffixes in some datasets but not in user queries.
+     */
+    stripVersionSuffix?: boolean;
+}
+
+export interface DataBackendDef {
+    backend: "data";
+
+    /**
+     * Eager tabular metadata source.
+     *
+     * Supports `UrlData` and `InlineData`.
+     */
+    data: UrlData | InlineData;
+
+    /**
+     * Field name in the table that matches sample ids in the view.
+     *
+     * __Default value:__ `"sample"`
+     */
+    sampleIdField?: string;
+}
+
+export interface ZarrMatrixLayoutDef {
+    /**
+     * Path to matrix values, arranged as sample rows by metadata columns.
+     *
+     * __Default value:__ `"X"`
+     */
+    valuesPath?: string;
+
+    /**
+     * Path to matrix row identifiers (sample ids).
+     *
+     * __Default value:__ `"obs_names"`
+     */
+    rowIdsPath?: string;
+
+    /**
+     * Path to matrix column identifiers.
+     *
+     * __Default value:__ `"var_names"`
+     */
+    columnIdsPath?: string;
+}
+
+export interface ZarrBackendDef {
+    backend: "zarr";
+
+    /**
+     * URL to the root of the Zarr store.
+     */
+    url: string;
+
+    /**
+     * Path overrides for the matrix layout.
+     */
+    matrix?: ZarrMatrixLayoutDef;
+
+    /**
+     * Identifier arrays used to resolve user queries to columns.
+     *
+     * If omitted, only primary column ids are used for lookup.
+     */
+    identifiers?: ColumnIdentifierField[];
+}
+
+export interface ParquetBackendDef {
+    backend: "parquet";
+
+    /**
+     * URL to a Parquet metadata source.
+     *
+     * Reserved for future use.
+     */
+    url: string;
+
+    /**
+     * Field containing sample ids.
+     */
+    sampleIdField: string;
+}
+
+export interface ArrowBackendDef {
+    backend: "arrow";
+
+    /**
+     * URL to an Arrow metadata source.
+     *
+     * Reserved for future use.
+     */
+    url: string;
+
+    /**
+     * Field containing sample ids.
+     */
+    sampleIdField: string;
+}
+
+export type MetadataBackendDef =
+    | DataBackendDef
+    | ZarrBackendDef
+    | ParquetBackendDef
+    | ArrowBackendDef;
+
+export interface MetadataSourceDef {
+    /**
+     * Stable source identifier.
+     *
+     * Should remain stable across spec revisions if bookmarks/provenance replay
+     * must keep working.
+     */
+    id?: string;
+
+    /**
+     * User-facing label shown in menus and dialogs.
+     *
+     * If omitted, UI falls back to `id`.
+     */
+    name?: string;
+
+    /**
+     * User-facing description of what this source contains.
+     *
+     * Can be shown in UI and can help automated agents choose the correct
+     * source.
+     */
+    description?: string;
+
+    /**
+     * Startup loading behavior.
+     *
+     * - `false`: do not load at startup
+     * - `"*"`: load all columns allowed by this source
+     * - `string[]`: resolve and load only the listed columns
+     *
+     * If omitted, data backends load all columns and other backends do not
+     * load columns at startup.
+     */
+    initialLoad?: false | "*" | string[];
+
+    /**
+     * Column ids that must never be imported from this source.
+     *
+     * The data backend always excludes its `sampleIdField` automatically, so
+     * this property is only needed for other helper columns such as display
+     * labels.
+     */
+    excludeColumns?: string[];
+
+    /**
+     * Default destination group path for imported attributes.
+     *
+     * Imported column names are placed under this path, which effectively
+     * creates (or reuses) a metadata hierarchy node.
+     *
+     * This value is parsed as a path using `attributeGroupSeparator` when that
+     * separator is defined for the source. Without an explicit separator, the
+     * whole value is treated as one group name (including any `/` characters).
+     *
+     * Users can override this per import in the dialog.
+     */
+    groupPath?: string;
+
+    /**
+     * Separator used by source-side attribute names to express hierarchy.
+     *
+     * Example: if separator is `"."`, column `clinical.OS` is interpreted as
+     * group `clinical` and attribute `OS`.
+     */
+    attributeGroupSeparator?: string;
+
+    /**
+     * Attribute definitions keyed by attribute/column id (and optionally by group path).
+     *
+     * Special key `""` defines source-level defaults for all imported columns.
+     * Path splitting is applied only when `attributeGroupSeparator` is defined.
+     */
+    attributes?: Record<string, SampleAttributeDef>;
+
+    /**
+     * Source backend configuration.
+     */
+    backend: MetadataBackendDef;
+}
+
+export interface MetadataSourceImportDef {
+    /**
+     * URL to a standalone metadata source definition file.
+     *
+     * Imports are shallow: imported files must define exactly one source and
+     * cannot contain nested `import` entries.
+     */
+    url: string;
+}
+
+export type MetadataSourceEntry =
+    | MetadataSourceDef
+    | { import: MetadataSourceImportDef };
+
+export interface MetadataDef {
+    /**
+     * Metadata source definitions used for startup and on-demand imports.
+     *
+     * Source order is significant for startup loading: eager startup imports
+     * are applied in declaration order.
+     */
+    sources?: MetadataSourceEntry[];
+
+    /**
+     * Default width of metadata columns in pixels.
+     *
+     * __Default value:__ `10`
+     */
+    attributeWidth?: number;
+
+    /**
+     * Spacing between metadata columns in pixels.
+     *
+     * __Default value:__ `1`
+     */
+    spacing?: number;
+
+    /**
+     * Font typeface for metadata attribute labels.
+     *
+     * __Default value:__ `"Lato"`
+     */
+    labelFont?: string;
+
+    /**
+     * Font style for metadata attribute labels.
+     *
+     * __Default value:__ `"normal"`
+     */
+    labelFontStyle?: FontStyle;
+
+    /**
+     * Font weight for metadata attribute labels.
+     *
+     * __Default value:__ `"regular"`
+     */
+    labelFontWeight?: FontWeight;
+
+    /**
+     * Font size for metadata attribute labels in pixels.
+     *
+     * __Default value:__ `11`
+     */
+    labelFontSize?: number;
+
+    /**
+     * Angle of metadata attribute labels in degrees.
+     *
+     * __Default value:__ `-90`
+     */
+    labelAngle?: number;
+}
+
+export interface SampleDef {
+    /**
+     * Defines the sample ids and optional display names for the sample view.
+     *
+     * If omitted, sample ids are inferred from the `sample` channel in the view
+     * data.
+     */
+    identity?: SampleIdentityDef;
+
+    /**
+     * Title shown above sample labels.
+     * If omitted, the title defaults to `"Sample"`.
+     * Set to `null` to hide the title.
+     */
+    labelTitle?: string | null;
+
+    /**
+     * Width reserved for sample labels in pixels.
+     *
+     * If omitted, the width is inferred from the sample labels.
+     */
+    labelLength?: number;
+
+    /**
+     * The font typeface. GenomeSpy uses [SDF](https://github.com/Chlumsky/msdfgen)
+     * versions of [Google Fonts](https://fonts.google.com/). Check their
+     * availability at the [A-Frame
+     * Fonts](https://github.com/etiennepinchon/aframe-fonts/tree/master/fonts)
+     * repository. System fonts are **not** supported.
+     *
+     * **Default value:** `"Lato"`
+     */
+    labelFont?: string;
+
+    /**
+     * The font style. Valid values: `"normal"` and `"italic"`.
+     *
+     * **Default value:** `"normal"`
+     */
+    labelFontStyle?: FontStyle;
+
+    /**
+     * The font weight. The following strings and numbers are valid values:
+     * `"thin"` (`100`), `"light"` (`300`), `"regular"` (`400`),
+     * `"normal"` (`400`), `"medium"` (`500`), `"bold"` (`700`),
+     * `"black"` (`900`)
+     *
+     * **Default value:** `"regular"`
+     */
+    labelFontWeight?: FontWeight;
+
+    /**
+     * The font size in pixels.
+     *
+     * **Default value:** `11`
+     */
+    labelFontSize?: number;
+
+    /**
+     * The horizontal alignment of the text. One of `"left"`, `"center"`, or `"right"`.
+     *
+     * **Default value:** `"left"`
+     */
+    labelAlign?: Align;
+}