Documentation
¶
Overview ¶
Package geom provides geometry specifications for the Grammar of Graphics. Geometries define how data is visually represented — as points, lines, bars, areas, etc. Each geom is a pure declarative specification; it holds no rendering logic. The rendering pipeline reads the spec and dispatches drawing operations to the [canvas.Canvas] backend.
Every geom constructor returns a Layer that can be added to a plot:
p := ggplot.New(ds, aes.X("x"), aes.Y("y")).
Layer(geom.Point()).
Layer(geom.Line())
Index ¶
- func RegisterGeomType(t Type, relevantOpts OptFlag)
- type Layer
- func ABLine(opts ...Opt) Layer
- func Area(opts ...Opt) Layer
- func Bar(opts ...Opt) Layer
- func Boxplot(opts ...Opt) Layer
- func Col(opts ...Opt) Layer
- func Density(opts ...Opt) Layer
- func HLine(opts ...Opt) Layer
- func Histogram(opts ...Opt) Layer
- func Line(opts ...Opt) Layer
- func Point(opts ...Opt) Layer
- func Polygon(opts ...Opt) Layer
- func Rug(opts ...Opt) Layer
- func Smooth(opts ...Opt) Layer
- func Step(opts ...Opt) Layer
- func Text(opts ...Opt) Layer
- func VLine(opts ...Opt) Layer
- type Opt
- func WithAlpha(a float64) Opt
- func WithAngle(deg float64) Opt
- func WithBins(n int) Opt
- func WithColor(hex string) Opt
- func WithFill(hex string) Opt
- func WithFontFamily(family string) Opt
- func WithFontSize(size float64) Opt
- func WithGap(g float64) Opt
- func WithIntercept(v float64) Opt
- func WithLabel(name string) Opt
- func WithLineWidth(w float64) Opt
- func WithMethod(m string) Opt
- func WithNotch(enabled bool) Opt
- func WithOrientation(o Orientation) Opt
- func WithPoints(n int) Opt
- func WithPosition(p position.Pos) Opt
- func WithShape(shape string) Opt
- func WithSize(s float64) Opt
- func WithSlope(s float64) Opt
- func WithSpan(s float64) Opt
- func WithStat(name stat.Name) Opt
- func WithWhisker(rule string) Opt
- func WithWidth(w float64) Opt
- type OptFlag
- type Orientation
- type Params
- type Type
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func RegisterGeomType ¶
RegisterGeomType registers a custom geometry type with its relevant option flags. This makes geom.Type open: third-party packages can define new geometry types that participate in option validation via Layer.Validate.
Combined with [ggplot.RegisterDrawer], this enables fully custom geoms:
// In your package init(): const TypeViolin geom.Type = "violin" geom.RegisterGeomType(TypeViolin, geom.OptColor|geom.OptFill|geom.OptAlpha|geom.OptWidth) ggplot.RegisterDrawer(TypeViolin, myViolinDrawer)
Types ¶
type Layer ¶
type Layer struct {
Geom Type // geometry type (point, line, bar, etc.)
StatName stat.Name // stat name (stat.Identity, stat.Bin, stat.Count, etc.)
Position position.Pos // position adjustment
Params Params // visual parameters specific to this geometry
Mapping map[string]string // per-layer aesthetic overrides (channel → column)
// contains filtered or unexported fields
}
Layer represents a declarative layer specification produced by a geom constructor. It carries the geometry type, optional stat/position overrides, per-layer aesthetic mappings, and visual parameters.
func ABLine ¶ added in v0.0.2
ABLine creates a reference line defined by y = slope*x + intercept. Use WithIntercept for the y-intercept and WithSlope for the slope.
Example:
geom.ABLine(geom.WithIntercept(0), geom.WithSlope(1.5), geom.WithColor("#9B59B6"))
Relevant options: WithIntercept, WithSlope, WithColor, WithAlpha, WithLineWidth, WithLabel.
func Area ¶
Area creates a filled area geometry layer.
Relevant options: WithColor, WithFill, WithAlpha, WithLineWidth.
func Bar ¶
Bar creates a bar chart geometry layer. Default stat: count. Default position: stack.
Relevant options: WithColor, WithFill, WithAlpha, WithWidth, WithLineWidth.
func Boxplot ¶
Boxplot creates a box-and-whisker geometry layer. It uses stat "boxplot" which computes the five-number summary (min, Q1, median, Q3, max) for each unique X group.
Relevant options: WithColor, WithFill, WithAlpha, WithWidth, WithLineWidth.
func Col ¶
Col creates a column geometry layer that uses raw Y values (stat: identity). This is equivalent to ggplot2's geom_col(). Use Bar when you want automatic counting/aggregation, and Col when you have pre-computed values.
Default stat: identity. Default position: stack.
Relevant options: WithColor, WithFill, WithAlpha, WithWidth, WithLineWidth.
func Density ¶
Density creates a kernel density estimation geometry layer.
Relevant options: WithColor, WithFill, WithAlpha, WithLineWidth, WithPoints.
func HLine ¶
HLine creates a horizontal reference line at the given Y intercept.
Example:
geom.HLine(geom.WithIntercept(0), geom.WithColor("#CC0000"))
Relevant options: WithIntercept, WithColor, WithAlpha, WithLineWidth, WithLabel.
func Histogram ¶
Histogram creates a binned histogram geometry layer. Default stat: bin. Default position: stack.
Relevant options: WithColor, WithFill, WithAlpha, WithWidth, WithBins, WithLineWidth.
func Line ¶
Line creates a connected line geometry layer.
Relevant options: WithColor, WithAlpha, WithLineWidth, WithSize.
func Point ¶
Point creates a scatter point geometry layer. Default stat: identity. Default position: identity.
Relevant options: WithColor, WithFill, WithAlpha, WithSize, WithShape.
func Polygon ¶
Polygon creates a closed polygon geometry layer.
Relevant options: WithColor, WithFill, WithAlpha, WithLineWidth.
func Rug ¶
Rug creates a rug (marginal tick) geometry layer.
Relevant options: WithColor, WithAlpha, WithLineWidth.
func Smooth ¶
Smooth creates a smoothed trendline geometry layer. Default stat: smooth. Default method: lm.
Relevant options: WithColor, WithAlpha, WithLineWidth, WithSize, WithMethod, WithSpan, WithPoints.
func Step ¶
Step creates a step-function line geometry layer.
Relevant options: WithColor, WithAlpha, WithLineWidth, WithSize.
func Text ¶
Text creates a text label geometry layer.
Relevant options: WithColor, WithAlpha, WithFontSize, WithFontFamily, WithAngle.
func VLine ¶
VLine creates a vertical reference line at the given X intercept.
Example:
geom.VLine(geom.WithIntercept(5), geom.WithColor("#006600"))
Relevant options: WithIntercept, WithColor, WithAlpha, WithLineWidth, WithLabel.
func (*Layer) Validate ¶
Validate checks if the configured params are meaningful for this geometry type and returns a list of warning messages for irrelevant options.
Example:
layer := geom.Point(geom.WithBins(30)) // bins are for histograms, not points warnings := layer.Validate() // warnings = ["geom_point: WithBins has no effect (relevant for: histogram)"]
type Opt ¶
type Opt func(*Layer)
Opt is a functional option for configuring geometry layers.
func WithFontFamily ¶
WithFontFamily sets the text font family.
func WithGap ¶
WithGap sets the gap between bars as a fraction [0, 1]. 0 means bars touch (no gap), 1 means 100% gap (bars invisible). The bar width is derived as 1 - gap. Default gap is 0.2.
func WithIntercept ¶
WithIntercept sets the intercept value for reference lines. For HLine, this is the Y value. For VLine, this is the X value.
func WithLabel ¶
WithLabel sets a legend label for this layer. When used together with WithColor, a legend entry is generated even without aes.Color grouping. This is the idiomatic way to add legends in wide-format multi-layer plots.
func WithNotch ¶
WithNotch enables notched boxplots that show the 95% confidence interval around the median.
func WithOrientation ¶
func WithOrientation(o Orientation) Opt
WithOrientation sets the axis extension direction for directional geoms. Horizontal makes bars grow rightward, boxplots lay sideways, etc.
func WithPosition ¶
WithPosition sets the position adjustment for this layer.
func WithSize ¶
WithSize sets the point radius. Use WithLineWidth for stroke width.
func WithSlope ¶ added in v0.0.2
WithSlope sets the slope for ABLine. The line equation is y = slope*x + intercept.
func WithWhisker ¶
WithWhisker sets the boxplot whisker rule: "tukey" (1.5×IQR, default) or "range" (min-max).
type OptFlag ¶
type OptFlag uint32
OptFlag tracks which parameters were explicitly set by the user. Exported so third-party packages can compose relevance masks for RegisterGeomType.
const ( OptColor OptFlag = 1 << iota // common OptFill // common OptAlpha // common OptLineWidth // common OptSize // point, (also sets LineWidth) OptShape // point OptWidth // bar, histogram OptBins // histogram OptFontSize // text OptFontFamily // text OptAngle // text OptMethod // smooth OptSpan // smooth OptPoints // smooth, density OptWhisker // boxplot OptNotch // boxplot OptOrientation // bar, histogram, boxplot, area, density, rug )
OptColor tracks whether WithColor was set.
type Orientation ¶
type Orientation string
Orientation controls which axis a directional geom extends along.
const ( Vertical Orientation = "v" // default: bars grow upward, boxplots are vertical Horizontal Orientation = "h" // bars grow rightward, boxplots are horizontal )
Vertical is the default orientation: bars grow upward.
type Params ¶
type Params struct {
// Common
Color string // hex color override (e.g., "#4C72B0")
Fill string // hex fill color override
Alpha float64 // opacity [0, 1]
LineWidth float64 // stroke width in pixels
// Point-specific
Size float64 // point radius in pixels (default = 3)
Shape string // "circle", "square", "triangle", "diamond" (default = "circle")
// Bar/Histogram-specific
Width float64 // relative bar width [0, 1] (default = 0.8)
Gap float64 // gap between bars [0, 1] (0 = touching, 1 = invisible; default = 0.2)
Bins int // number of bins (histogram, default = 30)
// Text-specific
FontSize float64 // text font size in points
FontFamily string // font family name
Angle float64 // rotation angle in degrees
// Smooth-specific
Method string // "lm", "loess"
Span float64 // loess span
Points int // number of interpolation points
// Boxplot-specific
Whisker string // whisker rule: "tukey" (default, 1.5×IQR), "range" (min-max)
Notch bool // if true, compute notch confidence interval around median
// Orientation
Orientation Orientation // "v" (default) or "h" — controls axis extension direction
// Legend
Label string // legend label for this layer (used with manual colors)
// Reference lines
Intercept float64 // y-intercept (hline) or x-intercept (vline)
Slope float64 // slope for abline (y = slope*x + intercept)
}
Params holds visual parameters for geometries. Not all fields apply to every geometry type; unused fields are ignored during rendering but Layer.Validate will emit warnings for irrelevant options.
type Type ¶
type Type string
Type identifies the kind of geometry.
const ( TypePoint Type = "point" TypeLine Type = "line" TypeBar Type = "bar" TypeHistogram Type = "histogram" TypeArea Type = "area" TypePolygon Type = "polygon" TypeSmooth Type = "smooth" TypeText Type = "text" TypeBoxPlot Type = "boxplot" TypeErrorBar Type = "errorbar" TypeDensity Type = "density" TypeTile Type = "tile" TypeRug Type = "rug" TypeSegment Type = "segment" TypeStep Type = "step" TypeHLine Type = "hline" TypeVLine Type = "vline" TypeABLine Type = "abline" )
TypePoint identifies a scatter point geometry.
Source Files