import { Table } from 'apache-arrow'; import { CosmographConfig } from ".."; import { PointColorStrategyType } from "../../strategies/point-color"; import { PointSizeStrategyType } from "../../strategies/point-size"; import { LinkColorStrategyType } from "../../strategies/link-color"; import { LinkWidthStrategyType } from "../../strategies/link-width"; export declare const RequiredPointsConfigKeys: { readonly Points: "points"; readonly PointId: "pointIdBy"; readonly PointIndex: "pointIndexBy"; }; export declare const BasePointsConfigKeys: { readonly PointColor: "pointColorBy"; readonly PointColorMap: "pointColorByMap"; readonly PointColorFn: "pointColorByFn"; readonly PointColorPalette: "pointColorPalette"; readonly PointColorStrategy: "pointColorStrategy"; readonly PointSize: "pointSizeBy"; readonly PointSizeStrategy: "pointSizeStrategy"; readonly PointSizeRange: "pointSizeRange"; readonly PointSizeFn: "pointSizeByFn"; readonly PointLabel: "pointLabelBy"; readonly PointLabelWeight: "pointLabelWeightBy"; readonly PointX: "pointXBy"; readonly PointY: "pointYBy"; readonly PointCluster: "pointClusterBy"; readonly PointClusterFn: "pointClusterByFn"; readonly PointClusterStrength: "pointClusterStrengthBy"; readonly PointIncludeColumns: "pointIncludeColumns"; readonly PointShape: "pointShapeBy"; readonly PointImageUrl: "pointImageUrlBy"; readonly PointImageSize: "pointImageSize"; readonly PointImageSizeColumn: "pointImageSizeBy"; readonly HidePointShapesForLoadedImages: "hidePointShapesForLoadedImages"; }; export declare const RequiredLinksConfigKeys: { readonly Links: "links"; readonly LinkSource: "linkSourceBy"; readonly LinkSourceIndex: "linkSourceIndexBy"; readonly LinkTarget: "linkTargetBy"; readonly LinkTargetIndex: "linkTargetIndexBy"; }; export declare const BaseLinksConfigKeys: { readonly LinkColor: "linkColorBy"; readonly LinkColorFn: "linkColorByFn"; readonly LinkColorPalette: "linkColorPalette"; readonly LinkColorStrategy: "linkColorStrategy"; readonly LinkWidth: "linkWidthBy"; readonly LinkWidthRange: "linkWidthRange"; readonly LinkWidthFn: "linkWidthByFn"; readonly LinkWidthStrategy: "linkWidthStrategy"; readonly LinkArrow: "linkArrowBy"; readonly LinkArrowFn: "linkArrowByFn"; readonly LinkStrength: "linkStrengthBy"; readonly LinkStrengthFn: "linkStrengthByFn"; readonly LinkStrengthRange: "linkStrengthRange"; readonly LinkIncludeColumns: "linkIncludeColumns"; }; export declare const BaseClustersConfigKeys: { readonly ClusterPositionsMap: "clusterPositionsMap"; }; export interface CosmographPointsConfig { /** Input data for the points. * @see {@link CosmographInputData} */ [RequiredPointsConfigKeys.Points]?: CosmographInputData; /** Unique identifier column for each point. Required for mapping links to points correctly. */ [RequiredPointsConfigKeys.PointId]?: string; /** Numeric index column for each point. Used for efficient lookups and should be a sequential integer starting from 0. */ [RequiredPointsConfigKeys.PointIndex]?: string; /** The column name for the point color. If provided, points will be colored based on the values in this column, which should be either a color `string` or an array of numeric `[r, g, b, a]` values. */ [BasePointsConfigKeys.PointColor]?: string; /** * Specifies the function that will be used to generate the color for each point based on the value in the {@link pointColorBy} column. It takes a point record and its index as input, and should return a color `string` or an array of `[r, g, b, a]` values. * * Overrides the values in {@link pointColorBy} column by processing them (in this case the values in the {@link pointColorBy} column can be of any type, not just colors). * * **Has effect only when {@link pointColorBy} is provided and {@link pointColorStrategy} is `undefined`.** * * @see {@link pointColorStrategy} * @returns The color as a `string` or an array of `[r, g, b, a]` value to be applied to the point. * * @example * // Color points based on a value of the `pointColorBy` column * pointColorByFn: (value: number) => value > 10 ? 'red' : '#00ff00' * * // Color points based on the index of the point * pointColorByFn: (value: number, index: number) => index % 2 === 0 ? 'red' : '#00ff00' * * // Color points using RGBA values (normalized 0–1) * pointColorByFn: (value: unknown) => [1, 0, 0, 1] * */ [BasePointsConfigKeys.PointColorFn]?: ColorAccessorFn | ColorAccessorFn | ColorAccessorFn | ColorAccessorFn; /** * An optional array of color strings that can be used to color the points in the visualization. * If provided, the points will be colored using the colors in this palette, cycling through the array as needed. * * **Used when {@link pointColorStrategy} is set to `'categorical'`, `'continuous'`, or `'degree'`.**` */ [BasePointsConfigKeys.PointColorPalette]?: string[]; /** * An optional mapping of values to colors for the points in the visualization. * The keys in the map should be string and the values can be either color strings or arrays of RGBA values. * * **Used when {@link pointColorStrategy} is set to `'map'`.** * * @default `undefined` * * @example * pointColorByMap: { * 'active': '#ff0000', // string key with hex color * '42': [1, 0, 0, 1], // number key with normalized RGBA array * 'true': 'red' // boolean key with css-valid color * } * */ [BasePointsConfigKeys.PointColorMap]?: Record; /** * Specifies the strategy for coloring points based on data from the {@link pointColorBy} column. * * When `undefined` (default), will automatically use the optimal strategy based on the input configuration and color data type. * Current strategy can be acquired with {@link Cosmograph.activePointColorStrategy} getter. * * See {@link PointColorStrategy} for available strategies and their documentation. */ [BasePointsConfigKeys.PointColorStrategy]?: PointColorStrategyType; /** * The column name that should contain numeric values to be used for the point size and label weight (if labels enabled). * If provided, points will be sized based on the values in this column. **Use `pointSizeRange` to control the size range.** */ [BasePointsConfigKeys.PointSize]?: string; /** * Specifies the strategy for sizing points based on data from the {@link pointSizeBy} column. * * When `undefined` (default), will automatically use the optimal strategy based on the input configuration and size data type. * Current strategy can be acquired with {@link Cosmograph.activePointSizeStrategy} getter. * * See {@link PointSizeStrategy} for available strategies and their documentation. */ [BasePointsConfigKeys.PointSizeStrategy]?: PointSizeStrategyType; /** * Defines the range for automatic point size scaling. Takes [min, max] values in pixels. * * When {@link pointSizeBy} column contains numeric values, they will be automatically remapped * to fit within this range to prevent oversized points. * * **Used when {@link pointSizeStrategy} is set to `'auto'` or `'degree'`.** * * @default `[2, 9]` */ [BasePointsConfigKeys.PointSizeRange]?: [number, number]; /** * Function that generates sizes for points based on values in the {@link pointSizeBy} column. * * Overrides the values in {@link pointSizeBy} column by processing them (values can be of any type, not just numbers). * * **Has effect only when {@link pointSizeBy} is provided and {@link pointSizeStrategy} is `undefined`.** * * @see {@link pointSizeStrategy} * * @example * // Size points based on a value of the `pointSizeBy` column * pointSizeByFn: (value: boolean) => value ? 8 : 4 * * // Size points based on the index * pointSizeByFn: (value: unknown, index: number) => index % 2 === 0 ? 8 : 4 * * // Size points using a calculation * pointSizeByFn: (value: number) => Math.min(value * 2, 10) */ [BasePointsConfigKeys.PointSizeFn]?: SizeAccessorFn | SizeAccessorFn | SizeAccessorFn | SizeAccessorFn; /** * Column name containing cluster assignments for points. Can be string or number. * * @remarks * Cosmograph will automatically generate a mapping of cluster values to their indices that will be available in the {@link Cosmograph.clusterMapping clusterMapping} getter. */ [BasePointsConfigKeys.PointCluster]?: string; /** * Function that generates cluster assignments for points based on values in the {@link pointClusterBy} column. * * Overrides the values in {@link pointClusterBy} column by processing them. * * **Has effect only when {@link pointClusterBy} is provided.** * * @example * pointClusterByFn: (value: string) => value.length */ [BasePointsConfigKeys.PointClusterFn]?: AccessorFn; /** * The `pointClusterStrengthBy` column defines how strongly each point is attracted to its assigned cluster during the simulation. * * The column should contain numeric values where higher values (closer to 1.0) = stronger attraction, point stays closer to its cluster, Lower values (closer to 0.0) = weaker attraction, point can move more freely away from its cluster * * Has effect only when {@link pointClusterBy} is provided. */ [BasePointsConfigKeys.PointClusterStrength]?: string; /** * Column name for point shape. Values: numeric 0–8 (Circle=0, Square=1, Triangle=2, Diamond=3, Pentagon=4, Hexagon=5, Star=6, Cross=7, None=8) * or known string names (e.g. "circle", "square", "none"). Other strings map per distinct value via a global ordinal scale over drawable shapes (excludes none). */ [BasePointsConfigKeys.PointShape]?: string; /** Column name for image URLs (string per row) to be displayed as point images. */ [BasePointsConfigKeys.PointImageUrl]?: string; /** Default size in pixels for point images when pointImageSizeBy is not set. */ [BasePointsConfigKeys.PointImageSize]?: number; /** Optional column name for per-point image display size (numeric); overrides pointImageSize per point when provided. */ [BasePointsConfigKeys.PointImageSizeColumn]?: string; /** * Hide point shapes (circle/square/etc.) for points whose images have been loaded. * Useful when images should visually replace the underlying shape marker. * * @default true */ [BasePointsConfigKeys.HidePointShapesForLoadedImages]?: boolean; /** The column name for the point label. */ [BasePointsConfigKeys.PointLabel]?: string; /** Specify the numeric column that will be used for the point label weight. * Higher weight values make labels more likely to be shown. * * If not provided, the points labels will be sorted by {@link pointSizeBy} if provided or their total links count (degree) otherwise . */ [BasePointsConfigKeys.PointLabelWeight]?: string; /** The column name for the point's x-coordinate. * If provided with `pointYBy`, points will be positioned based on the values from `pointXBy` and `pointYBy` columns. */ [BasePointsConfigKeys.PointX]?: string; /** The column name for the point's y-coordinate. * If provided with `pointXBy`, points will be positioned based on the values from `pointXBy` and `pointYBy` columns. */ [BasePointsConfigKeys.PointY]?: string; /** An array of additional column names to include in the point data. * * These columns will be available on the point objects but not used by Cosmograph directly, can be used as accessors for Cosmograph components. * Useful for storing additional information about the points. * If provided with `*`, all columns will be included. * * @example * pointIncludeColumns: ['*'] // all columns will be included * pointIncludeColumns: ['column1', 'column2'] // only column1 and column2 will be included */ [BasePointsConfigKeys.PointIncludeColumns]?: string[]; } export interface CosmographLinksConfig { /** The input data for the links. * * {@link CosmographInputData} Accepts `File | string | Table | Uint8Array | ArrayBuffer | Record[]` */ [RequiredLinksConfigKeys.Links]?: CosmographInputData; /** The column name for the **source** point of each link. This should match the `pointIdBy` values in the points data. */ [RequiredLinksConfigKeys.LinkSource]?: string; /** The column name for the index of the **source** point of each link. * This is used for efficient lookups and should match the `pointIndexBy` values in the points data. */ [RequiredLinksConfigKeys.LinkSourceIndex]?: string; /** The column name for the **target** point of each link. This should match the `pointIdBy` values in the points data. */ [RequiredLinksConfigKeys.LinkTarget]?: string; /** The column name for the index of the **target** point of each link. * This is used for efficient lookups and should match the `pointIndexBy` values in the points data. */ [RequiredLinksConfigKeys.LinkTargetIndex]?: string; /** The column name for the link color. * * If provided, links will be colored based on the values in this column, which should be either a color `string` or an array of numeric `[r, g, b, a]` values. */ [BaseLinksConfigKeys.LinkColor]?: string; /** Specifies the function that will be used to generate the color for each link based on the value in the {@link linkColorBy} column. * It takes a link record as input and its index, and should return a color `string` or an array of `[r, g, b, a]` values. * * Works only when {@link linkColorBy} is provided. Overrides the values in {@link linkColorBy} column by processing them (in this case the values in the {@link linkColorBy} column can be of any type, not just colors). * * @param {any} value - The value from the `LinkColor` column. * @param {number} index - The index of the link. * @returns {string | [number, number, number, number]} The color as a `string` or an array of `[r, g, b, a]` value to be applied to the link. */ [BaseLinksConfigKeys.LinkColorFn]?: ColorAccessorFn | ColorAccessorFn | ColorAccessorFn | ColorAccessorFn; /** * An optional array of color strings that can be used to color the links in the visualization. * If provided, the links will be colored using the colors in this palette, cycling through the array as needed. * * **Used when {@link linkColorStrategy} is set to `'categorical'`, `'count'`, `'sum'`, or `'average'`**` */ [BaseLinksConfigKeys.LinkColorPalette]?: string[]; /** * Specifies the strategy for coloring links based on data from the {@link linkColorBy} column. * * When `undefined` (default), will automatically use the optimal strategy based on the input configuration and color data type. * Current strategy can be acquired with {@link Cosmograph.activeLinkColorStrategy} getter. * * See {@link LinkColorStrategy} for available strategies and their documentation. */ [BaseLinksConfigKeys.LinkColorStrategy]?: LinkColorStrategyType; /** The column name for the link width. * * If provided, links will have their widths set based on the values in this column, which should be numeric values. */ [BaseLinksConfigKeys.LinkWidth]?: string; /** Specifies the function that will be used to generate the width for each link based on the value in the {@link linkWidthBy} column. * It takes a link record as input and its index, and should return a numeric value. * * Works only when {@link linkWidthBy} is provided. Overrides the values in the {@link linkWidthBy} column by processing them (in this case the values in the {@link linkWidthBy} column can be of any type, not just numbers). * * @param {any} value - The value from the {@link linkWidthBy} column. * @param {number} index - The index of the link. * @returns {number} The numeric width value to be applied to the link. */ [BaseLinksConfigKeys.LinkWidthFn]?: SizeAccessorFn | SizeAccessorFn | SizeAccessorFn | SizeAccessorFn; /** * Specifies the strategy for sizing links based on data from the {@link linkWidthBy} column. * * When `undefined` (default), will automatically use the optimal strategy based on the input configuration and width data type. * Current strategy can be acquired with {@link Cosmograph.activeLinkWidthStrategy} getter. * * See {@link LinkWidthStrategy} for available strategies and their documentation. */ [BaseLinksConfigKeys.LinkWidthStrategy]?: LinkWidthStrategyType; /** * Defines the range for automatic link width scaling. Takes [min, max] values in pixels. * * When {@link linkWidthBy} column contains numeric values, they will be automatically remapped to fit within this range to prevent oversized links if no {@link linkWidthByFn} provided. * * Note: Only works when {@link linkWidthBy} column is provided and contains numeric values and when {@link linkWidthByFn} is not set. * * @default [1, 9] */ [BaseLinksConfigKeys.LinkWidthRange]?: [number, number]; /** The column name that determines whether a link should have an arrow. * If provided, links will have arrows based on the `boolean` values in this column. */ [BaseLinksConfigKeys.LinkArrow]?: string; /** Specifies the function that determines if a link should have an arrow based on the value in the {@link linkArrowBy} column. * It takes a link record as input and its index, and should return a boolean value. * * Works only when {@link linkArrowBy} is provided. Overrides the values in the {@link linkArrowBy} column by processing them (in this case the values in the {@link linkArrowBy} column can be of any type, not just booleans). * * @param {any} value - The value from the {@link linkArrowBy} column. * @param {number} index - The index of the link. * @returns {boolean} A boolean indicating whether the link should have an arrow. */ [BaseLinksConfigKeys.LinkArrowFn]?: BooleanAccessorFn | BooleanAccessorFn | BooleanAccessorFn; /** The column name for the link strength. * If provided, links will have their strengths set based on the values in this column, which should be numeric values. * Link strength affects the force simulation. */ [BaseLinksConfigKeys.LinkStrength]?: string; /** Specifies the function that will be used to generate the strength for each link based on the value in the {@link linkStrengthBy} column. * It takes a link record as input and its index, and should return a numeric value. * * Works only when {@link linkStrengthBy} is provided. Overrides the values in the {@link linkStrengthBy} column by processing them (in this case the values in the {@link linkStrengthBy} column can be of any type, not just numbers). * * @param {any} value - The value from the `LinkStrength` column. * @param {number} index - The index of the link. * @returns {number} The numeric strength value to be applied to the link. */ [BaseLinksConfigKeys.LinkStrengthFn]?: SizeAccessorFn | SizeAccessorFn | SizeAccessorFn | SizeAccessorFn; /** Defines the range for automatic link strength scaling. Takes [min, max] values in the range [0, 1]. * * This setting can be used to control the strength of the links during the simulation. * * Note: Only works when {@link linkStrengthBy} column is provided and contains numeric values and when {@link linkStrengthByFn} is not set. Has effect only during the active simulation. * @default [0.2, 1.0] */ [BaseLinksConfigKeys.LinkStrengthRange]?: [number, number]; /** An array of additional column names to include in the link data. * * These columns will be available on the link objects but not used by Cosmograph directly, can be used as accessors for Cosmograph components. Useful for storing additional information about the links. * If provided with `*`, all columns will be included. * * @example * linkIncludeColumns: ['*'] // all columns will be included * linkIncludeColumns: ['column1', 'column2'] // only column1 and column2 will be included */ [BaseLinksConfigKeys.LinkIncludeColumns]?: string[]; } export interface CosmographClustersConfig { /** * Mapping of cluster keys to [x, y] coordinate positions. * Keys should match values from the {@link CosmographConfig.pointClusterBy pointClusterBy} column. * Missing cluster keys will be automatically positioned using the centermass. * Won't take effect if point positions are provided by {@link CosmographConfig.pointXBy pointXBy} or {@link CosmographConfig.pointYBy pointYBy}. * * @example * // Object mapping cluster keys to coordinates: * clusterPositionsMap: { * 'Rock': [10, 20], // Cluster 'Rock' at position (10, 20) * 'Rap': [30, 40], // Cluster 'Rap' at position (30, 40) * } * * @remarks * If {@link CosmographConfig.pointClusterByFn pointClusterByFn} is provided, use keys as values of {@link CosmographConfig.pointClusterBy pointClusterBy} after applying {@link CosmographConfig.pointClusterByFn pointClusterByFn }. */ [BaseClustersConfigKeys.ClusterPositionsMap]?: Record; } export declare const pointsConfigKeys: Array; export declare const linksConfigKeys: Array; export declare const clustersConfigKeys: Array; export declare const requiredPointsConfigKeys: Array; export declare const requiredLinksConfigKeys: Array; export declare const requiredProps: (keyof CosmographConfig)[]; export declare const unrequiredLinkProps: (keyof CosmographConfig)[]; export declare const unrequiredPointProps: (keyof CosmographConfig)[]; export declare const unrequiredProps: (keyof CosmographConfig)[]; /** * Represents the input data for Cosmograph points or links. * This can be an array of objects or a more complex data structure * containing information about each point or link to be rendered. Accepts `File`, `string`, `Table` (Apache Arrow), `Uint8Array` (Apache Arrow), `ArrayBuffer` (Apache Arrow), `Record[]` * * `string` will be treated as table name in external DuckDB-Wasm instance when `duckDbConnection` is provided to the Cosmograph instance. */ export type CosmographInputData = File | string | Table | Uint8Array | ArrayBuffer | Record[]; /** * Represents the data operated by the Cosmograph. * * The data is stored in the Apache Arrow `Table` format, which is a fast and efficient way to store and process large amounts of data. * * For more information on the `Table` format, see the [Apache Arrow documentation](https://arrow.apache.org/docs/format/Columnar.html). */ export type CosmographData = Table; export interface CosmographDataConfig extends CosmographPointsConfig, CosmographLinksConfig, CosmographClustersConfig { } /** * Base accessor with generic input/output types * @template T - Input type * @template O - Output type * @inline */ export type AccessorFn = (value: T, index?: number) => O; export type ColorAccessorFn = AccessorFn; export type SizeAccessorFn = AccessorFn; export type BooleanAccessorFn = AccessorFn; export type CosmographPointInput = { id: string; [key: string]: unknown; }; export type CosmographLinkInput = { source: string; target: string; [key: string]: unknown; };