fit

The least-squares polynomial through the readings of one scatter; in space, the regression surface.

fitNode
Only withxyxyzplane
On this page
Seven grey readings that rise, dip and rise again, with a teal cubic fitted through them.Seven grey readings that rise, dip and rise again, with a teal cubic fitted through them.

#The readings a fit is taken through

A fit is the least-squares polynomial through the readings of one scatter, named in of: by its id: fit(of: #readings), or in the head, fit:#readings(). The scatter must be in the same graph:

graph{
    fit(of: #elsewhere)
    scatter#readings(x: 1, 2, 3, 4; y: 2.0, 2.4, 3.1, 4.8)
}
graph{
    scatter#elsewhere(x: 1, 2, 3, 4; y: 1.8, 2.9, 3.3, 4.1)
}

[canvas/fit-target-unknown]'fit(of: #elsewhere)' does not match any scatter in this graph — a fit is taken through one named mark, so give the scatter that id ('scatter#elsewhere')

Because a fit takes one named sample, a graph can carry two: the whole sample, and the sample without the reading in question, each its own scatter, each fit publishing its own numbers. Fitting part of a sample is done the same way. The line is drawn across the graph's whole x window, broken where it leaves the y window. A fit is refused on an axis ruled in names (canvas/categorical-mark).

Five grey points, the last an outlier at (5, 14.0), with a grey line fitted to all five and a blue line fitted to the first four.Five grey points, the last an outlier at (5, 14.0), with a grey line fitted to all five and a blue line fitted to the first four.
graph{

    fit#with-outlier(of: #all; degree: 1; colour: grey)
    fit#without(of: #typical; degree: 1; colour: blue)
    scatter#all(x: 1, 2, 3, 4, 5; y: 2.1, 3.9, 6.2, 7.8, 14.0; colour: grey)
    scatter#typical(x: 1, 2, 3, 4; y: 2.1, 3.9, 6.2, 7.8; colour: blue)
}

#Degree and model

degree is the polynomial's degree, rounded to a whole number and at most one less than the number of readings; degree: 0 is a level line at the mean. model: linear fits a straight line whatever degree says. A parameter in degree puts it in the reader's hands:

graph{
    selector:d(name: degree; options: 1, 2, 3, 4)
    fit(of: #readings; degree: d)
    scatter#readings(x: 1, 2, 3, 4, 5; y: 2.0, 2.4, 3.1, 4.8, 7.4)
}

#What a fit publishes

A fit publishes slope, its x¹ coefficient; intercept, its value at x = 0; and r2, one minus the residual sum of squares over the total sum of squares of the readings it was taken through. They are the current fit's, under whatever degree a reader has chosen. At degree 1 they are the line's slope and intercept.

It also publishes the readings themselves and how far each lies from the fit. readings is the list of points it was taken through, in data units; fitted is each of those points moved onto the fit; residuals is each reading minus its fitted value, a signed list of numbers. sse is the sum of the squared residuals, rmse the square root of their mean, and max-residual the largest residual ignoring sign. Prose cites them through the fit's id, !value:#trend.sse() or {{round(#trend.rmse, 2)}}; fitted and readings are lists of points a segment draws between. The statistics pack's statistics.residuals draws a segment from each fitted value to its reading.

Warning
Above degree 1, slope is the gradient at x = 0, not an average gradient.
scene{
    Each unit of dose adds {{round(#trend.slope, 2)}} to the response (r² = {{round(#trend.r2, 3)}}).
}[
    graph{
        fit#trend(of: #readings; colour: teal)
        scatter#readings(x: #doses.dose; y: #doses.response; colour: grey)
    }
]

#Fits on log axes

A fit is taken where the axes place the values: on a log axis, on the base-10 logarithm of the values, and on a log2 axis on the base-2 logarithm. On log–log axes a straight fit is a power law y = a·x^b and slope is the exponent b; with only y logarithmic it is an exponential, and slope is the logarithm of the growth factor per unit of x. intercept and r2 are in the same placed units.

#Regression surfaces in space

On graph:xyz a fit of a scatter is the regression surface of z on x and y: a plane at degree 1, a quadratic surface at degree 2 or more. It publishes intercept, r2, readings, fitted, residuals, sse, rmse and max-residual, with fitted each reading moved onto the surface.


#Attributes

ofRequiredImplicit
The scatter to fit, by its id — fit(of: #readings), or in the head, fit:#readings(). It must be a scatter in this graph (canvas/fit-target-unknown). To fit part of a sample, draw that part as its own scatter and name it here.
Also written: through, dataCan be written as shorthand: fit:value
model
polynomial fits the polynomial of degree:; linear fits a straight line whatever degree: says.
polynomiallinear
Defaultpolynomial
degreeAnimatable
The polynomial's degree, rounded to a whole number and at most one less than the number of readings; 0 is a level line at the mean. A parameter puts it in the reader's hands (degree: d with a selector:d or slider:d). In space, 1 or 2.
Default1
colour
Curve colour.
colour-along
Also written: color
Defaultteal
width
Stroke width.
width-along
Default2
style
How the fitted curve is drawn: solid, dashed or dotted. A function of the point it is at, so it may change along the fit: style: x -> (..8: solid; 8..: dashed) dashes it where it runs past the data.
stroke-along
Defaultsolid
hiddenAnimatable
Declared but not drawn. Animatable — hidden: true !cue.to{false}(at: 2) reveals it — and unlike a cue, a hidden element still frames the plot, so the axes do not jump when it appears.
Defaultfalse
lock
Keeps the reader from editing this element on an editable: graph. Nothing at all on a graph that is not editable.
Also written: locked
Defaultfalse
group
The groups this fit belongs to, comma-separated: group: Treated, Projected. It is drawn in the colour of the first group that has one, over its own colour:, and the footer's key names every group. A stroke the graph's key: gives a group does not change it.

#Derived attributes

Computed while the element renders — read one with #id.name in attribute position or {{#id.name}} in prose, never set.

On any plane
interceptDerived
The fit's value at x = 0, in the units the axes place values in.
r2Derived
One minus the residual sum of squares over the total sum of squares of the readings the current fit was taken through.
readingsDerived
The readings the fit was taken through, as points in data units, in the order the scatter gives them.
fittedDerived
Each reading moved onto the fit: the same x (and y, in space), with the fitted value as its last coordinate.
residualsDerived
Each reading less its fitted value, signed, one per reading — positive where the reading is above the fit.
sseDerived
The sum of the squared residuals.
rmseDerived
The square root of the mean squared residual, over every reading.
max-residualDerived
The largest residual, ignoring its sign.
Only withxyplane
slopeDerived
The x¹ coefficient of the current fit — at degree 1 the line's slope, above it the gradient at x = 0. On a log axis, in logarithmic units: on log–log axes, the exponent of the power law.

#Allowed in

#Examples

Five readings with a teal polynomial fitted through them, and a fit degree menu beneath the plot set to 1.Five readings with a teal polynomial fitted through them, and a fit degree menu beneath the plot set to 1.
graph{
    selector:d(name: fit degree; options: 1, 2, 3, 4)
    fit(of: #readings; model: polynomial; degree: d; colour: teal)
    scatter#readings(x: 1, 2, 3, 4, 5; y: 2.0, 2.4, 3.1, 4.8, 7.4)
}
Six cell counts roughly doubling each hour, on a logarithmic y axis, with the teal straight line fitted to their logarithms.Six cell counts roughly doubling each hour, on a logarithmic y axis, with the teal straight line fitted to their logarithms.
graph{
    fit(of: #counts; colour: teal)
    scatter#counts(x: 0, 1, 2, 3, 4, 5; y: 100, 210, 380, 820, 1600, 3300; colour: grey)
}(
    y scale: log
    x axis label: hours
    y axis label: cells
)
In space: the regression plane of z on x and y through a cloud of twelve readings, with each reading's residual drawn to the plane.In space: the regression plane of z on x and y through a cloud of twelve readings, with each reading's residual drawn to the plane.
@use:statistics

graph:xyz{
    fit#plane(of: #cloud)
    statistics.residuals(of: #plane)
    scatter#cloud(x: 1, 2, 3, 4, 5, 1, 2, 3, 4, 5, 2, 4; y: 1, 1, 2, 2, 3, 3, 4, 4, 5, 5, 2, 4; z: 3.1, 3.9, 5.4, 6.0, 7.7, 5.2, 6.1, 7.4, 8.3, 9.6, 4.6, 7.0)
}(
    view: (-55, 20)
)

#Writing guidance

Last updated