Skip to content

feat: add P2QuantileEstimator, one quantile of a stream in constant memory - #7603

Merged
DenizAltunkapan merged 1 commit into
TheAlgorithms:masterfrom
alxkm:feat/p2-quantile-estimator
Sep 12, 2026
Merged

feat: add P2QuantileEstimator, one quantile of a stream in constant memory#7603
DenizAltunkapan merged 1 commit into
TheAlgorithms:masterfrom
alxkm:feat/p2-quantile-estimator

Conversation

@alxkm

@alxkm alxkm commented Sep 12, 2026

Copy link
Copy Markdown
Member

Adds the P-square algorithm of Jain and Chlamtac, which estimates one quantile of a stream from five numbers and never stores the samples.

An exact quantile needs the whole stream in memory, which is not an option for an unbounded one. P-square keeps five markers instead: the minimum, the quantiles p/2, p and (1 + p)/2, and the maximum. Each marker has a height and a position, that is how many samples are known to sit at or below it. A new sample shifts the positions of the markers it falls below, and every marker is then nudged back towards the position it should occupy, using a piecewise parabolic prediction fitted through its two neighbours. The parabolic step is rejected and replaced by a linear one whenever it would break the ordering of the heights, which is what keeps the estimator stable on sorted or violently jumping input.

The first five samples are stored verbatim, so the answer is exact until the sixth arrives, and min() and max() stay exact for the whole stream. Accuracy is typically a fraction of a percent in rank on stationary data and improves as the stream grows, but there is no bound for adversarial input, and the Javadoc says so rather than implying a guarantee.

add and quantile run in O(1) and the estimator holds five markers regardless of how many samples pass through it. That is the point of it: a p99 latency counter per endpoint costs a fixed 80 bytes or so, where an exact one grows without limit.

P2QuantileEstimatorTest covers 27 cases. Among them: the estimate is exact for the first five samples, a ramp lands exactly on its textbook quantile which pins the marker convention, uniform streams are estimated within a percent of the exact quantile for several probabilities, the tail of an exponential stream is tracked, already sorted input and wildly jumping input both stay sane, estimates of different quantiles of the same stream keep their order, and the extremes are exact.

Checklist

  • I have read CONTRIBUTING.md.
  • This pull request is all my own work -- I have not plagiarized it.
  • All filenames are in PascalCase.
  • All functions and variable names follow Java naming conventions.
  • All new algorithms have a URL in their comments that points to Wikipedia or other similar explanations.
  • All new algorithms include a corresponding test class that validates their functionality.
  • All new code is formatted with clang-format -i --style=file path/to/your/file.java

…emory

The P-square algorithm of Jain and Chlamtac keeps five markers instead of the samples, so a quantile of an unbounded stream costs O(1) time per sample and O(1) memory. Each marker is nudged towards its desired position with a piecewise parabolic prediction, falling back to a linear one whenever the parabola would break the ordering of the heights.

The first five samples are kept verbatim, so the estimate is exact until the sixth arrives, and the minimum and maximum stay exact for the whole stream.

Signed-off-by: alxkm <19151554+alxkm@users.noreply.github.com>
@codecov-commenter

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 98.96907% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 81.11%. Comparing base (a097a28) to head (63e0bed).

Files with missing lines Patch % Lines
...m/thealgorithms/streaming/P2QuantileEstimator.java 98.96% 0 Missing and 1 partial ⚠️
Additional details and impacted files
@@             Coverage Diff              @@
##             master    #7603      +/-   ##
============================================
+ Coverage     81.03%   81.11%   +0.07%     
- Complexity     7766     7816      +50     
============================================
  Files           826      827       +1     
  Lines         24645    24742      +97     
  Branches       4814     4833      +19     
============================================
+ Hits          19972    20070      +98     
  Misses         3907     3907              
+ Partials        766      765       -1     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@DenizAltunkapan
DenizAltunkapan merged commit c99b056 into TheAlgorithms:master Sep 12, 2026
7 checks passed
@alxkm
alxkm deleted the feat/p2-quantile-estimator branch September 12, 2026 13:44
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants