From 9dd52d84606174bdb171c06268e92d3c7d6b8e10 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Philippe=20Rivi=C3=A8re?= Date: Sun, 26 Mar 2023 16:45:24 +0200 Subject: [PATCH 1/3] document density --- src/marks/density.d.ts | 43 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 43 insertions(+) diff --git a/src/marks/density.d.ts b/src/marks/density.d.ts index abac1a9b29..d18b31616f 100644 --- a/src/marks/density.d.ts +++ b/src/marks/density.d.ts @@ -1,15 +1,58 @@ import type {ChannelValue, ChannelValueSpec} from "../channel.js"; import type {Data, MarkOptions, RenderableMark} from "../mark.js"; +/** Options for the density mark. */ export interface DensityOptions extends MarkOptions { + /** The horizontal point position, typically bound to the *x* scale. */ x?: ChannelValueSpec; + /** The vertical point position, typically bound to the *y* scale. */ y?: ChannelValueSpec; + /** + * Group points into series and create independent contours for each series. + */ z?: ChannelValue; + /** + * The **weight** channel, which defaults to 1, specifies the weight of each + * point. Non-positive weights are allowed, making associated points + * repulsive. + */ weight?: ChannelValue; + /** + * The **bandwidth** option, which defaults to 20, specifies the standard + * deviation of the Gaussian kernel used for estimation in pixels. + */ bandwidth?: number; + /** + * The **thresholds** option, which defaults to 20, specifies one more than + * the number of contours that will be computed at uniformly-spaced intervals + * between 0 (exclusive) and the maximum density (exclusive). The + * **thresholds** option may also be specified as an array or iterable of + * explicit density values. + */ thresholds?: number | Iterable; } +/** + * Draws contours representing the estimated density of the two-dimensional + * points given by the **x** and **y** channels, and possibly weighted by the + * **weight** channel. If either of the **x** or **y** channels are not + * specified, the corresponding position is controlled by the **frameAnchor** + * option. + * + * The **thresholds** option, which defaults to 20, specifies one more than the + * number of contours that will be computed at uniformly-spaced intervals + * between 0 (exclusive) and the maximum density (exclusive). The **thresholds** + * option may also be specified as an array or iterable of explicit density + * values. The **bandwidth** option, which defaults to 20, specifies the + * standard deviation of the Gaussian kernel used for estimation in pixels. + * + * If a **z**, **stroke** or **fill** channel is specified, the input points are + * grouped by series, and separate sets of contours are generated for each + * series. If the **stroke** or **fill** is specified as *density*, a color + * channel is constructed with values representing the density threshold value + * of each contour. + */ export function density(data?: Data, options?: DensityOptions): Density; +/** The density mark. */ export class Density extends RenderableMark {} From 01ae4bccbb94284f5fecc974d77b72115cb09bfe Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Philippe=20Rivi=C3=A8re?= Date: Wed, 29 Mar 2023 18:40:00 +0200 Subject: [PATCH 2/3] lines --- src/marks/density.d.ts | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/src/marks/density.d.ts b/src/marks/density.d.ts index d18b31616f..d30456d40d 100644 --- a/src/marks/density.d.ts +++ b/src/marks/density.d.ts @@ -5,23 +5,28 @@ import type {Data, MarkOptions, RenderableMark} from "../mark.js"; export interface DensityOptions extends MarkOptions { /** The horizontal point position, typically bound to the *x* scale. */ x?: ChannelValueSpec; + /** The vertical point position, typically bound to the *y* scale. */ y?: ChannelValueSpec; + /** * Group points into series and create independent contours for each series. */ z?: ChannelValue; + /** * The **weight** channel, which defaults to 1, specifies the weight of each * point. Non-positive weights are allowed, making associated points * repulsive. */ weight?: ChannelValue; + /** * The **bandwidth** option, which defaults to 20, specifies the standard * deviation of the Gaussian kernel used for estimation in pixels. */ bandwidth?: number; + /** * The **thresholds** option, which defaults to 20, specifies one more than * the number of contours that will be computed at uniformly-spaced intervals From 550662f69b3c836b750db39fd151487cabd7c832 Mon Sep 17 00:00:00 2001 From: Mike Bostock Date: Thu, 30 Mar 2023 17:29:44 -0700 Subject: [PATCH 3/3] edits --- src/marks/area.d.ts | 6 ++--- src/marks/delaunay.d.ts | 4 ++-- src/marks/density.d.ts | 53 +++++++++++++++++------------------------ src/marks/line.d.ts | 6 ++--- 4 files changed, 30 insertions(+), 39 deletions(-) diff --git a/src/marks/area.d.ts b/src/marks/area.d.ts index 28ec52f4fb..797456a052 100644 --- a/src/marks/area.d.ts +++ b/src/marks/area.d.ts @@ -37,9 +37,9 @@ export interface AreaOptions extends MarkOptions, StackOptions, CurveOptions { y2?: ChannelValueSpec; /** - * The optional ordinal **z** channel, for grouping data into (possibly - * stacked) series to be drawn as separate areas; defaults to **fill** if a - * channel, or **stroke** if a channel. + * An optional ordinal channel for grouping data into (possibly stacked) + * series to be drawn as separate areas; defaults to **fill** if a channel, or + * **stroke** if a channel. */ z?: ChannelValue; } diff --git a/src/marks/delaunay.d.ts b/src/marks/delaunay.d.ts index f70e392983..82743081d9 100644 --- a/src/marks/delaunay.d.ts +++ b/src/marks/delaunay.d.ts @@ -5,9 +5,9 @@ import type {MarkerOptions} from "../marker.js"; /** Options for the Delaunay marks. */ export interface DelaunayOptions extends MarkOptions, MarkerOptions, CurveOptions { - /** A channel for the horizontal position, typically bound to the *x* scale. */ + /** The horizontal position channel, typically bound to the *x* scale. */ x?: ChannelValueSpec; - /** A channel for the vertical position, typically bound to the *y* scale. */ + /** The vertical position channel, typically bound to the *y* scale. */ y?: ChannelValueSpec; /** An optional ordinal channel for grouping to produce multiple (possibly overlapping) triangulations. */ z?: ChannelValue; diff --git a/src/marks/density.d.ts b/src/marks/density.d.ts index d30456d40d..f964a915ee 100644 --- a/src/marks/density.d.ts +++ b/src/marks/density.d.ts @@ -3,59 +3,50 @@ import type {Data, MarkOptions, RenderableMark} from "../mark.js"; /** Options for the density mark. */ export interface DensityOptions extends MarkOptions { - /** The horizontal point position, typically bound to the *x* scale. */ + /** The horizontal position channel, typically bound to the *x* scale. */ x?: ChannelValueSpec; - - /** The vertical point position, typically bound to the *y* scale. */ + /** The vertical position channel, typically bound to the *y* scale. */ y?: ChannelValueSpec; /** - * Group points into series and create independent contours for each series. + * An optional ordinal channel for grouping, producing independent contours + * for each group. If not specified, it defaults to **fill** if a channel, or + * **stroke** if a channel. */ z?: ChannelValue; /** - * The **weight** channel, which defaults to 1, specifies the weight of each - * point. Non-positive weights are allowed, making associated points - * repulsive. + * An optional weight channel specifying the relative contribution of each + * point. If not specified, all points have a constant weight of 1. + * Non-positive weights are allowed, making associated points repulsive. */ weight?: ChannelValue; /** - * The **bandwidth** option, which defaults to 20, specifies the standard - * deviation of the Gaussian kernel used for estimation in pixels. + * The bandwidth, a number in pixels which defaults to 20, specifies the + * standard deviation of the Gaussian kernel used for density estimation. A + * larger value will produce smoother contours. */ bandwidth?: number; /** - * The **thresholds** option, which defaults to 20, specifies one more than - * the number of contours that will be computed at uniformly-spaced intervals - * between 0 (exclusive) and the maximum density (exclusive). The - * **thresholds** option may also be specified as an array or iterable of - * explicit density values. + * How many contours to produce, and at what density; either a number, by + * default 20, specifying one more than the number of contours that will be + * computed at uniformly-spaced intervals between 0 (exclusive) and the + * maximum density (exclusive); or, an iterable of explicit density values. */ thresholds?: number | Iterable; } /** - * Draws contours representing the estimated density of the two-dimensional - * points given by the **x** and **y** channels, and possibly weighted by the - * **weight** channel. If either of the **x** or **y** channels are not - * specified, the corresponding position is controlled by the **frameAnchor** - * option. - * - * The **thresholds** option, which defaults to 20, specifies one more than the - * number of contours that will be computed at uniformly-spaced intervals - * between 0 (exclusive) and the maximum density (exclusive). The **thresholds** - * option may also be specified as an array or iterable of explicit density - * values. The **bandwidth** option, which defaults to 20, specifies the - * standard deviation of the Gaussian kernel used for estimation in pixels. + * Returns a mark that draws contours representing the estimated density of the + * two-dimensional points given by **x** and **y**, and possibly weighted by + * **weight**. If either **x** or **y** is not specified, it defaults to the + * respective middle of the plot’s frame. * - * If a **z**, **stroke** or **fill** channel is specified, the input points are - * grouped by series, and separate sets of contours are generated for each - * series. If the **stroke** or **fill** is specified as *density*, a color - * channel is constructed with values representing the density threshold value - * of each contour. + * If the **stroke** or **fill** is specified as *density*, a color channel is + * constructed with values representing the density threshold value of each + * contour. */ export function density(data?: Data, options?: DensityOptions): Density; diff --git a/src/marks/line.d.ts b/src/marks/line.d.ts index c05235418f..d17e06a7b3 100644 --- a/src/marks/line.d.ts +++ b/src/marks/line.d.ts @@ -17,9 +17,9 @@ export interface LineOptions extends MarkOptions, MarkerOptions, CurveAutoOption y?: ChannelValueSpec; /** - * The optional ordinal **z** channel, for grouping data into (possibly - * stacked) series to be drawn as separate lines. If not specified, it - * defaults to **fill** if a channel, or **stroke** if a channel. + * An optional ordinal channel for grouping data into (possibly stacked) + * series to be drawn as separate lines. If not specified, it defaults to + * **fill** if a channel, or **stroke** if a channel. */ z?: ChannelValue; }