Skip to content

dist #

vsl.dist

vsl.dist provides histogram binning, density estimates, and text rendering for numeric samples. Histogram stores finite, strictly increasing bin boundaries and counts. Bins are left-closed and right-open, except the last bin includes its right boundary, matching NumPy histogram edge semantics.

API Purpose
Histogram.new(stations) Create a histogram from bin boundaries.
find_bin(x) Return the matching bin index, -1 when outside the range, or an error for invalid edges/NaN.
count(values, clear) Count values, optionally resetting prior counts first.
count_with_policy(values, clear, policy) Count finite values using stats.NonFinitePolicy; return the sample count for density normalization.
gen_labels(format) Format the bins as display labels.
density(nsamples) Estimate per-bin density using each bin's width and the total sample count.
density_area(nsamples) Integrate the density estimate across all bins.
text_hist(labels, counts, barlen) Render labeled counts as a text chart.
build_text_hist(...) Build a histogram and render it in one call.
import vsl.dist

mut histogram := dist.Histogram.new([0.0, 1.0, 2.0, 3.0])
histogram.count([0.2, 0.7, 1.4, 2.8], true)!
labels := histogram.gen_labels('%g')!
println(dist.text_hist(labels, histogram.counts, 0)!)
println(histogram.density(4)!)

For non-uniform bins, each density is count / (sample_count * bin_width). Values outside the bin range still contribute to sample_count; therefore density_area is the fraction of samples that fell within the histogram range. count_with_policy returns the number of finite observations, including those outside the bin range; pass that count to density when using .omit. It keeps existing counts unchanged on rejected inputs. Its .propagate mode returns an error when a non-finite value appears because integer bin counts cannot represent propagated NaN. Weighted histogram counts and automatic bin selection expose matching *_with_policy variants; omitted weighted pairs do not contribute to bins or the returned normalization weight. The legacy unweighted Histogram.count rejects NaN but treats infinities as out-of-range observations. Legacy weighted histogram counting rejects all non-finite values and weights; automatic bin selection rejects non-finite samples.

See the histogram example and hist.v for formatting and boundary behavior.

fn build_text_hist #

fn build_text_hist(xmin f64, xmax f64, nstations int, values []f64, numfmt string, barlen int) !string

build_text_hist builds a text histogram

fn histogram_bin_edges #

fn histogram_bin_edges(values []f64, rule HistogramBinRule) ![]f64

histogram_bin_edges returns equal-width edges selected from the finite sample. Constant samples use one bin spanning value +/- 0.5.

fn histogram_bin_edges_in_range #

fn histogram_bin_edges_in_range(values []f64, rule HistogramBinRule, lower f64, upper f64) ![]f64

histogram_bin_edges_in_range selects edges over an explicit finite interval. Only observations inside the closed interval influence the bin rule. Samples outside it do not contribute; an interval containing no observations errors.

fn histogram_bin_edges_in_range_with_policy #

fn histogram_bin_edges_in_range_with_policy(values []f64, rule HistogramBinRule, lower f64, upper f64, policy stats.NonFinitePolicy) ![]f64

histogram_bin_edges_in_range_with_policy applies a non-finite sample policy before selecting edges inside the explicit interval.

fn histogram_bin_edges_with_policy #

fn histogram_bin_edges_with_policy(values []f64, rule HistogramBinRule, policy stats.NonFinitePolicy) ![]f64

histogram_bin_edges_with_policy selects edges after applying a non-finite sample policy. Propagation is undefined for bin-edge selection and errors when any sample is non-finite.

fn text_hist #

fn text_hist(labels []string, counts []int, barlen int) !string

text_hist prints a text histogram

fn Histogram.new #

fn Histogram.new(stations []f64) &Histogram

Histogram.new returns an histogram struct from a given list of stations

fn HistogramBinRule.from #

fn HistogramBinRule.from[W](input W) !HistogramBinRule

from returns the HistogramBinRule value of an integer or of a field name, or an error if there is none.

fn WeightedHistogram.new #

fn WeightedHistogram.new(stations []f64) &WeightedHistogram

WeightedHistogram.new creates weighted bins using the same edge convention as Histogram: left-closed bins, with the final right edge included.

enum HistogramBinRule #

enum HistogramBinRule {
	auto
	fd
	doane
	scott
	stone
	rice
	sturges
	sqrt
}

HistogramBinRule selects a NumPy-compatible automatic bin-width estimator.

struct Histogram #

struct Histogram {
pub mut:
	stations []f64 // stations
	counts   []int // counts
}

Histogram defines a public data structure for this module.

fn (Histogram) find_bin #

fn (o Histogram) find_bin(x f64) !int

find_bin finds where x falls in returns -1 if x is outside the range

fn (Histogram) count #

fn (mut o Histogram) count(vals []f64, clear bool) !

count counts how many items fall within each bin

fn (Histogram) count_with_policy #

fn (mut o Histogram) count_with_policy(vals []f64, clear bool, policy stats.NonFinitePolicy) !int

count_with_policy counts finite observations according to the selected policy. Propagation is undefined for integer bin counts, so it returns an error if any non-finite observation is present.

fn (Histogram) gen_labels #

fn (o Histogram) gen_labels(numfmt string) ![]string

gen_labels generate nice labels identifying bins

fn (Histogram) density #

fn (o Histogram) density(nsamples int) ![]f64

density returns per-bin probability densities using each bin's actual width. nsamples is the total number of observations, including those outside the histogram range; therefore the integrated density is the in-range fraction.

fn (Histogram) density_area #

fn (o Histogram) density_area(nsamples int) !f64

density_area integrates per-bin densities over the histogram range.

struct WeightedHistogram #

struct WeightedHistogram {
pub mut:
	stations []f64 // bin edges
	counts   []f64 // accumulated weight per bin
}

WeightedHistogram accumulates non-negative observation weights in fixed bins.

fn (WeightedHistogram) count #

fn (mut o WeightedHistogram) count(values []f64, weights []f64, clear bool) !f64

count adds each sample's non-negative weight to its bin and returns the total weight from this call, including observations outside the range. clear controls whether previous bin weights are retained. When accumulating calls with clear: false, sum their returned weights for density normalization.

fn (WeightedHistogram) count_with_policy #

fn (mut o WeightedHistogram) count_with_policy(values []f64, weights []f64, clear bool, policy stats.NonFinitePolicy) !f64

count_with_policy accumulates finite value/weight pairs. Under omit, pairs with a non-finite value or weight are excluded from both bins and the returned normalization weight. Propagation is undefined for histogram counts and returns an error when any pair is non-finite.

fn (WeightedHistogram) density #

fn (o WeightedHistogram) density(total_weight f64) ![]f64

density returns each bin's accumulated weight fraction divided by its width. total_weight includes observations outside the range, so the integrated density is the fraction of total weight that fell inside the histogram.

fn (WeightedHistogram) density_area #

fn (o WeightedHistogram) density_area(total_weight f64) !f64

density_area integrates densities over the configured range.