stream-charts 1.0.0 → 1.1.0

package/src/app/charts/tooltips/ScatterPlotTooltipContent.tsx

@@ -0,0 +1,319 @@
+import {Series} from "../plots/plot";
+import {Dimensions, Margin} from "../styling/margins";
+import {boundingPoints, defaultTooltipStyle, TooltipDimensions, TooltipStyle, tooltipX, tooltipY} from "./tooltipUtils";
+import * as d3 from "d3";
+import {formatTime, formatTimeChange, formatValue, formatValueChange} from "../utils";
+import {TextSelection} from "../d3types";
+import {useEffect, useMemo} from "react";
+import {NoTooltipMetadata, useChart} from "../hooks/useChart";
+import {usePlotDimensions} from "../hooks/usePlotDimensions";
+import {ContinuousNumericAxis, SeriesLineStyle} from "../axes/axes";
+import {Datum, emptyDatum} from "../series/timeSeries";
+import {TooltipData} from "../hooks/useTooltip";
+import {ContinuousAxisRange} from "../axes/ContinuousAxisRange";
+
+/**
+# Want to write your own tooltip-content component?
+
+Here's how to write your own tooltip-content component.
+
+To create your own tooltip content `<MyTooltipContent/>` you must do the following:
+1. Create a react component for your tooltip content (see for example, {@link ScatterPlotTooltipContent}
+   as a reference.
+2. Use the {@link useChart} hook to get the {@link registerTooltipContentProvider} registration function.
+3. When your tooltip content component (`<MyTooltipContent/>`) mounts, use the {@link registerTooltipContentProvider}
+   function to register your tooltip content provider.
+4. When the chart dimensions, margin, container, etc, change, register your tooltip content provider
+   again (you can register as many times as you like because it only uses the last content provider
+   registered).
+
+That's it! A bit more details below.
+
+The {@link registerTooltipContentProvider} function from the {@link useChart} hook allows you to register
+one tooltip content provider. A second call to this function will cause the {@link useChart} hook to drop
+the first one in favor of the second one.
+
+The {@link registerTooltipContentProvider} function from the {@link useChart} hook accepts a higher-order
+function that allowing a closure on content/chart-specific data. Specifically, you must hand the
+{@link registerTooltipContentProvider} a function of the form:
+
+`(seriesName: string, time: number, series: TimeSeries, mouseCoords: [x: number, y: number]) => TooltipDimensions`
+
+Your function to add that actual content will be what this function calls whenever d3 fires a mouse-over
+event on one you the time-series in the chart.
+
+The code snippet below is from the `useEffect` call in the {@link ScatterPlotTooltipContent}.
+Note that the first four arguments to the {@link addTooltipContent} function are those provided by the {@link useChart} hook
+when a d3 mouse-over event occurs on one of your series. The additional six arguments are from the closure formed
+on the variables in your component. The `chartId`, `container`, `margin`, and `plotDimensions` are from the
+ {@link useChart} hook called by the {@link ScatterPlotTooltipContent} component. The last two
+arguments, `defaultTooltipStyle` and `options` are specific to the {@link ScatterPlotTooltipContent}.
+For example, the `options` property is set by the caller of the {@link ScatterPlotTooltipContent}
+component.
+
+```ts
+// register the tooltip content provider function with the chart hook (useChart) so that
+// it is visible to all children of the Chart (i.e. the <Tooltip>).
+registerTooltipContentProvider(
+    (seriesName: string, time: number, series: TimeSeries, mouseCoords: [x: number, y: number]) =>
+        addTooltipContent(
+            seriesName, time, series, mouseCoords,
+            chartId, container, margin, plotDimensions,
+            defaultTooltipStyle, options
+        )
+)
+```
+
+This pattern allows you to supplement that `useChart` mouse-over callback with information specific to you component.
+
+ */
+
+/**
+ * Options for displaying the tooltip content. These options are specific to this
+ * particular implementation of a tooltip content. The options effect are applied
+ * as shown below.
+ * ```
+ * series name
+ *            headers.before       headers.after         headers.delta
+ * labels.x   formatters.x.value   formatters.x.value    formatters.x.change
+ * labels.y   formatters.y.value   formatters.y.value    formatters.y.change
+ * ```
+ */
+interface TooltipOptions {
+    labels: { x: string, y: string }
+    headers: {before: string, after: string, delta: string}
+    formatters: {
+        x: { value: (value: number) => string, change: (value1: number, value2: number) => string },
+        y: { value: (value: number) => string, change: (value1: number, value2: number) => string },
+    }
+}
+
+/**
+ * Properties for rendering the tooltip content. The properties are applied as
+ * shown below.
+ * ```
+ * series name
+ *          beforeHeader      afterHeader        deltaHeader
+ * xLabel   xValueFormatter   xValueFormatter    xChangeFormatter
+ * yLabel   yValueFormatter   yValueFormatter    yChangeFormatter
+ * ```
+ */
+interface Props {
+    // label for the x-values (x-value row header)
+    xLabel: string
+    yLabel: string
+    beforeHeader?: string
+    afterHeader?: string
+    deltaHeader?: string
+    xValueFormatter?: (value: number) => string
+    yValueFormatter?: (value: number) => string
+    xChangeFormatter?: (value1: number, value2: number) => string,
+    yChangeFormatter?: (value1: number, value2: number) => string,
+    style?: Partial<TooltipStyle>
+}
+
+/**
+ * Adds tooltip content as a table. The columns of the table are the "label", the value before
+ * the mouse cursor, then value after the mouse cursor, and the difference between the two values.
+ * The rows of the table are x-values for the first row, and the y-values for the second row.
+ * The table has the following form.
+ * ```
+ * series name
+ *            before     after         ∆
+ * x-label     x_tb      x_ta       x_ta - x_tb
+ * y-label     y_tb      y_ta       y_ta - y_tb
+ * ```
+ *
+ * Registers the tooltip-content provider with the `ChartContext` so that when d3 fires a mouse-over
+ * event on a series. The content provider is returns the {@link addTooltipContent} function
+ * when called. And when called the {@link addTooltipContent} function adds the actual tooltip
+ * content to the SVG element.
+ * @param props The properties describing the tooltip content
+ * @return null
+ * @constructor
+ */
+export function ScatterPlotTooltipContent(props: Props): null {
+    const {
+        chartId,
+        container,
+        tooltip
+    } = useChart<Datum, SeriesLineStyle, NoTooltipMetadata, ContinuousAxisRange, ContinuousNumericAxis>()
+
+    const {registerTooltipContentProvider} = tooltip
+
+    const {margin, plotDimensions} = usePlotDimensions()
+
+    const {
+        xLabel,
+        yLabel,
+        beforeHeader = 'before',
+        afterHeader = 'after',
+        deltaHeader = '∆',
+        xValueFormatter = formatTime,
+        yValueFormatter = formatValue,
+        xChangeFormatter = formatTimeChange,
+        yChangeFormatter = formatValueChange,
+        style,
+    } = props
+
+    const tooltipStyle = useMemo(() => ({...defaultTooltipStyle, ...style}), [style])
+
+    // register the tooltip content provider, which when called on mouse-enter-series events
+    // will render the tooltip container and then the tooltip content. recall that that the
+    // tooltip content is generated in this plot (because this is the plot that holds all the
+    // information needed to render it), and the container for the content is rendered by
+    // the <Tooltip>, which this know nothing about.
+    //
+    // the 'registration function accepts a function of the form (seriesName, time, series) => TooltipDimensions.
+    // and that function has a closure on the content-specific information needed to add the
+    // actual content
+    useEffect(
+        () => {
+            if (container) {
+                // assemble the options for adding the tooltip
+                const options: TooltipOptions = {
+                    labels: {x: xLabel, y: yLabel},
+                    headers: {before: beforeHeader, after: afterHeader, delta: deltaHeader},
+                    formatters: {
+                        x: {value: xValueFormatter, change: xChangeFormatter},
+                        y: {value: yValueFormatter, change: yChangeFormatter},
+                    }
+                }
+
+                // register the tooltip content provider function with the chart hook (useChart) so that
+                // it is visible to all children of the Chart (i.e. the <Tooltip>).
+                registerTooltipContentProvider(
+                    (seriesName: string, time: number, tooltipData: TooltipData<Datum, NoTooltipMetadata>, mouseCoords: [x: number, y: number]) =>
+                        addTooltipContent(
+                            seriesName, time, tooltipData.series, mouseCoords,
+                            chartId, container, margin, plotDimensions, tooltipStyle,
+                            options
+                        )
+                )
+            }
+        },
+        [
+            chartId, container, margin, plotDimensions, registerTooltipContentProvider,
+            xLabel, xChangeFormatter, xValueFormatter,
+            yLabel, yChangeFormatter, yValueFormatter,
+            beforeHeader, afterHeader, deltaHeader,
+            tooltipStyle
+        ]
+    )
+
+    return null
+}
+
+/**
+ * Callback function that adds tooltip content and returns the tooltip width and text height
+ * @param seriesName The name of the series (i.e. the neuron ID)
+ * @param time The time (x-coordinate value) corresponding to the mouse location
+ * @param series The datum (t ms, s mV)
+ * @param mouseCoords The coordinates of the mouse when the event was fired (relative to the plot container)
+ * @param chartId The ID of this chart
+ * @param container The plot container (SVGSVGElement)
+ * @param margin The plot margins
+ * @param tooltipStyle The style properties for the tooltip
+ * @param plotDimensions The dimensions of the plot
+ * @param options The options passed through the function that adds the tooltip content
+ * @return The width and text height of the tooltip content
+ */
+function addTooltipContent(
+    seriesName: string,
+    time: number,
+    series: Series<Datum>,
+    mouseCoords: [x: number, y: number],
+    chartId: number,
+    container: SVGSVGElement,
+    margin: Margin,
+    plotDimensions: Dimensions,
+    tooltipStyle: TooltipStyle,
+    options: TooltipOptions
+): TooltipDimensions {
+    const {labels, formatters} = options
+    const [x, y] = mouseCoords
+    const [lower, upper] = boundingPoints(series, time, value => value.time, () => emptyDatum())
+
+    // display the neuron ID in the tooltip
+    const header = d3.select<SVGSVGElement | null, any>(container)
+        .append<SVGTextElement>("text")
+        .attr('id', `tn${time}-${seriesName}-${chartId}`)
+        .attr('class', 'tooltip')
+        .attr('fill', tooltipStyle.fontColor)
+        .attr('font-family', 'sans-serif')
+        .attr('font-size', tooltipStyle.fontSize)
+        .attr('font-weight', tooltipStyle.fontWeight)
+        .text(() => seriesName)
+
+
+    // create the table that shows the points that come before and after the mouse time, and the
+    // changes in the time and value
+    const table = d3.select<SVGSVGElement | null, any>(container)
+        .append("g")
+        .attr('id', `t${time}-${seriesName}-header-${chartId}`)
+        .attr('class', 'tooltip')
+        .attr('fill', tooltipStyle.fontColor)
+        .attr('font-family', 'sans-serif')
+        .attr('font-size', tooltipStyle.fontSize + 2)
+        .attr('font-weight', tooltipStyle.fontWeight + 150)
+
+
+    const headerRow = table.append('g').attr('font-weight', tooltipStyle.fontWeight + 550)
+    const hrLower = headerRow.append<SVGTextElement>("text").text(() => options.headers.before)
+    const hrUpper = headerRow.append<SVGTextElement>("text").text(() => options.headers.after)
+    const hrDelta = headerRow.append<SVGTextElement>("text").text(() => options.headers.delta)
+
+    const trHeader = table.append<SVGTextElement>("text").text(() => labels.x)
+    const trLower = table.append<SVGTextElement>("text").text(() => formatters.x.value(lower.time))
+    const trUpper = table.append<SVGTextElement>("text").text(() => formatters.x.value(upper.time))
+    const trDelta = table.append<SVGTextElement>("text").text(() => formatters.x.change(lower.time, upper.time))
+
+    const vrHeader = table.append<SVGTextElement>("text").text(() => labels.y)
+    const vrLower = table.append<SVGTextElement>("text").text(() => formatters.y.value(lower.value))
+    const vrUpper = table.append<SVGTextElement>("text").text(() => formatters.y.value(upper.value))
+    const vrDelta = table.append<SVGTextElement>("text").text(() => formatters.y.change(lower.value, upper.value))
+
+    const textWidthOf = (elem: TextSelection) => elem.node()?.getBBox()?.width || 0
+    const textHeightOf = (elem: TextSelection) => elem.node()?.getBBox()?.height || 0
+    const spacesWidthFor = (spaces: number) => spaces * textWidthOf(hrLower) / 5
+
+    // calculate the max width and height of the text
+    const tooltipWidth = Math.max(textWidthOf(header), spacesWidthFor(33))
+    const headerTextHeight = textHeightOf(header)
+    const headerRowHeight = textHeightOf(hrLower)
+    const timeRowHeight = textHeightOf(trHeader)
+    const valueRowHeight = textHeightOf(vrHeader)
+    const textHeight = headerTextHeight + headerRowHeight + timeRowHeight + valueRowHeight
+
+    // set the header text location
+    const xCoord = tooltipX(x, tooltipWidth, plotDimensions, tooltipStyle, margin)
+    const yCoord = tooltipY(y, textHeight, plotDimensions, tooltipStyle, margin)
+    const xTooltip = xCoord + tooltipStyle.paddingLeft
+    const yTooltip = yCoord + tooltipStyle.paddingTop
+    header
+        .attr('x', () => xTooltip)
+        .attr('y', () => yTooltip - (headerRowHeight + timeRowHeight + valueRowHeight) + textHeight)
+
+
+    const hrRowY = yTooltip + headerTextHeight + headerRowHeight
+    const hrLowerX = spacesWidthFor(14)
+    const hrUpperX = spacesWidthFor(24)
+    const hrDeltaX = spacesWidthFor(32)
+    hrLower.attr('x', () => xTooltip + hrLowerX - textWidthOf(hrLower)).attr('y', () => hrRowY)
+    hrUpper.attr('x', () => xTooltip + hrUpperX - textWidthOf(hrUpper)).attr('y', () => hrRowY)
+    hrDelta.attr('x', () => xTooltip + hrDeltaX - textWidthOf(hrDelta)).attr('y', () => hrRowY)
+
+    const trRowY = hrRowY + timeRowHeight
+    trHeader.attr('x', () => xTooltip).attr('y', () => trRowY)
+    trLower.attr('x', () => xTooltip + hrLowerX - textWidthOf(trLower)).attr('y', () => trRowY)
+    trUpper.attr('x', () => xTooltip + hrUpperX - textWidthOf(trUpper)).attr('y', () => trRowY)
+    trDelta.attr('x', () => xTooltip + hrDeltaX - textWidthOf(trDelta)).attr('y', () => trRowY)
+
+    const vrRowY = trRowY + valueRowHeight
+    vrHeader.attr('x', () => xTooltip).attr('y', () => vrRowY)
+    vrLower.attr('x', () => xTooltip + hrLowerX - textWidthOf(vrLower)).attr('y', () => vrRowY)
+    vrUpper.attr('x', () => xTooltip + hrUpperX - textWidthOf(vrUpper)).attr('y', () => vrRowY)
+    vrDelta.attr('x', () => xTooltip + hrDeltaX - textWidthOf(vrDelta)).attr('y', () => vrRowY)
+
+    return {x: xCoord, y: yCoord, contentWidth: tooltipWidth, contentHeight: textHeight}
+}

package/src/app/charts/tooltips/Tooltip.tsx

@@ -0,0 +1,148 @@
+import {cloneElement, useEffect, useMemo, JSX} from "react";
+import {defaultTooltipStyle, removeTooltip, TooltipStyle} from "./tooltipUtils";
+import * as d3 from "d3";
+import {useChart} from "../hooks/useChart";
+import {usePlotDimensions} from "../hooks/usePlotDimensions";
+import {BaseAxis, SeriesStyle} from "../axes/axes";
+import {TooltipData} from "../hooks/useTooltip";
+import {BaseAxisRange} from "../axes/BaseAxisRange";
+
+export interface Props {
+    visible: boolean
+    style?: Partial<TooltipStyle>
+    children: JSX.Element
+}
+
+/**
+ * Tooltip component triggered by mouse-over-series events. When mounted, the tooltip component
+ * registers a mouse-over handler with the {@link useChart} hook using the
+ * {@link UseChartValues.registerTooltipContentProvider} function. The handler renders the tooltip
+ * by adding it to the SVG plot container. However, to remain general, this {@link Tooltip} also
+ * uses the {@link useChart}'s {@link UseChartValues.tooltipContentProvider} to render the actual
+ * content of the tooltip. The content provider is given the series' name on which the mouse-over
+ * event occurred, the plot time associated with mouse-over event, and the {@link TimeSeries}
+ * associated with the mouse-over event. The plot (for example {@link ScatterPlot}) is responsible
+ * for rendering the tooltip, and it registers this tooltip-content provider with the {@link useChart}
+ * hook.
+ *
+ * The {@link useChart} hook allows the plots and this tooltip to register methods needed its siblings.
+ *
+ * ## on mount
+ * 1. The plot (for example {@link ScatterPlot}) adds a d3 mouse-enter and mouse-leave event handlers
+ *    to each series. The mouse-enter event handler performs a few tasks and then calls the
+ *    mouse-over event handler registered by the {@link Tooltip} via the {@link useChart} hook.
+ * 2. The plot (for example {@link ScatterPlot}) registers the tooltip-content provider with the {@link useChart}
+ *    hook using the {@link UseChartValues.registerTooltipContentProvider} function.
+ * 3. {@link Tooltip} registers the handler for mouse-over events. The handler accepts the series
+ *    name, plot time, and time-series associated with the mouse-over event, and returns the tooltip
+ *    dimensions. In order to create/render the tooltip, it uses the {@link UseChartValues.tooltipContentProvider}
+ *    function that was registered via the {@link useChart} hook.
+ *
+ * ## on mouse-over event
+ * When the plot's (for example {@link ScatterPlot}) d3 mouse-enter event handler fires, the plot calls this
+ * {@link Tooltip}'s mouse-over handler, which creates the tooltip, and calls the {@link UseChartValues.tooltipContentProvider}
+ * registered by the plot to render the tooltip content, and get the tooltip size.
+ *
+ * @param props The properties of the tooltip (i.e. visibility and style)
+ * @return null
+ * @constructor
+ */
+export function Tooltip<D, S extends SeriesStyle, TM, AR extends BaseAxisRange, A extends BaseAxis>(props: Props): JSX.Element {
+    const {
+        chartId,
+        container,
+        tooltip,
+        mouse
+    } = useChart<D, S, TM, AR, A>()
+
+    const {
+        tooltipContentProvider,
+        setVisibilityState,
+    } = tooltip
+
+    const {margin, plotDimensions} = usePlotDimensions()
+
+    const {
+        visible,
+        style,
+        children
+    } = props
+
+    const {
+        registerMouseOverHandler,
+        unregisterMouseOverHandler,
+        registerMouseLeaveHandler,
+        unregisterMouseLeaveHandler
+    } = mouse
+
+    const tooltipStyle = useMemo(() => ({...defaultTooltipStyle, ...style}), [style])
+
+    // let the tooltip context know whether the tooltip is visible
+    setVisibilityState(visible)
+
+    useEffect(
+        () => {
+            const handlerId = `tooltip-${chartId}`
+            if (visible && container) {
+                const contentProvider = tooltipContentProvider()
+                if (contentProvider) {
+                    // register this tooltip's mouse-over event handler with the useCharts hook
+                    // so that the plots can call it when mouse-enter events are triggered (for
+                    // example, a mouse-over a time-series in the plot).
+                    registerMouseOverHandler(
+                        handlerId,
+                        (
+                            (
+                                seriesName: string,
+                                time: number,
+                                tooltipData: TooltipData<D, TM>,
+                                mouseCoords: [x: number, y: number],
+                                providerId?: string
+                            ) => {
+                                // create the rounded rectangle for the tooltip's background
+                                const rect = d3.select<SVGSVGElement | null, any>(container)
+                                    .append<SVGRectElement>('rect')
+                                    .attr('id', `r${time}-${seriesName}-${chartId}`)
+                                    .attr('class', 'tooltip')
+                                    .attr('rx', tooltipStyle.borderRadius)
+                                    .attr('fill', tooltipStyle.backgroundColor)
+                                    .attr('fill-opacity', tooltipStyle.backgroundOpacity)
+                                    .attr('stroke', tooltipStyle.borderColor)
+                                    .attr('stroke-width', tooltipStyle.borderWidth)
+
+                                // call the callback to add the content
+                                const {
+                                    x,
+                                    y,
+                                    contentWidth,
+                                    contentHeight
+                                } = contentProvider(seriesName, time, tooltipData, mouseCoords, providerId)
+
+                                // set the position, width, and height of the tooltip rect based on the text height and width and the padding
+                                rect.attr('x', () => x)
+                                    .attr('y', () => y)
+                                    .attr('width', contentWidth + tooltipStyle.paddingLeft + tooltipStyle.paddingRight)
+                                    .attr('height', contentHeight + tooltipStyle.paddingTop + tooltipStyle.paddingBottom)
+
+                            }
+                        )
+                    )
+
+                    registerMouseLeaveHandler(handlerId, () => removeTooltip())
+                }
+            }
+            return () => {
+                unregisterMouseOverHandler(handlerId)
+                unregisterMouseLeaveHandler(handlerId)
+            }
+        },
+        [
+            chartId, container, margin, plotDimensions,
+            registerMouseOverHandler, tooltipContentProvider, tooltipStyle,
+            unregisterMouseOverHandler, visible, registerMouseLeaveHandler,
+            unregisterMouseLeaveHandler
+        ]
+    )
+
+    return <>{cloneElement(children, props)}</>
+}

package/src/app/charts/tooltips/tooltipUtils.ts

@@ -0,0 +1,216 @@
+import {Series} from "../plots/plot";
+import * as d3 from "d3";
+import {Datum} from "../series/timeSeries";
+import {Dimensions, Margin} from "../styling/margins";
+import {OrdinalStringAxis} from "../axes/axes";
+
+/**
+ * Properties for rendering the tooltip. This is the style for the container
+ * of the content.
+ */
+export interface TooltipStyle {
+    /**
+     * Visibility of the tooltip when the mouse hovers over a data series or point.
+     */
+    visible: boolean
+
+    /**
+     * The size of the font displayed in the tooltip
+     */
+    fontSize: number
+    /**
+     * The color of the text displayed in the tooltip
+     */
+    fontColor: string
+    /**
+     * The font family for the text displayed in the tooltip
+     */
+    fontFamily: string
+    /**
+     * The font weight for the text displayed in the tooltip
+     */
+    fontWeight: number
+
+    /**
+     * The background color
+     */
+    backgroundColor: string;
+    backgroundOpacity: number;
+
+    borderColor: string;
+    borderOpacity: number;
+    borderWidth: number;
+    borderRadius: number;
+
+    paddingLeft: number;
+    paddingRight: number;
+    paddingTop: number;
+    paddingBottom: number;
+}
+
+export const defaultTooltipStyle: TooltipStyle = {
+    visible: false,
+
+    fontSize: 12,
+    fontColor: 'rgba(10,31,58,0.99)',
+    // fontColor: '#d2933f',
+    // fontColor: '#202020',
+    fontFamily: 'sans-serif',
+    fontWeight: 250,
+
+    backgroundColor: '#202020',
+    backgroundOpacity: 0.8,
+
+    borderColor: '#d2933f',
+    borderOpacity: 1,
+    borderWidth: 1,
+    borderRadius: 5,
+
+    paddingLeft: 10,
+    paddingRight: 10,
+    paddingTop: 5,
+    paddingBottom: 10,
+};
+
+export interface TooltipDimensions {
+    x: number,
+    y: number,
+    contentWidth: number,
+    contentHeight: number
+}
+
+/**
+ * Removes the tooltip when the mouse has moved away from the spike
+ */
+export function removeTooltip() {
+    d3.selectAll<SVGPathElement, Datum>('.tooltip').remove()
+}
+
+/**
+ * Calculates the x-coordinate of the upper left-hand side of the tooltip rectangle (obviously without
+ * "rounded corners"). Adjusts the x-coordinate so that tooltip is visible on the edges of the plot.
+ * @param x The current x-coordinate of the mouse
+ * @param textWidth The width of the tooltip text
+ * @param plotDimensions The dimensions of the plot
+ * @param tooltipStyle The tooltip style information
+ * @param margin The plot margin
+ * @return The x-coordinate of the lower left-hand side of the tooltip rectangle
+ */
+export function tooltipX(x: number, textWidth: number, plotDimensions: Dimensions, tooltipStyle: TooltipStyle, margin: Margin): number {
+    if (x > plotDimensions.width + margin.left - (textWidth + tooltipStyle.paddingLeft + tooltipStyle.paddingRight)) {
+        return x - textWidth - margin.right + tooltipStyle.paddingRight + tooltipStyle.paddingLeft
+    }
+    return x + tooltipStyle.paddingLeft
+}
+
+/**
+ * Calculates the y-coordinate of the upper-left-hand corner of the tooltip rectangle. Adjusts the y-coordinate
+ * so that the tooltip is visible on the upper edge of the plot
+ * @param y The y-coordinate of the mouse
+ * @param textHeight The height of the header and neuron ID text
+ * @param plotDimensions The dimensions of the plot
+ * @param tooltipStyle The tooltip style information
+ * @param margin The plot margin
+ * @return The y-coordinate of the lower-left-hand corner of the tooltip rectangle
+ */
+export function tooltipY(y: number, textHeight: number, plotDimensions: Dimensions, tooltipStyle: TooltipStyle, margin: Margin): number {
+    if (y > plotDimensions.height + margin.top - (textHeight + tooltipStyle.paddingTop + tooltipStyle.paddingBottom)) {
+        return plotDimensions.height + margin.top - (textHeight + tooltipStyle.paddingTop + tooltipStyle.paddingBottom)
+    }
+    return y + tooltipStyle.paddingTop
+}
+
+/**
+ * Calculates the y-coordinate for the upper-left-hand the tooltip rectangle. Adjusts the y-coordinate so
+ * that the tooltip is visible on the upper and lower edges of the plot
+ * @param seriesName The name of the series
+ * @param textHeight The height of the header and neuron ID text
+ * @param axis The category axis for determining the y-value of the tooltip
+ * @param tooltipStyle The tooltip style
+ * @param margin The plot margin
+ * @param categoryHeight The height (in pixels) of the category
+ * @param plotDimensions The dimensions of the plot
+ * @return The y-coordinate of the lower-left-hand corner of the tooltip rectangle
+ */
+export function categoryTooltipY(
+    seriesName: string,
+    textHeight: number,
+    axis: OrdinalStringAxis,
+    tooltipStyle: TooltipStyle,
+    margin: Margin,
+    categoryHeight: number,
+    plotDimensions: Dimensions
+): number {
+    const y = axis.scale(seriesName) || 0
+    const halfHeight = (tooltipStyle.paddingBottom + textHeight + tooltipStyle.paddingTop) / 2
+    if (y < halfHeight) {
+        return margin.top
+    }
+    if (y > plotDimensions.height + margin.top - halfHeight) {
+        return plotDimensions.height + margin.top - textHeight
+    }
+    return y + margin.top - halfHeight + categoryHeight / 2
+}
+
+/**
+ * Returns the index of the data point whose time is the upper boundary on the specified
+ * time. If the specified time is larger than any time in the specified data, the returns
+ * the length of the data array. If the specified time is smaller than all the values in
+ * the specified array, then returns -1.
+ * @param data The array of points from which to select the
+ * boundary.
+ * @param value The time for which to find the bounding points
+ * @param xFrom A function that extracts the x-value from the datum
+ * @template D The type of the datum in the data-series
+ * @return The index of the upper boundary.
+ */
+function boundingPointsIndex<D>(data: Series<D>, value: number, xFrom: (value: D) => number): number {
+    const length = data.length
+    if (value > xFrom(data[length - 1])) {
+        return length
+    }
+    if (value < xFrom(data[0])) {
+        return 0
+    }
+    return data.findIndex((_, index, array) => {
+        const lowerIndex = Math.max(0, index - 1)
+        return xFrom(array[lowerIndex]) <= value && value <= xFrom(array[index])
+    })
+}
+
+/**
+ * Returns the (time, value) point that comes just before the mouse and just after the mouse
+ * @param data The time-series data
+ * @param value The time represented by the mouse's x-coordinate
+ * @param xFrom A function that extracts the x-value from the datum
+ * @param emptyDatum A function that returns an empty datum
+ * @template D The type of the datum in the data-series
+ * @return {[[number, number], [number, number]]} the (time, value) point that comes just before
+ * the mouse and just after the mouse. If the mouse is after the last point, then the "after" point
+ * is `[NaN, NaN]`. If the mouse is before the first point, then the "before" point is `[NaN, NaN]`.
+ */
+export function boundingPoints<D>(data: Series<D>, value: number, xFrom: (value: D) => number, emptyDatum: () => D): [D, D] {
+    const upperIndex = boundingPointsIndex<D>(data, value, xFrom)
+    if (upperIndex <= 0) {
+        return [emptyDatum(), data[0]]
+    }
+    if (upperIndex >= data.length) {
+        return [data[data.length - 1], emptyDatum()]
+    }
+    return [data[upperIndex - 1], data[upperIndex]]
+}
+
+export function findPointAndNeighbors<D>(
+    data: Series<D>,
+    value: number,
+    tolerance: number,
+    xFrom: (value: D) => number,
+    emptyDatum: () => D
+): [D, D, D, number] {
+    // find the index of the point
+    const index = data.findIndex((_, index, array) => Math.abs(xFrom(array[index]) - value) <= tolerance)
+    const point = index > -1 ? data[index] : emptyDatum()
+    const lower = (index > 0) ? data[index-1] : emptyDatum()
+    const upper = (index < data.length - 1) ? data[index+1] : emptyDatum()
+    return [lower, point, upper, index]
+}