vahub charts

vahub-charts directory (vahub/src/main/webapp/src/vahub-charts) contains all the chart classes that are used to plot the study data. They are built with d3.js.

Table of contents:

• List of implemented chart types
• Chart class properties
• Chart class methods
• Creating a new chart instance
• Referenced interfaces and types
• Publishing to nmp

List of implemented chart types

• ScatterChart - plotting scattered data across linear x and y axes (type: scatter)
• LineChart and SimpleLineChart - plotting groups of markers connected by lines across different axes (linear or category for x-axis and linear or logarithmic for y-axis) (type: line / simple-line)
• RangeChart - same as LineChart/SimpleLineChart but with ranges for deviations around the lines (type: range)
• StackedBarChart - plotting bars across category x and linear y axes. For one x category there may be multiple bars stacked on top of each other (type: stacked-bar-plot)
• GroupedBarChart - plotting bars across category x and linear y axes. For one category there may be multiple bars that will be displayed side-by-side, separated with a category sub-scale (type: grouped-bar-plot)
• BarLineChart - same as StackedBarChart, but adding another constant y-axis for displaying continuous (line-like) data (type: barline)
• BoxPlot - plotting statistical data with boxes across linear/category x-axis and linear y-axis (mean value, quartiles, whiskers) and dots (outliers) (type: boxplot)
• ShiftPlot - plotting range (minimum and maximum values) around the baseline across linear/category x-axis and linear y-axis (type: errorbar)
• HeatMapChart - plotting heat map between two categorical axes (type: heatmap)
• ChordDiagram - plotting chord diagram to show connections between entries (type: chord)
• TimeLineBarChart - plotting data as a continuous bar and specific markers across linear x-axis (type: timeline-barchart)
• TimelineLineChart - plotting data as a continuous line (with markers at points) across linear x and y axes (type: timeline-linechart)
• TimelineAxis - axis to be used with a group of TimelineBarCharts of TimelineLineCharts(type: timeline-xaxis)

Chart class properties

Public properties

• container: HTMLElement - an HTML element in which the chart is drawn
• series: Array<Series> - an array of data series to be plotted
• title: string - chart title
• height: number - chart height
• width: number - chart width
• xAxis: Array<Axis> - an array of charts x-axis
• yAxis: Array<Axis> - an array of charts y-axis
• svg: d3.Selection<SVGElement> - svg element containing the chart
• margins: Margins - margins from the borders of a svg to the actual chart elements (interface)
• isInverted: boolean - are charts axes inverted (vertical x-axis and horizontal y-axis)
• innerSpaceSelectorForExport: string - selector of the element containing all the chart elements for export
• xScale: d3.Selection<SVGElement, {}, HTMLElement, any> - d3 scaling function for x-axis
• yScale: d3.Selection<SVGElement, {}, HTMLElement, any> - d3 scaling function for y-axis
• limits: Object - borders for x and y axes (for zooming)
  • x: Array<number> - first value (index 0) stands for lower limit, second (index 1) - for upper limit
  • y: Array<number>

Protected properties

• id: string - chart ID
• chartType: string - chart type (should correspond to chart types)
• animationTime: number - scaling animation time in milliseconds (if set to 0 chart won't be animated)
• tooltip: ChartTooltip - configuration for chart tooltip (interface)
• plotLines: Array<PlotLine> - a set of pre-determined lines to be drawn (e.g., level of y=5) (interface)
• click: Function - handling click or double-click on chart
• displayMarkingDialogue: Function - displaying dialog window on selection
• removeSelection: Function - removing chart selection
• selection: Function - adding data selection
• xAxisScale: d3.Selection<SVGElement, {}, HTMLElement, any> - d3 x-axis element to be drawn
• yAxisScale: d3.Selection<SVGElement, {}, HTMLElement, any> - d3 y-axis element to be drawn
• tooltipContainer: d3.Selection<SVGElement, {}, HTMLElement, any> - selected tooltip container for this chart
• tooltipTimeout: number - timeout for changing tooltip state (position, content. displaying) in milliseconds
• minHeight: number - minimum chart height
• resizeTimeout: number - timeout for applying changes to charts appearence on window resize
• selectionZones: Array<ZoneSelection> - an array of selection zones that should be drawn (interface)
• noDataMessage: string - a message to be displayed instead of the chart

Chart class methods

Public methods

• onZoomX: function(borders: Array<number>): void - set new limits on x-axis and redraw the chart
• onZoomY: function(borders: Array<number>): void - set new limits on y-axis and redraw the chart
• setSize: function(width: number, height: number): void - set new size for the chart
• addSeries: function(options: SeriesOptions<SeriesItemType>): void - add new series to charts series property
• clearSeries: function(): void - remove all chart series (set chart.series = [])
• addPlotLine: function(line: PlotLine): void - add line to charts plotLines property
• redraw: function(animate?: boolean): void - redraw the chart (whether animated, without clearing contents of svg, or completely)
• resize: function(): void - redraw the chart after resize and set new height parameter value
• getSVG: function(): string - get serialised contents of charts svg for export
• setTitle: function(title: string): void - set new chart title
• setNoDataMessage: function(message: string): void - set a message to display instead of the chart
• destroy: function(): void - remove charts svg element and tooltip from the document

Protected methods

• abstract initSeries: function(options: SeriesOptions<SeriesItemType>): Array<Series> - preform data from options to series property
• addTooltip: function(): void - add tooltipContainer for this chart
• setAxis: function(): void - set single x and y axes
• animateOnZoom: get(): boolean - get whether chart is animated (animationTime !== 0) of not
• init: function(options: UserOptions): void - initialization function that:
  • sets UserOptions values to chart properties
  • adds buttons for chart export (if not disabled)
  • adds an svg element to charts container
  • adds window resize event listener
• drawPlotLines: function(): void - draw plot lines added to plotLines property
• handleMouseOver: function(event, d, tooltipText?, movementAnimationTime?): void - handler for mouseenter over chart element (to show tooltip)
• handleMouseOut: function(): void - handler for mouseleave from chart element (to hide tooltip)
• clipPathId: get(): string - getter for this charts clip path id
• clipPathURL: get(): string - getter for this charts clip path URL
• addClipPath: function(): void - draw clip path for this chart
• resizeClipPath: function(height: number): void - resize clip path with a new height value
• handleResize: function(): void - handler for window resize event listener, resizes the chart
• redrawSelectionZones: function(xScale, yScale, selectedZonesContainer?, animate?): void - redraw already drawn selection zones
• showNoData: function(): void - draw message from noDataMessage instead of a chart

Creating a new chart instance

A new chart instance is created in a createChart method of AbstractPlotComponent. It uses chart function from index.ts.
A configuration object should be passed with properties as described below. It is created in a createPlotConfig method of a plot component. It uses this components config service. chart function uses chart.type property of a configuration object to create and return an instance of the appropriate chart (as stated here).

UserOptions interface

• chart: Object
  • renderTo: HTMLElement - an HTML element in which chart will be drawn
  • id: string - chart id
  • height: number - chart height
  • type: string - chart type (should correspond to chart types)
  • events?: Object - handlers for chart events
    • displayMarkingDialogue: Function - displaying dialog window on selection
    • removeSelection: Function - removing chart selection
    • selection: Function - adding data selection
    • click: Function - handling click or double-click on chart
  • animationTime?: number - scaling animation time in milliseconds (if set to 0 chart won't be animated)
  • disableExport?: boolean - should exporting be unavailable for this chart
  • margins?: Margins - margins from the borders of a svg to the actual chart elements (interface)
• plotOptions?: Object
  • markerSymbol?: string - type of marker to use (currently only available option is 'diamond' for SimpleLineChart)
• plotLines?: Array<PlotLine> - a set of pre-determined lines to be drawn (e.g., level of y=5) (interface)
• yAxis?: PlotAxisConfig - y axis configuration (interface)
• xAxis?: PlotAxisConfig - same as yAxis
• tooltip?: Object - configuration for chart tooltip (interface)

Referenced interfaces and types

ZoneSelection interface

• xMin: number - start x coordinate of selected zone
• xMax: number - end x coordinate of selected zone
• yMin: number - start y coordinate of selected zone
• yMax: number - end y coordinate of selected zone

ChartTooltip interface

• formatter: () => void - function to parse data from chart element to tooltip content (HTML)
• onclick?: (element: HTMLElement, event: any) => void - any specific handler for click on tooltip

Margins interface

• left?: number
• right?: number
• top?: number
• bottom?: number
• bottomWithRotatedLabels?: number - maximum bottom margin when lower axis labels are rotated

PlotLine interface

• axis?: string - name of axis this line should be parallel to ('x' or 'y')
• width?: number - total length of a parallel line
• value?: number - line level (e.g., if axis='x' if would stand for y-axis value)
• color?: string - line color (any css)
• x1, x2, x3, x4?: number - if the line is not parallel to any of the axes it can be set by its start and end coordinates
• styles?: Object - object with any css styles to be applied to the line (e.g., stroke-dasharray: 1)

PlotAxisConfig interface

• title?: Object - axis title parameters
  • text: string - axis title text
• type?: string - axis type
• categories?: Array<string> - list of all axis categories
• borders?: { min: number, max: number } - initial axis limits

Axis types

• ScaleTypes
  • LINEAR_SCALE = linear
  • LOGARITHMIC_SCALE = logarithmic
  • DATETIME_SCALE = datetime
  • CATEGORY_SCALE = category

Publishing to npm

vahub-charts directory can be moved to separate project and published to npm.

Entry points:

1. vahub/src/main/webapp/src/app/common/trellising/grid/plot/plottypes/AbstractPlotComponent.ts
2. vahub/src/main/webapp/src/styles.styl

Steps to achieve this:

1. Create repo
2. Setup new Typescript project (libriary)
3. Setup testing environment, linter
4. Move code to new repo
5. Add documentation
6. Publish to npm
7. Include to vahub as dependency
8. For development purpouses dependency can be substituted with npm-link