{"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":"python","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,"search_vec":"'across':53 'analyz':47 'applic':72 'base':5,16 'c':34 'code':35 'configur':55 'count':52 'data':50 'depend':36 'design':42 'dynam':20,79 'effici':44 'fork':27 'hdr':1,22 'hdrhistogram':29 'hdrpi':6 'high':19,78 'high-dynamic-rang':77 'histogram':2,23,73 'implement':17 'initi':26 'integ':56 'latenc':67,75 'librari':10,40 'make':62 'numpi':4,15,38,76 'numpy-bas':3,14 'particular':64 'perform':70,74 'performance-sensit':69 'precis':61 'provid':12 'py':30 'python':9 'rang':21,57,80 'record':45 'replac':32 'sampl':49 'sensit':71 'specifi':59 'use':65 'valu':51,60","created_at":"2026-04-16T13:51:41.937793+00:00","updated_at":"2026-04-16T13:51:41.937793+00:00","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"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"0.3.3","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/dmand/hdrpy","docs":null,"changelog":null,"pypi":"https://pypi.org/project/hdrpy/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["data","observability"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-06-28","next_check":"2026-07-28","install_tag":null}}