JavaScript & React libraryAPI

Interface: CosmographDataConfig

Extends

Extended by

Properties

points?

optional points: CosmographInputData

Input data for the points.

See

CosmographInputData

Inherited from

CosmographPointsConfig.points

pointIdBy?

optional pointIdBy: string

Unique identifier column for each point. Required for mapping links to points correctly.

Inherited from

CosmographPointsConfig.pointIdBy

pointIndexBy?

optional pointIndexBy: string

Numeric index column for each point. Used for efficient lookups and should be a sequential integer starting from 0.

Inherited from

CosmographPointsConfig.pointIndexBy

pointColorBy?

optional pointColorBy: 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.

Inherited from

CosmographPointsConfig.pointColorBy

pointColorByFn?

optional pointColorByFn: ColorAccessorFn<number> | ColorAccessorFn<string> | ColorAccessorFn<boolean> | ColorAccessorFn<unknown>

Specifies the function that will be used to generate the color for each point based on the value in the pointColorBy column. It takes a point record as input and its index, and should return a color string or an array of [r, g, b, a] values.

Overrides the values in pointColorBy column by processing them (in this case the values in the pointColorBy column can be of any type, not just colors).

Has effect only when pointColorBy is provided and pointColorStrategy is undefined.

See

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
pointColorByFn: (value: unknown) => [255, 0, 0, 1]

Inherited from

CosmographPointsConfig.pointColorByFn

pointColorPalette?

optional pointColorPalette: string[]

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 pointColorStrategy is set to 'palette', 'interpolatePalette', or 'degree'.`

Inherited from

CosmographPointsConfig.pointColorPalette

pointColorByMap?

optional pointColorByMap: Record<string, string | [number, number, number, number]>

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 pointColorStrategy is set to 'map'.

Default

undefined

Example

pointColorByMap: {
  'active': '#ff0000', // string key with hex color
  '42': [255, 0, 0, 1], // number key with RGBA array
  'true': 'red'  // boolean key with css-valid color
}

Inherited from

CosmographPointsConfig.pointColorByMap

pointColorStrategy?

optional pointColorStrategy: string

Specifies the strategy for coloring points based on data from the pointColorBy column. Available strategies:

undefined (default):

Will automatically use the optimal strategy based on the input configuration and color data type. Current strategy can be acquired with Cosmograph.activePointColorStrategy getter.

'palette'

Uses colors from pointColorPalette without interpolation.

  • For numeric data: Creates equal-width buckets mapped to pointColorPalette colors
  • For categorical data: Assigns colors from pointColorPalette in order, cycling when unique values exceed palette length

'interpolatePalette'

Interpolates colors from pointColorPalette.

  • For numeric data: Creates continuous color scale between pointColorPalette colors
  • For categorical data: Creates evenly-spaced color scale by interpolating between pointColorPalette colors to match the number of unique values in pointColorBy so every value is a unique color

'map'

Uses color mapping from pointColorByMap to values in pointColorBy.

  • Applies exact color from pointColorByMap for matching values
  • Falls back to pointColor when value is not found in map or invalid

'degree'

Colors points based on their degree (number of connections) using interpolated pointColorPalette with quantile-based boundaries.

  • Maps point degrees to continuous color scale between pointColorPalette colors
  • Has effect only if links provided

'direct'

Directly uses pointColorBy column values as colors.

Inherited from

CosmographPointsConfig.pointColorStrategy

pointSizeBy?

optional pointSizeBy: string

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.

Inherited from

CosmographPointsConfig.pointSizeBy

pointSizeStrategy?

optional pointSizeStrategy: string

Specifies the strategy for sizing points based on data from the pointSizeBy column. Available strategies:

undefined (default):

Will automatically use the optimal strategy based on the input configuration and size data type. Current strategy can be acquired with Cosmograph.activePointSizeStrategy getter.

'auto'

Automatically sizes points using symmetric log scaling with quantile-based data boundaries based on the pointSizeBy data. Uses pointSizeRange to determine the min/max size range.

  • Has effect only if pointSizeBy provided and contains numeric data.

direct:

Directly uses pointSizeBy column values as point sizes.

'degree'

Sizes points based on their degree (number of connections) with quantile-based boundaries and the min/max from pointSizeRange.

  • Has effect only if links provided

Inherited from

CosmographPointsConfig.pointSizeStrategy

pointSizeRange?

optional pointSizeRange: [number, number]

Defines the range for automatic point size scaling. Takes [min, max] values in pixels.

When pointSizeBy column contains numeric values, they will be automatically remapped to fit within this range to prevent oversized points.

Used when pointSizeStrategy is set to 'auto' or 'degree'.

Default

[2, 9]

Inherited from

CosmographPointsConfig.pointSizeRange

pointSizeByFn?

optional pointSizeByFn: SizeAccessorFn<number> | SizeAccessorFn<string> | SizeAccessorFn<boolean> | SizeAccessorFn<unknown>

Function that generates sizes for points based on values in the pointSizeBy column.

Overrides the values in pointSizeBy column by processing them (values can be of any type, not just numbers).

Has effect only when pointSizeBy is provided and pointSizeStrategy is undefined.

See

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)

Inherited from

CosmographPointsConfig.pointSizeByFn

pointClusterBy?

optional pointClusterBy: string

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 clusterMapping getter.

Inherited from

CosmographPointsConfig.pointClusterBy

pointClusterByFn()?

optional pointClusterByFn: (value, index?) => unknown

Function that generates cluster assignments for points based on values in the pointClusterBy column.

Overrides the values in pointClusterBy column by processing them.

Has effect only when pointClusterBy is provided.

Parameters

ParameterType
valueany
index?number

Returns

unknown

Example

pointClusterByFn: (value: string) => value.length

Inherited from

CosmographPointsConfig.pointClusterByFn

pointClusterStrengthBy?

optional pointClusterStrengthBy: string

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 pointClusterBy is provided.

Inherited from

CosmographPointsConfig.pointClusterStrengthBy

pointLabelBy?

optional pointLabelBy: string

The column name for the point label.

Inherited from

CosmographPointsConfig.pointLabelBy

pointLabelWeightBy?

optional pointLabelWeightBy: 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 pointSizeBy if provided or their total links count (degree) otherwise .

Inherited from

CosmographPointsConfig.pointLabelWeightBy

pointXBy?

optional pointXBy: 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.

Inherited from

CosmographPointsConfig.pointXBy

pointYBy?

optional pointYBy: 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.

Inherited from

CosmographPointsConfig.pointYBy

pointIncludeColumns?

optional pointIncludeColumns: 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 comopnents. Useful for storing additional information about the points.

Inherited from

CosmographPointsConfig.pointIncludeColumns

links?

optional links: CosmographInputData

The input data for the links.

CosmographInputData Accepts File | string | Table | Uint8Array | ArrayBuffer | Record<string, unknown>[]

Inherited from

CosmographLinksConfig.links

linkSourceBy?

optional linkSourceBy: string

The column name for the source point of each link. This should match the pointIdBy values in the points data.

Inherited from

CosmographLinksConfig.linkSourceBy

linkSourceIndexBy?

optional linkSourceIndexBy: 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.

Inherited from

CosmographLinksConfig.linkSourceIndexBy

linkTargetBy?

optional linkTargetBy: string

The column name for the target point of each link. This should match the pointIdBy values in the points data.

Inherited from

CosmographLinksConfig.linkTargetBy

linkTargetIndexBy?

optional linkTargetIndexBy: 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.

Inherited from

CosmographLinksConfig.linkTargetIndexBy

linkColorBy?

optional linkColorBy: 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.

Inherited from

CosmographLinksConfig.linkColorBy

linkColorByFn?

optional linkColorByFn: ColorAccessorFn<number> | ColorAccessorFn<string> | ColorAccessorFn<boolean> | ColorAccessorFn<unknown>

Specifies the function that will be used to generate the color for each link based on the value in the 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 linkColorBy is provided. Overrides the values in linkColorBy column by processing them (in this case the values in the linkColorBy column can be of any type, not just colors).

Param

The value from the LinkColor column.

Param

The index of the link.

Returns

The color as a string or an array of [r, g, b, a] value to be applied to the link.

Inherited from

CosmographLinksConfig.linkColorByFn

linkWidthBy?

optional linkWidthBy: string

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.

Inherited from

CosmographLinksConfig.linkWidthBy

linkWidthRange?

optional linkWidthRange: [number, number]

Defines the range for automatic link width scaling. Takes [min, max] values in pixels.

When linkWidthBy column contains numeric values, they will be automatically remapped to fit within this range to prevent oversized links if no linkWidthByFn provided.

Note: Only works when linkWidthBy column is provided and contains numeric values and when linkWidthByFn is not set.

Default

[1, 9]

Inherited from

CosmographLinksConfig.linkWidthRange

linkWidthByFn?

optional linkWidthByFn: SizeAccessorFn<number> | SizeAccessorFn<string> | SizeAccessorFn<boolean> | SizeAccessorFn<unknown>

Specifies the function that will be used to generate the width for each link based on the value in the linkWidthBy column. It takes a link record as input and its index, and should return a numeric value.

Works only when linkWidthBy is provided. Overrides the values in the linkWidthBy column by processing them (in this case the values in the linkWidthBy column can be of any type, not just numbers).

Param

The value from the LinkWidth column.

Param

The index of the link.

Returns

The numeric width value to be applied to the link.

Inherited from

CosmographLinksConfig.linkWidthByFn

linkArrowBy?

optional linkArrowBy: string

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.

Inherited from

CosmographLinksConfig.linkArrowBy

linkArrowByFn?

optional linkArrowByFn: BooleanAccessorFn<string> | BooleanAccessorFn<number> | BooleanAccessorFn<unknown>

Specifies the function that determines if a link should have an arrow based on the value in the linkArrowBy column. It takes a link record as input and its index, and should return a boolean value.

Works only when linkArrowBy is provided. Overrides the values in the linkArrowBy column by processing them (in this case the values in the linkArrowBy column can be of any type, not just booleans).

Param

The value from the LinkArrow column.

Param

The index of the link.

Returns

A boolean indicating whether the link should have an arrow.

Inherited from

CosmographLinksConfig.linkArrowByFn

linkStrengthBy?

optional linkStrengthBy: string

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.

Inherited from

CosmographLinksConfig.linkStrengthBy

linkStrengthByFn?

optional linkStrengthByFn: SizeAccessorFn<number> | SizeAccessorFn<string> | SizeAccessorFn<boolean> | SizeAccessorFn<unknown>

Specifies the function that will be used to generate the strength for each link based on the value in the linkStrengthBy column. It takes a link record as input and its index, and should return a numeric value.

Works only when linkStrengthBy is provided. Overrides the values in the linkStrengthBy column by processing them (in this case the values in the linkStrengthBy column can be of any type, not just numbers).

Param

The value from the LinkStrength column.

Param

The index of the link.

Returns

The numeric strength value to be applied to the link.

Inherited from

CosmographLinksConfig.linkStrengthByFn

linkStrengthRange?

optional linkStrengthRange: [number, number]

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 linkStrength column is provided and contains numeric values and when linkStrengthFn is not set. Has effect only during the active simulation.

Default

[0.2, 1.0]

Inherited from

CosmographLinksConfig.linkStrengthRange

linkIncludeColumns?

optional linkIncludeColumns: string[]

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.

Inherited from

CosmographLinksConfig.linkIncludeColumns

clusterPositionsMap?

optional clusterPositionsMap: Record<string, [number, number]>

Mapping of cluster keys to [x, y] coordinate positions. Keys should match values from the pointClusterBy column. Missing cluster keys will be automatically positioned using the centermass. Won’t take effect if point positions are provided by pointXBy or 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 pointClusterByFn is provided, use keys as values of pointClusterBy after applying pointClusterByFn.

Inherited from

CosmographClustersConfig.clusterPositionsMap

Upgrade from v1CosmographBars