freealg.visualization.hist#

freealg.visualization.hist(array, bins=None, m=8, density=True, support=None, atoms=None, edge_tol=0.001, detect_bins=512, trim_q=0.01, smooth_w=7, merge_gap_bins=2, min_interval_bins=3, atom_exclude_sigma=3.0, return_support=False)#

Histogram (optionally ASH-smoothed) with detected multi-interval support and atom-centered bins.

This function produces histogram for empirical data with three features:

It can perform averaged shift histogram (ASH) to reduce the sensitivity of histogram values to bin selection.
It can detect multi-interval densities (separate bulks) and snap the bin edges to the edges of the density bulks for crisper histograms on the edges and reduce the smoothing artifact at sharp edges.
It ensures the bins on the atoms are centered so the spikes are shown right at the atom location.

Parameters:

arrayarray_like: One-dimensional samples.
binsint, default=None: Number of bins used for the absolutely-continuous (AC) part. Atom bins (if any) are added in addition to these bins. If None, number of bins are automatically detected using auto_bins().
mint, default=8: ASH smoothing parameter. Use m=1 for a plain histogram.
densitybool, default=True: If True, normalize counts by (n * bin_width) per bin.
supportlist of (float, float) or None, default=None: AC support intervals [(a1, b1), …, (ak, bk)]. If None, the AC support is detected from the samples using edge_tol and related parameters.
atomslist of float or None, default=None: Atom locations only. A centered bin is created at each atom location (and atoms strictly inside AC intervals may also be carved into the AC binning).
edge_tolfloat, default=1e-3: Relative threshold for AC support detection, as a fraction of the maximum coarse density.
detect_binsint, default=512: Number of coarse bins used to detect the AC support.
trim_qfloat, default=0.01: Quantile trimming fraction for robust detection range, using [trim_q, 1-trim_q].
smooth_wint, default=7: Moving-average window size (in coarse bins) for detection smoothing.
merge_gap_binsint, default=2: Merge detected intervals if the gap between them is at most this many coarse bins.
min_interval_binsint, default=3: Drop detected intervals shorter than this many coarse bins.
atom_exclude_sigmafloat, default=3.0: When detecting AC support, exclude a neighborhood around each atom location with radius atom_exclude_sigma * (coarse_bin_width).
return_supportbool, default=False: If True, the detected support is also returned.

Returns:

edgesnumpy.ndarray: Bin edges of length (n_bins + 1), suitable for matplotlib stairs.
valsnumpy.ndarray: Bin heights of length n_bins. If density=True, vals integrates to the empirical mass within the plotted bins (up to smoothing/ discretization).
supportnumpy.array: If return_support=True, this array is also returned.