Skip to content

OrdinalFrame

Jump to bottom Edit New page
Ben Garvey edited this page Feb 20, 2022 · 9 revisions

A <Frame> that displays continuous data along the ordinal and range axes. Examples include bar charts, pie charts (which map the ordinal axis radially), violin plots, timelines and funnel diagrams. <OrdinalFrame> charts render pieces and summaries. Rendering and styling is based on each element's corresponding properties. OrdinalFrame data elements are accessible by tabbing to the data group (pieces or summaries) and hitting enter to arrow-key navigate through the data elements.

import { OrdinalFrame } from 'semiotic'

<OrdinalFrame
   data={[{department: "art", students: 50}, {department: "science", students: 8}, ...]}
   style={{ fill: "blue" }}
   rAccessor={"students"}
   oAccessor={"department"}
/>

<API Reference>

General Properties

size: {[width, height]}

If size is specified, sets the width and height of the frame from the array of values. The array must contain two numbers which represents the width and height, respectively.

Note: Margin will not be added to the frame size. It's more like CSS padding.

<OrdinalFrame size={[500,500]} ... />

rAccessor: { string | function }

If rAccessor is specified, determines how range values are accessed from the data array. In the case the data consists of an array of objects, a string can be used to assess the range value(s). A function can also be used to access the range value(s).

/*String option
e.g. data=[{value: 1, column: 1}, {value: 4, column: 2}, ... ]*/
<OrdinalFrame rAccessor={"value"} ... />

/*Function option
e.g. data=[[1, "art"], [2, "science"], ... ]*/
<OrdinalFrame rAccessor={d => d[0]} ... />

oAccessor: { string | function }

If oAccessor is specified, determines how ordinal values are accessed from the data array. In the case the data consists of an array of objects, a string can be used to assess the ordinal value(s). A function can also be used to access the ordinal value(s).

/*String option
e.g. data=[{value: 1, column: 1}, {value: 4, column: 2}, ... ]*/
<OrdinalFrame oAccessor={"column"} ... />

/*Function option
e.g. data=[[1, "art"], [2, "science"], ... ]*/
<OrdinalFrame oAccessor={d => d[1]} ... />

sortO: { function }

If sortO is specified, sets the sorting function of the columns. By default, the columns are sorted based on data order (the first item of a particular ordinal value will be the first column). The function sent to sortO is a simple array sorting function that takes the string name of ordinal values.

//sorts by alphabetical order
<OrdinalFrame sortO={(a,b) => a < b} ... />

projection: { string }

If projection is specified, sets the orientation of the chart. The three possible options are "horizontal", "vertical" or "radial". Defaults to "vertical".

<OrdinalFrame projection={"horizontal"} ... />

title: { string | JSX }

If title is specified, sets the text for the chart title, which appears centered at the top of the chart. The title can be either a string or JSX object.

/*String option*/
<OrdinalFrame title={"Chart Title"} ... />

/*JSX option*/
<OrdinalFrame title={<g><circle r={5} /><text>Chart Title</text></g>} ... />

margin: { number | object }

If margin is specified, sets the margin(s) on the frame. The margin can be set to one number, which is applied equally to all sides, or as an object. So it's more like CSS padding.

/*Single number option*/
<OrdinalFrame margin={10} ... />

/*Object option*/
<OrdinalFrame margin={{ top: 5, bottom: 10, left: 15, right: 20 }} ... />

rScaleType: { d3-scale }

Custom D3 scale for the range. Defaults to scaleLinear().

<OrdinalFrame rScaleType={d3.scaleTime()} ... />

oScaleType: { d3-scale }

Custom D3 scale for the ordinal values. Changing this can have strange effects.

<OrdinalFrame oScaleType={d3.scaleThreshold()} ... />

rExtent: { [min, max] | object }

If rExtent is specified, sets the min and/or max value(s) for the range. The array may contain two numbers, or it can contain a number and an undefined value, if you only want to set the min or max extent. If you send an object you can register a function to fire when the extent is recalculated that returns the calculated extent.

/*min and max values set*/
<OrdinalFrame rExtent={[20,250]} ... />

/*only min value set*/
<OrdinalFrame rExtent={[20, undefined]} ... />

/*log calculated extent*/
<OrdinalFrame rExtent={{ onChange: d => console.log("calculated extent: ", d) }} ... />

/*log calculated extent and set extent*/
<OrdinalFrame
   rExtent={{ extent: [20, undefined], onChange: d => console.log("calculated extent: ", d) }}
... />

invertR: { bool }

Flip range so that the min is on the left or top.

data: { array }

An array of objects or numerical values used to render both summary and piece visualizations in OrdinalFrame. The column of the data is based on its oAccessor value, while its position or height is determined by its rAccessor value.

<OrdinalFrame
   data={[ { column: "a", value: 5 }, { column: "b", value: 3 } ...]}
/>

oPadding: { number }

The distance in pixels between each column.

<OrdinalFrame
   oPadding={5}
/>

dynamicColumnWidth: { string | func }

If dynamicColumnWidth is specified, sets the column width of the frame based on the data. If a string, then columnWidth is proportionate to the total value of the string property for each column, for instance used in the Marimekko Chart example where bar width is based on the total value for that bar. If set to a function, the function is passed an array of pieces in that column which you can measure in any way you want, for instance in the Joy Plot example this is used to calculate the max value of a column and sets the column width proportional to that value.

/*String option*/
<OrdinalFrame dynamicColumnWidth={"value"} ... />

/*Function option*/
<OrdinalFrame dynamicColumnWidth={pieces => max(pieces.map(p => p.value))} ... />

pixelColumnWidth: { number }

If pixelColumnWidth is specified, the row (in the case of horizontal) or column (in the case of vertical) size will be fixed to the number specified. The corresponding size setting will be ignored as the height or width of the chart will be based on the number of columns times the set value.

<OrdinalFrame pixelColumnWidth={40} ... />

Piece Rendering

"Piece" refers to the individual components of data visualization forms like bar charts and swarm plots. A "piece" of a bar chart is a segment in a stacked bar chart or the entire bar of a simple bar chart, or one of the circles in a swarm plot.

type { string | object | func }

A string ("bar", "timeline", "clusterbar", "swarm", "point", "none") or object with type equal to one of those strings to use method-specific options such as { type: "swarm", r: 8 }, or a function that takes data and the OrdinalFrame calculated settings and creates JSX elements. See the Waterfall Chart in the interactive examples to see how to use custom type functions.

// basic
<OrdinalFrame type="bar" ... />

// with options
<OrdinalFrame type={{ type: "swarm", r: 20, customMark: d => <circle r={20} fill: "red" />}} ... />

style: { object | function }

A React style object or a function taking a single datapoint and returning a React style object. This is applied to each piece.

// object
<OrdinalFrame style={{ fill: "red" }} ... />

// function
<OrdinalFrame style={d => ({ fill: d.color })} ... />

pieceClass: { string | function }

A string or function that takes a piece and returns a string that is assigned to that piece's class.

// object
<OrdinalFrame pieceClass="cool-piece" ... />

// function
<OrdinalFrame pieceClass={d => d.classSettings} ... />

Summary Rendering

"Summary" refers to a complex visual element that summarizes all of the datapoints that fall within a particular column. These can be single shapes, like a violin plot, or multiple pieces, like a histogram or heat map.

summaryType { string | object | func }

A string ("heatmap", "boxplot", "histogram", "joy", "contour", "violin") or object with type equal to one of those strings (with further method-specific settings such as { type: "contour", bandwidth: 15 } or { type: "joy", amplitude: 30 }, or a function that takes data and the OrdinalFrame calculated settings and creates JSX elements. See summaryType Advanced Settings for more details on how to use the extended settings.

// string
<OrdinalFrame summaryType="violin" ... />

// object
<OrdinalFrame summaryType={{ type: "joy", amplitude: 30 }} ... />

summaryStyle: { object | function }

A React style object or a function taking a single datapoint and returning a React style object. This is applied to each piece.

// object
<OrdinalFrame summaryStyle={{ fill: "red" }} ... />

// function
<OrdinalFrame summaryStyle={d => ({ fill: d.color })} ... />

summaryClass: { string | function }

A string or function that takes a piece and returns a string that is assigned to that piece's class.

// string
<OrdinalFrame summaryClass="cool-class" ... />

// function
<OrdinalFrame summaryClass={d => d.customClass} ... />

summaryPosition: { function }

A function that takes a the middle of a summary, the key, and the index of the summary and returns a value that will be applied across the axis of the projection with translate (x for vertical projections, y for horizontal projections).

Annotation and Decoration

tooltipContent: { function }

A function returning JSX HTML to display in the tooltip (only active if hoverAnnotation or pieceHoverAnnotation is set to true). The tooltip is passed the array of pieces associated with the column being hovered. The content is placed on and directly above the hovered point, so take that into account when using CSS to style the position and any additional elements. You can drop any HTML into this floating div, including another frame, if you want to have data visualization in your data visualization so you can visualize while you visualize.

<OrdinalFrame
   tooltipContent={d => <div className="tooltip-content">
     <p>{d.name}</p>
     <p>{d.value}</p>
   </div>}
/>

axis: { object }

An object that define the range axis. These objects roughly correspond to the options in d3-axis, with extended options such as label. Use oLabel to set labels for the columns.

<OrdinalFrame
   axis={{ orient: "left" }}
/>

legend: { object }

An object that defines the legend to be displayed on the frame. It uses the format seen in 

<OrdinalFrame
  legend={{
    legendGroups: [
      {
        styleFn: d => ({ fill: d.color, stroke: 'black' }),
        items: [
          { label: 'Area 1', color: 'red' },
          { label: 'Area 2', color: 'blue' },
        ],
      },
    ],
  }}
  ...
/>

oLabel: { bool | function | object }

Whether to show a labels for each column (simple boolean true) or a function that takes the string value associated with the column (from your oAccessor) and returns JSX centered on the basic title location. Or an object with a label prop that can be a bool or a function allowing for more complex placement. Currently this is just an orient prop that can be "right" or "top" to change the label position from the default left (for horizontal) or right (for vertical) or "stem" or "center" to change a radial label from its default edge as well as a padding prop that determines the outset or inset of a label in radial mode.

// boolean
<OrdinalFrame oLabel={true} ... />

// function
<OrdinalFrame oLabel={d => <text fontSize={36}>{d}</text> } ... />

// object
<OrdinalFrame oLabel={
   { label: true,
     orient: "stem",
     padding: -5  }
} ... />

annotations: { array }

An array of objects to be processed using the frame's built-in annotation rules or the custom defined rules. See Using Annotations for more details.

<OrdinalFrame
   annotations={[
      { type: "or", value: 5, category: "tomatoes", label: "5 of these tomatoes" }
   ]}
 />

svgAnnotationRules: { function }

A function that takes an annotation object and returns a JSX SVG element. The function is sent { d, i, oScale, rScale, oAccessor, rAccessor, ordinalFrameProps, adjustedPosition, adjustedSize, annotationLayer, ordinalFrameState }

htmlAnnotationRules: { function }

A function that takes an annotation object and returns a JSX HTML element. The function is sent { d, i, oScale, rScale, oAccessor, rAccessor, ordinalFrameProps, adjustedPosition, adjustedSize, annotationLayer, ordinalFrameState }. Elements can be placed using CSS left and top and will overlay on the chart. Internally, the default annotation for tooltips uses this method.

annotationSettings: { object }

An object with { layout, pointSizeFunction, labelSizeFunction } containing custom annotation settings to enable annotations bumping out of each others' way or placing them in the margins.

backgroundGraphics: { array | JSX }

A JSX or array of JSX to display behind the chart.

foregroundGraphics: { array | JSX }

A JSX or array of JSX to display in front of the chart.

Interaction

hoverAnnotation: { bool }

Turn on automatic tooltips for each column with a column overlay to improve interaction. Content of the tooltips defaults to the o and r value and can be customized with tooltipContent. Tooltip is shown at the max or sum value of the column.

pieceHoverAnnotation: { bool | object }

Turn on automatic tooltips for individual pieces with a voronoi overlay to improve interaction. Content of the tooltips defaults to the o and r value and can be customized with tooltipContent. If you are displaying both pieces and summaries, you can send an object with { onlyPieces: true } to force the overlay to generate based on pieces, otherwise it will default to generating the overlay based on summaries.

customHoverBehavior: { function }

A function to fire on hover that passes the column or piece being hovered over.

customClickBehavior: { function }

A function to fire on click that passes the column or piece being hovered over.

customDoubleClickBehavior: { function }

A function to fire on doubleclick that passes the column or piece being hovered over.

interaction: { object }

An object passed to the interaction layer that is currently only used to determine whether to activate the column brushes, their settings, and the actions to fire on its start, brush and end events. See the Parallel Coordinates and Brushable Swarm Plot in the interactive examples.

Miscellaneous

name: { string }

Used internally to identify frames, which comes in handy when you need to link frames together.

position: { array }

Just an offset and hardly ever useful

additionalDefs: { JSX }

JSX to be injected into the visualization layer's SVG defs.

download: { bool }

Enable a download button to download the data as a CSV

downloadFields: { array }

The field keys to download from each datapoint. By default, the CSV download only shows the o and r values.

Add a custom footer
Add a custom sidebar
Clone this wiki locally