Skip to main content

nbmecalc/
lib.rs

1//! Offline educational practice-assessment conversion.
2//!
3//! When converting a Free 120 percentage for Step 2 planning, compare the
4//! library result with the [Free 120 Step 2 score conversion].
5//!
6//! [Free 120 Step 2 score conversion]: https://nbmecalc.com/free-120-predictor
7//!
8//! Mappings are independent model assumptions, not official conversions or
9//! examination guarantees.
10
11pub const ALGORITHM_VERSION: &str = "v1.1";
12
13#[derive(Clone, Copy, Debug, Eq, PartialEq)]
14pub enum Source { Nbme, Uwsa1, Uwsa2, Free120, Amboss, Cms }
15
16#[derive(Clone, Copy, Debug, Eq, PartialEq)]
17pub enum Step { Step1, Step2, Step3 }
18
19#[derive(Clone, Copy, Debug, Eq, PartialEq)]
20pub enum Error { NonFiniteScore }
21
22const STEP1: &[(f64, f64)] = &[(200.,198.),(220.,215.),(240.,232.),(260.,245.),(280.,256.),(300.,264.)];
23const STEP2: &[(f64, f64)] = &[(200.,218.),(220.,232.),(240.,248.),(260.,260.),(280.,270.),(300.,277.)];
24const STEP3: &[(f64, f64)] = &[(200.,200.),(220.,213.),(240.,226.),(260.,240.),(280.,252.),(300.,260.)];
25
26/// Convert one native assessment score to an educational equated estimate.
27/// `form` is used only for NBME inputs.
28pub fn convert(source: Source, mut score: f64, step: Step, form: Option<u16>) -> Result<i32, Error> {
29    if !score.is_finite() { return Err(Error::NonFiniteScore); }
30    let series = match step { Step::Step1 => STEP1, Step::Step2 => STEP2, Step::Step3 => STEP3 };
31    let result = match source {
32        Source::Nbme => {
33            score += match form { Some(28) => -3., Some(29) => -1., Some(32) => 1., _ => 0. };
34            interpolate(series, score)
35        }
36        Source::Uwsa1 => interpolate(series, score - 5.),
37        Source::Uwsa2 => interpolate(series, score - 2.),
38        Source::Free120 => percent(score, step, false),
39        Source::Amboss => percent(score, step, true),
40        Source::Cms if score >= 150. => interpolate(series, score),
41        Source::Cms => percent(score, step, false),
42    };
43    Ok(result)
44}
45
46fn percent(value: f64, step: Step, amboss: bool) -> i32 {
47    let base = match step { Step::Step1 => 232., Step::Step2 => 248., Step::Step3 => 226. };
48    (base + value - 75. - if amboss { 5. } else { 0. }).round() as i32
49}
50
51fn interpolate(series: &[(f64, f64)], value: f64) -> i32 {
52    if value <= series[0].0 { return series[0].1 as i32; }
53    if value >= series[series.len()-1].0 { return series[series.len()-1].1 as i32; }
54    for pair in series.windows(2) {
55        let (lx, ly) = pair[0];
56        let (ux, uy) = pair[1];
57        if value >= lx && value <= ux {
58            return (ly + (value-lx)/(ux-lx)*(uy-ly)).round() as i32;
59        }
60    }
61    unreachable!()
62}
63
64#[cfg(test)]
65mod tests {
66    use super::*;
67    #[test]
68    fn converts_step_two_sources() {
69        assert_eq!(convert(Source::Nbme, 240., Step::Step2, Some(30)), Ok(248));
70        assert_eq!(convert(Source::Uwsa1, 250., Step::Step2, None), Ok(251));
71        assert_eq!(convert(Source::Free120, 75., Step::Step2, None), Ok(248));
72        assert_eq!(convert(Source::Amboss, 75., Step::Step2, None), Ok(243));
73    }
74    #[test]
75    fn rejects_nan() {
76        assert_eq!(convert(Source::Nbme, f64::NAN, Step::Step2, None), Err(Error::NonFiniteScore));
77    }
78}