{
"title": "hist",
"category": "plotting",
"keywords": [
"hist",
"legacy histogram",
"bin centers",
"distribution plot",
"matlab hist",
"hist vs histogram"
],
"summary": "Create legacy center-based histograms for quick distribution plots and MATLAB `hist` workflows.",
"gpu_support": {
"elementwise": false,
"reduction": false,
"precisions": [
"single",
"double"
],
"broadcasting": "none",
"notes": "`hist` supports GPU-aware histogram computation where applicable, but it remains the legacy center-based histogram workflow rather than the object-based `histogram` API."
},
"fusion": {
"elementwise": false,
"reduction": false,
"max_inputs": 2,
"constants": "inline"
},
"requires_feature": null,
"tested": {
"unit": "builtins::plotting::hist::tests"
},
"description": "`hist` is the legacy histogram builtin that uses MATLAB `hist` semantics. The most important distinction from `histogram` is that when you pass a vector as the second argument, `hist` interprets that vector as bin centers rather than bin edges. In RunMat, `hist` remains useful for center-based legacy workflows, while `histogram` is the newer object-style histogram API with bin-edge semantics and handle-based property workflows.",
"behaviors": [
"`hist(data)` uses a default number of bins based on the input size, following MATLAB-style legacy behavior.",
"`hist(data, v)` interprets `v` as bin centers, not bin edges. This is the key semantic difference from `histogram`.",
"`hist` is a plotting-style histogram command, while `histogram` returns a first-class histogram object handle.",
"Normalization and bin-control workflows are supported, but the builtin should still be documented and used as the legacy center-based histogram path rather than as an alias of `histogram`.",
"GPU-aware computation is used where supported, but semantics stay aligned with legacy MATLAB `hist` behavior."
],
"examples": [
{
"description": "Create a default legacy histogram",
"input": "data = randn(1, 1000);\nhist(data);"
},
{
"description": "Pass explicit bin centers",
"input": "data = randn(1, 500);\ncenters = -3:0.5:3;\nhist(data, centers);",
"output": "% Here the second argument is interpreted as bin centers, not edges"
},
{
"description": "Compare legacy hist semantics with modern histogram intent",
"input": "data = randn(1, 300);\nhist(data, -2:0.5:2);",
"output": "% Use histogram(...) instead when you want bin-edge semantics and an object handle"
}
],
"faqs": [
{
"question": "What's the actual difference between hist and histogram?",
"answer": "The critical difference is how the second argument is interpreted. `hist(data, v)` treats `v` as **bin centers**. `histogram(data, 'BinEdges', v)` treats `v` as **bin edges**. Beyond that, `histogram` returns a handle object with properties you can query via `get`, while `hist` is a fire-and-forget plotting command."
},
{
"question": "When should I use hist instead of histogram?",
"answer": "Use `hist` when you're porting legacy MATLAB code that relies on center-based binning or when you want a quick distribution plot without needing a handle object. For anything new—especially if you need normalization modes, bin-edge control, or programmatic access to bin counts—use `histogram` instead."
}
],
"links": [
{
"label": "histogram",
"url": "./histogram"
},
{
"label": "bar",
"url": "./bar"
},
{
"label": "pie",
"url": "./pie"
},
{
"label": "Choosing the right plot type",
"url": "/docs/plotting/choosing-the-right-plot-type"
},
{
"label": "Styling plots and axes",
"url": "/docs/plotting/styling-plots-and-axes"
},
{
"label": "Plot replay and export",
"url": "/docs/plotting/plot-replay-and-export"
},
{
"label": "Complete plotting guide",
"url": "/blog/matlab-plotting-guide"
}
],
"source": {
"label": "`crates/runmat-runtime/src/builtins/plotting/ops/hist.rs`",
"url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/plotting/ops/hist.rs"
}
}