Building an uncertainty-aware practice-exam score calculator in Java

A score calculator is easy to write if it returns one number. The harder and
more honest problem is preserving uncertainty, source quality, and timing.

This tutorial uses the open-source nbmecalc-core Java package maintained by
NBMEcalc. It runs
offline, performs no tracking, and treats every mapping as an independent model
assumption rather than an official conversion.

Install the library

<dependency>
  <groupId>io.github.jiankn</groupId>
  <artifactId>nbmecalc-core</artifactId>
  <version>1.0.0</version>
</dependency>

Represent heterogeneous observations

Different assessment families do not share one native scale, so the API keeps
the source explicit:

var exams = List.of(
    PracticeExam.nbme(240, 30, 21),
    PracticeExam.uwsa2(250, 7),
    PracticeExam.free120(76, 2)
);

The optional age enables recency weighting. The NBME form number is optional
because the model only applies a bias when it has an explicit rule for that
form.

Return a range, not false precision

Prediction result = ScorePredictor.predict(exams, StepKind.STEP_2, 10);

System.out.printf(
    "Estimate %d, interval %d-%d, model version %s%n",
    result.pointEstimate(),
    result.ciLower(),
    result.ciUpper(),
    result.algorithmVersion()
);

The model converts each observation, multiplies recency and source-quality
weights, and rounds the weighted mean. Its half-width begins at 16 / sqrt(n)
and is adjusted for low-weight-only inputs and examination horizon.

Persist the algorithm version with any cached result. Otherwise a future model
revision can silently mix incompatible values in the same progress chart.

Validate boundary behavior

Tests should cover more than a happy-path example:

• interpolation at and between anchors;
• clamping beyond the outer anchors;
• source-specific adjustments;
• non-finite scores and negative ages;
• uncertainty widening and probability bounds.

The source repository includes these
tests and generated API documentation. The published package is also available
from Maven Central.
For the user-facing methodology and limitations, see
NBMEcalc.

Responsible use

This is an educational planning example. It is not affiliated with or endorsed
by NBME, FSMB, USMLE, UWorld, AMBOSS, or CMS, and it must not be presented as a
guarantee of an actual examination result.