charts

Default background color for chart rendering

Random seed to use when picking pseudo-random colors for charts

Default font for chart rendering

Default color for grid lines

Default padding for charts

Default color for drawn lines such as frame borders

Default font color for title and axis labels

(color-lerp a b t)

A table containing various default color maps that can be used for rendering heat map data.
Each value is a function mapping real numbers in the range [0, 1] to colors represented as 32 bit integers.

(dark-mode)

Set dynamic color defaults to dark mode

(draw-axes &named canvas width height padding inner-padding inner-padding-x inner-padding-y font x-min x-max y-min y-max min-x-spacing min-y-spacing grid format-x format-y x-label y-label tick-length x-suffix x-prefix y-suffix y-prefix x-ticks y-ticks x-grid-ticks y-grid-ticks grid-between-x grid-between-y x-minor-ticks y-minor-ticks x-labels-vertical transpose)

Draw the axis for the chart. Also return a function that can be used
to convert a coordinate in the metric space to the screen space. Most parameters
are optional with sane defaults, but canvas, x-min, x-max, y-min, y-max are all required.

* :canvas - gfx2d/image to draw the axes on
* :width - (if no canvas provided) - make a new canvas with the given width in pixels
* :height - (if no canvas provided) - make a new canvas with the given height in pixels
* :x-label - optional label for the x axis
* :y-label - optional label for the y axis
* :padding - the number of pixels to leave around all drawn content
* :inner-padding - how many pixels to add between the axes frame and the internal graphing area. Defaults to 8.
* :inner-padding-x - inner-padding for the x-axis only.
* :inner-padding-y - inner-padding for the y-axis only.
* :font - the font to use for axis text
* :{x,y}-{min,max} - The bounds for coordinate system to draw
* :grid - Style for drawing grid-lines. Can be nil (none), :none, :solid, or :stipple
* :format-x - unary function (fn [x] ...) that returns a string to label x axis tick marks with
* :format-y - unary function (fn [y] ...) that returns a string to label y axis tick marks with
* :x-prefix - if format-x not provided, allows easily adding a string prefix to x axis tick mark labels
* :y-prefix - if format-y not provided, allows easily adding a string prefix to y axis tick mark labels
* :x-suffix - if format-x not provided, allows easily adding a string suffix to x axis tick mark labels
* :y-suffix - if format-y not provided, allows easily adding a string suffix to y axis tick mark labels
* :x-ticks - An array of x coordinates used marking the x axis rather than making a guess. These will be labeled.
* :y-ticks - An array of y coordinates used marking the x axis rather than making a guess. These will be labeled.
* :x-grid-ticks - An array of x coordinates that are used for drawing a grid. Can be combined with x-ticks for separate labels and grid-line locations.
* :y-grid-ticks - An array of y coordinates that are used for drawing a grid. Can be combined with y-ticks for separate labels and grid-line locations.
* :x-minor-ticks - How many minor tick marks, if any, to place between major tick marks on the x axis
* :y-minor-ticks - How many minor tick marks, if any, to place between major tick marks on the y axis
* :x-labels-vertical - Turn x labels vertical so more can fit on the axis
* :min-x-spacing - When guessing x ticks, allow setting a lower limit to the metric spacing between ticks
* :min-y-spacing - When guessing y ticks, allow setting a lower limit to the metric spacing between ticks
* :tick-length - how many pixels long to make major tick marks (minor tick marks are 1/2 major tick marks)
* :transpose - Consider the x axis to be the vertical axis instead of the horizontal axis
* :grid-between-x - Put grid-lines between X-axis labels on the x-axis instead of on them.
* :grid-between-y - Put grid-lines between X-axis labels on the y-axis instead of on them.

Returns a 4-tuple [view:gfx2d/image to-pixel-space:fn to-metric-space:fn outer-canvas:gfx2d/image]

* `view` is an image that can be used to draw inside the chart, clipped so you don't overwrite that axes.
* `(to-pixel-space metric-x metric-y)` converts metric space coordinates to pixel space for plotting on `view`.
* `(to-metric-space pixel-x pixel-y)` converts pixel coordinates to the metric space.
* `outer-canvas` is the input canvas or newly create enclosing image for the entire figure.

(draw-heat-legend canvas &named swatch-width swatch-height background-color font padding color-map frame line-color text-color layout labels)

Draw a legend that describes a heat-map color range.

`canvas` can be either nil to skip drawing or a gfx2d/image.

* :swatch-width - width of the color gradient in pixels
* :swatch-height - height of the color gradient in pixels
* :background-color - the color of the background of the legend
* :font - the font to use for legend text
* :padding - the number of pixels to leave around all drawn content
* :color-map - a table/struct that maps labels to colors
* :line-color - color to draw frame border
* :text-color - color of text
* :labels - a list of labels to draw in the legend
* :frame - whether or not to draw a frame around the legend

Return [w h] of the area that was or would be drawn if the legend were to be drawn.

(draw-legend canvas &named background-color font padding color-map labels view-width frame color-seed legend-map line-color text-color)

Draw a legend given a set of labels and colors

`canvas` can be either nil to skip drawing or a gfx2d/image.

* :background-color - the color of the background of the legend. Use :none to skip drawing a background.
* :font - the font to use for legend text
* :padding - the number of pixels to leave around all drawn content
* :color-map - a table/struct that maps labels to colors
* :legend-map - a table/struct that maps labels to text to draw
* :line-color - color to draw frame border
* :text-color - color of text
* :labels - a list of labels to draw in the legend
* :view-width - width of the enclosing view in pixels to help hint how to size the legend.
* :frame - whether or not to draw a frame around the legend

Return [w h] of the area that was or would be drawn if the legend were to be drawn.

(heat-map-chart &named canvas width height data data-scale xs ys color-fn cell-text-fn num-columns num-rows font title-font cell-font color-map background-color text-color cell-text-color x-min x-max y-min y-max format-x format-y padding title box-gap legend legend-frame legend-labels x-label y-label x-suffix x-prefix y-suffix y-prefix x-ticks y-ticks x-minor-ticks y-minor-ticks tick-length x-labels-vertical legend-width legend-height save-as)

Generate a heat map.

Basic Parameters
* :canvas - A gfx2d/image to draw on
* :width - (if no canvas provided) - make a new canvas with the given width in pixels
* :height - (if no canvas provided) - make a new canvas with the given height in pixels
* :color-map - a color map keyword or function used to map numbers in the range [0, 1] to a color.
* :save-as - optional path to save the chart

Function Callback Input
* :num-columns - Number of columns to draw.
* :num-rows - Number of rows to draw.
* :color-fn - Function `(color-fn x y)` that returns a gfx2d color used to color each cell in the heat-map. If color-fn evaluates to a falsey value, that cell will be left blank.
* :cell-text-fn - Function `(cell-text-fn x y)` that returns an optional string to render for each cell. If the function evaluates to nil, no text will be drawn for that cell.

Data Frame Input
* :data - a data-frame table that contains a grid of cell
* :data-scale - map numeric data to a [0.0, 1.0] range with a scale factor or function. Is the constant 1.0 by default.
* :xs - a list of x columns - these are keys in `data`
* :ys - (optional) keys into each column - by default this is just (range num-rows-in-data).

Axes Styling
* :x-ticks - manually set the tick marks on the X axis instead of auto-detecting them
* :y-ticks - manually set the tick marks on the Y axis instead of auto-detecting them
* :x-label - optional label for the x axis
* :y-label - optional label for the y axis
* :x-suffix - add a string suffix to each tick label on the x-axis
* :y-suffix - add a string suffix to each tick label on the x-axis
* :x-prefix - add a string prefix to each tick label on the y-axis
* :y-prefix - add a string prefix to each tick label on the y-axis
* :x-minor-ticks - how many, if any, small ticks to add between each large tick mark on the x axis
* :y-minor-ticks - how many, if any, small ticks to add between each large tick mark on the y axis
* :x-labels-vertical - Turn x labels vertical so more can fit on the axis
* :tick-length - how long to make major tick marks

Chart Styling
* :box-gap - Number of pixels between boxes on the heat map. Default is 0.
* :cell-font - font used to draw optional text in cells
* :cell-text-color - color of text, defaults to black or white, depending on cell color
* :font - font used to draw axes
* :title-font - font used to draw title. Defaults to font.
* :text-color - color of axes and title text
* :padding - Number of pixels to separate various elements of the chart
* :background-color - chart background color. Use :none to skip drawing a background.
* :legend - one of :top, :bottom, :left, :right, :top-left, :top-right, :bottom-left, :bottom-right, or :none
* :legend-labels - an array of evenly-spaced markers to put on the color map legend.
* :legend-width - width of color map gradient in the legend in pixels
* :legend-height - height of the color map gradient in the legend in pixels

Returns a new canvas.

(invert-color-map mapping)

Create an inverted color-map from an existing color map.

(light-mode)

Set dynamic color defaults to light mode

(line-chart &named canvas width height data font background-color text-color color-map point-radius x-min x-max y-min y-max padding inner-padding inner-padding-x inner-padding-y title circle-points scatter grid legend legend-labels super-sample stroke-thickness format-x format-y save-as legend-map legend-padding tick-length line-style line-style-per-column bar-padding x-label y-label x-suffix x-prefix y-suffix y-prefix x-column y-column x-ticks y-ticks x-minor-ticks y-minor-ticks x-grid-ticks y-grid-ticks x-labels-vertical grid-between-x grid-between-y annotate transpose)

Render a line chart. Returns a gfx2d/image which can be further manipulated with the spork/gfx2d module.

Basic Parameters
* :canvas - a gfx2d/image to draw on
* :width - (if no canvas provided) - make a new canvas with the given width in pixels
* :height - (if no canvas provided) - make a new canvas with the given height in pixels
* :data - a data frame to use for data
* :title - an optional title to add to the rendered image
* :font - font used to draw text, including title, legend, and axes labels
* :save-as - save the generated image to file. Can be any format supported by the gfx2d module
* :x-column - the name of the data frame column to use for the x axis
* :y-column - a single column or array of column names to use for the chart
* :x-ticks - manually set the tick marks on the X axis instead of auto-detecting them
* :y-ticks - manually set the tick marks on the Y axis instead of auto-detecting them

Axes Styling
* :inner-padding - the number of pixels of white space between x-min and the x-axes as well as y-min and the y-axes.
* :inner-padding-x - inner-padding for x-axis only
* :inner-padding-y - inner-padding for y-axis only
* :x-label - optional label for the x axis
* :y-label - optional label for the y axis
* :grid - how to draw grid lines. One of :none, :solid, or :stipple
* :x-suffix - add a string suffix to each tick label on the x-axis
* :y-suffix - add a string suffix to each tick label on the x-axis
* :x-prefix - add a string prefix to each tick label on the y-axis
* :y-prefix - add a string prefix to each tick label on the y-axis
* :x-ticks - Array of labeled x-coordinate locations.
* :y-ticks - Array of labeled y-coordinate locations.
* :x-grid-ticks - Array of x-coordinates for grid lines.
* :y-grid-ticks - Array of y-coordinates for grid lines.
* :x-minor-ticks - how many, if any, small ticks to add between each large tick mark on the x axis
* :y-minor-ticks - how many, if any, small ticks to add between each large tick mark on the y axis
* :x-labels-vertical - Turn x labels vertical so more can fit on the axis
* :tick-length - how long to make major tick marks
* :grid-between-x - Put grid-lines between X-axis labels on the x-axis instead of on them.
* :grid-between-y - Put grid-lines between X-axis labels on the y-axis instead of on them.

Chart Styling
* :padding - the number of pixels of white space around various elements of the chart
* :background-color - color of background, defaults to white. Use :none to skip drawing a background.
* :text-color - color of text, defaults to black
* :color-map - a dictionary mapping columns to colors. By default will hash column name to pseudo-random colors
* :scatter - set to true to disable lines connecting points
* :legend - set to true to add a legend to the top of the chart
* :legend-map - a dictionary mapping column names to pretty text for the chart
* :legend-labels - optional list of y-column names to display in the legend
* :legend-padding - extra padding around legend area
* :point-radius - radius of points when drawing a scatter plot
* :line-style - How to draw lines. Can be one of :stroke, :plot, :none, :bar, :area, or :stipple. Default is :plot.
* :line-style-per-column - Optional dictionary to override line style by y-column name.
* :super-sample - Super Sample anti-aliasing for chart lines. Is a bit slow, but makes smooth plots. Works best with :stroke and :bar
* :stroke-thickness - thickness in pixels of the stroke of the graph when :line-type = :stroke
* :annotate - an optional function to add annotations to a rendered chart. This function should take 3 arguments:
 (fn callback [view to-pixel to-metric] ...)

Axis Boundaries
* :x-min - minimum x coordinate on chart
* :x-max - maximum x coordinate on chart
* :y-min - minimum y coordinate on chart
* :y-max - maximum y coordinate on chart

(make-color-map & colors)

Create a function that linearly interpolates between colors for colormapping.

(plot-heat-map &named canvas width height color-fn cell-text-fn num-columns num-rows box-gap font cell-text-color)

Render a heat map on a set of axis. Will nicely fill the passed in image, so use a subview to draw to a section of the chart.

Basic Parameters
* :canvas - A gfx2d/image to draw on
* :width - (if no canvas provided) - make a new canvas with the given width in pixels
* :height - (if no canvas provided) - make a new canvas with the given height in pixels
* :color-fn - Function `(color-fn x y)` that returns a gfx2d color (32 bit integer) used to color each cell in the heat-map. If color-fn evaluates to a falsey value, that cell will be left blank.
* :cell-text-fn - Function `(cell-text-fn x y)` that returns an optional string to render for each cell.
* :num-columns - Number of columns to draw.
* :num-rows - Number of rows to draw.
* :box-gap - Number of pixels between boxes on the heat map
* :font - font used to draw optional text in cells
* :cell-text-color - color of text, defaults to black or white depending on the cell color

Returns the modified original canvas.

(plot-line-graph &named canvas width height data to-pixel-space line-style line-style-per-column x-column y-column circle-points point-radius x-colors bar-padding stroke-thickness super-sample color-map transpose)

Plot a line graph or scatter graph on a canvas. This function does not add a set of axis, title, or chart legend, it will only plot the graph lines and points from data.

* :canvas - a gfx2d/image to draw on
* :width - (if no canvas provided) - make a new canvas with the given width in pixels
* :height - (if no canvas provided) - make a new canvas with the given height in pixels
* :to-pixel-space - optional function (f x y) -> [pixel-x pixel-y]. Used to convert the metric space to pixel space when plotting points.
* :data - a data frame to use for x and y data
* :x-column - the name of the data frame column to use for the x axis
* :y-column - a single column name or list of column names to use for the y coordinates and connected lines
* :color-map - a dictionary mapping columns to colors. By default will hash column name to pseudo-random colors
* :line-style - How to draw lines. Can be one of :stroke, :plot, :none, :bar, :area, or :stipple. Default is :plot.
* :line-style-per-column - Optional dictionary to override line style by y-column name.
* :circle-points - add circles around each point
* :point-radius - how large to make the circles around each point in pixels
* :super-sample - use super sampling to draw a larger image and then scale it down for anti-aliasing.
* :bar-padding - space between bars in bar-charts
* :stroke-thickness - thickness in pixels of the stroke of the graph when :line-type = :stroke
* :x-colors - for bar and scatter plots, optionally set per-point/per-bar colors with an function (f x y index) called on each point.
* :transpose - When transpose is enabled, draw bar and area charts from the y-axis instead of the x-axis (make horizontal bar charts). Should be used with a transposed axes.

Returns the modified canvas image.

(plot-packing-chart &named canvas width height data-map data x-column y-column c-column group-column padding inner-padding background-color text-color font color-map omega no-text-resize sort-bins)

Draw a packing chart (a.k.a relative area chart or treemap). Plot boxes for each value who sizes are proportional to the value
they represent. A more versatile and compact alternative to pie charts, especially when there are many categories.
Returns either a new gfx2d/image or the passed-in :canvas.

Basic Parameters:
* :canvas - A gfx2d/image to draw on
* :width - (if no canvas provided) - make a new canvas with the given width in pixels
* :height - (if no canvas provided) - make a new canvas with the given height in pixels
* :color-map - a color map keyword or function used to map numbers in the range [0, 1] to a color.

Data Table Input (quick and easy method):
* :data-map - A table or struct that maps keys as categories to values as proportional rectangle areas.

Data Frame Input:
* :data - a data-frame table that contains a grid of cell
* :x-column - a column name to use the category identifiers. Defaults to the first column.
* :y-column - a column name to use for the area quantities. Defaults to the second column
* :c-column - a column name to use for color grading. Defaults to the same as the y-column, but mapped to a range from 0 to 1, such that
 the minimum value is a color parameter of 0 and the maximum has a color parameter of 1.
* :group-column - a column name that contains a label for grouping areas. Optional.

Layout Parameters:
* :omega - a number between 0 and 1 used to decide how to split rectangular areas. The default is 0.5
* :sort-bins - If true, will sort bins from largest to smallest before layout. This usually results in better-looking charts. Default is true.
  For custom bin ordering before layout, use a data-frame input, set sort-bins to false, and order the rows as desired.

Color and Theme:
* :font - Font to use to draw text inside areas.
* :no-text-resize - By default, text will be scaled to fill the space inside each area. Enabling this option keeps all text the same scale.
* :text-color - Color to draw text inside areas. By default, will choose white or black to maximize contrast.
* :padding - Number of pixels / 2 between areas.
* :inner-padding - Minimum number of pixels between area text and the area border.
* :background-color - Background color of canvas. Use :none to skip drawing a background.

(to-color-map cmap)

Map a keyword, function, array, or dictionary to a function that maps values to colors.