{"id":7285,"library":"hdrpy","title":"HDR Histogram (Numpy-based)","description":"hdrpy is a Python library that provides a NumPy-based implementation of High Dynamic Range (HDR) histograms. It was initially forked from HDRHistogram_py and replaced its C code dependency with NumPy. This library is designed for efficient recording and analyzing of sampled data value counts across a configurable integer range with specified value precision, making it particularly useful in latency and performance-sensitive applications.","status":"active","version":"0.3.3","language":"en","source_language":"en","source_url":"https://github.com/dmand/hdrpy","tags":["histogram","performance","latency","numpy","high-dynamic-range"],"install":[{"cmd":"pip install hdrpy","lang":"bash","label":"Install with pip"}],"dependencies":[{"reason":"Core dependency for histogram calculations.","package":"numpy","optional":false}],"imports":[{"symbol":"HdrHistogram","correct":"from hdrpy import HdrHistogram"}],"quickstart":{"code":"import random\nfrom hdrpy import HdrHistogram\n\n# Create a histogram that can track values from 1 to 3,600,000,000\n# with 3 significant digits of precision (e.g., 1 microsecond to 1 hour)\nhistogram = HdrHistogram(1, 3600 * 1000 * 1000, 3)\n\n# Record some simulated latency values (in microseconds)\nfor _ in range(100000):\n    latency = random.randint(100, 5000000) # values between 0.1ms and 5s\n    histogram.record_value(latency)\n\n# Record a value with correction for coordinated omission (e.g., expected interval of 10ms)\nhistogram.record_corrected_value(random.randint(100, 5000000), 10000)\n\nprint(f\"Total count: {histogram.get_total_count()}\")\nprint(f\"Mean: {histogram.get_mean()} µs\")\nprint(f\"Standard Deviation: {histogram.get_stddev()} µs\")\nprint(f\"99th Percentile: {histogram.get_value_at_percentile(99.0)} µs\")\nprint(f\"Max Value: {histogram.get_max_value()} µs\")","lang":"python","description":"Initialize an HdrHistogram instance, record values, and retrieve various statistics like mean, standard deviation, and percentiles."},"warnings":[{"fix":"Be aware of potential lack of active maintenance; consider contributions if specific new features or bug fixes are required.","message":"The library's last release was in 2018, indicating a slow development cadence. While stable for its core functionality, new features or rapid bug fixes are unlikely.","severity":"gotcha","affected_versions":"<=0.3.3"},{"fix":"For latency measurements where samples might be omitted due to system overload, use `histogram.record_corrected_value(value, expected_interval)` to accurately reflect the true distribution. The `expected_interval` is the expected sampling interval.","message":"When measuring latency, 'coordinated omission' can lead to inaccurate statistics. Use `record_corrected_value()` to account for dropped or delayed samples that might otherwise skew results.","severity":"gotcha","affected_versions":"All"},{"fix":"Carefully consider the `number_of_significant_value_digits` parameter when initializing `HdrHistogram` to ensure the required resolution for your data, particularly for small values. Higher precision requires more memory.","message":"The precision of the histogram is determined by `number_of_significant_value_digits` during initialization. Choosing too few digits may lead to coarser granularity and loss of detail, especially for values at the lower end of the range.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Ensure you are importing `HdrHistogram` directly from the `hdrpy` package: `from hdrpy import HdrHistogram`.","cause":"The HdrHistogram class might not be directly exposed at the top level of the `hdrpy` package if an incorrect import path is used, or the package structure differs from expectation.","error":"AttributeError: module 'hdrpy' has no attribute 'HdrHistogram'"},{"fix":"Always initialize `HdrHistogram` with its mandatory parameters, for example: `histogram = HdrHistogram(1, 3600000000, 3)` where the arguments specify the range and precision.","cause":"Attempting to instantiate `HdrHistogram` without the required initialization arguments: `lowest_discernible_value`, `highest_trackable_value`, and `number_of_significant_value_digits`.","error":"TypeError: HdrHistogram() takes no arguments"},{"fix":"Ensure that all values you intend to record fall within the `lowest_discernible_value` and `highest_trackable_value` specified when creating the `HdrHistogram` instance. Adjust the histogram's range if necessary to accommodate your data.","cause":"Attempting to record a value using `record_value()` or `record_corrected_value()` that is outside the `lowest_discernible_value` and `highest_trackable_value` range defined during histogram initialization.","error":"ValueError: value out of range"}]}