education.weighted-grade

export function weightedGrade(components: readonly GradeComponent[], decimals: number, mode: RoundingMode): WeightedGrade

/** One assessed component: a mark out of a total, and its share of the final grade. */
export interface GradeComponent {
  /** a label for the caller; not used in the sum */
  readonly name: string;
  /** 0 to outOf */
  readonly mark: number;
  /** the component's total, 1 or more */
  readonly outOf: number;
  /** share of the final grade: 4000 = 40% */
  readonly weightBasisPoints: number;
}

/** The weighted percentage, exact and rounded. */
export interface WeightedGrade {
  /** the exact weighted percentage, reduced */
  readonly percent: Rational;
  /** percent rounded to decimals places, times 10^decimals: 74.3% at 1 place is 743 */
  readonly scaled: number;
  readonly decimals: number;
}

import { weightedGrade } from "#fune/education.weighted-grade@^1";

import { type Rational, addRational, multiplyRational, rational, rationalToInteger } from "./math_rational.ts";  ← from math.rational ^1.0.0 · built alongside by fune
import { type RoundingMode } from "./math_round_div.ts";  ← from math.round-div ^1.0.0 · built alongside by fune
import { type GradeComponent, type WeightedGrade } from "./education_weighted_grade_types.ts";

/**
 * Weighted percentage across components, summed exactly and rounded once.
 *
 * Each component adds mark x weight / (outOf x 100) percent: mark/outOf of the
 * component, times weight/10000 of the whole, times 100 for a percentage.
 */
export function weightedGrade(components: readonly GradeComponent[], decimals: number, mode: RoundingMode): WeightedGrade {
  if (components.length === 0) {
    throw new RangeError("components must not be empty");
  }
  if (!Number.isInteger(decimals) || decimals < 0 || decimals > 6) {
    throw new RangeError(`decimals must be a whole number from 0 to 6, received ${decimals}`);
  }
  let total: Rational = rational(0, 1);
  let weights = 0;
  for (const c of components) {
    if (!Number.isInteger(c.outOf) || c.outOf < 1) {
      throw new RangeError(`outOf must be a whole number of 1 or more, received ${c.outOf} for ${c.name}`);
    }
    if (!Number.isInteger(c.mark) || c.mark < 0 || c.mark > c.outOf) {
      throw new RangeError(`mark must be a whole number from 0 to outOf (${c.outOf}), received ${c.mark} for ${c.name}`);
    }
    if (!Number.isInteger(c.weightBasisPoints) || c.weightBasisPoints < 0) {
      throw new RangeError(`weightBasisPoints must be a whole number of 0 or more, received ${c.weightBasisPoints} for ${c.name}`);
    }
    weights += c.weightBasisPoints;
    total = addRational(total, rational(c.mark * c.weightBasisPoints, c.outOf * 100));
  }
  if (weights !== 10000) {
    throw new RangeError(`weights must add up to 10000 basis points (100%), received ${weights}`);
  }
  const scaled = rationalToInteger(multiplyRational(total, rational(10 ** decimals, 1)), mode);
  return { percent: total, scaled, decimals };
}

Install

fune build

With that line in your source, in a TypeScript project (language typescript in fune.project), fune build resolves it and its 2 dependencies, pins them in fune.lock, downloads only the TypeScript package of each, and builds the code above into your project’s .fune/build, one readable file per capability with a header linking back here. Or pin a range in fune.project and build in one step:

fune add education.weighted-grade

The manifest, vectors and README with only the TypeScript implementation. Install it without the registry with fune add ./education.weighted-grade-1.0.0-typescript.fune, or fetch it from a terminal with fune pull education.weighted-grade@1.0.0:typescript.

The whole function, every language, is one file too: education.weighted-grade-1.0.0.fune, 21,780 bytes, sha256 00502fea3ca0bb6ac3d075fe288927fcfb06d8b723174710e715fd67fa3a8596. It installs into a project of any language.

// fune: before education.weighted-grade

// fune: after education.weighted-grade

// fune: replace math.rational in education.weighted-grade
// fune: replace math.round-div in education.weighted-grade

// fune: step education.weighted-grade after <n|label>

More from the author

Component percentages are usually repeating decimals (45 out of 60 is fine; 88 out of 120 is 73.333...). Adding them as floats can land a hair under a .5 and round the wrong way: 10/30 at 50% plus 29/300 at 50% is exactly 21.5, which floats compute as 21.4999999..., so a half-up round to whole marks gives 21 instead of 22. A vector pins that case. Rounding each component before adding is a second, commoner source of drift and is not done here.

## Decisions

- **Weights are basis points and must total 10000.** A table that adds up to 99.99% is almost always a typo, so it is refused rather than normalised. Equal thirds are 3333, 3333, 3334: say which component carries the extra basis point. - A weight of 0 is allowed (a formative piece recorded alongside), and adds nothing. - `scaled` is an integer so no float ever carries the answer: 74.3% at one decimal place is `743`. Grade the student with `education.grade-boundaries` on the scaled value if your boundaries are in percent. - Components not yet sat, capped resits and compensation rules are the institution's regulations and are out of scope: pass only marks that count.

## Errors

An empty list, a mark outside 0 to `outOf`, `outOf` below 1, a negative weight, weights not totalling 10000, `decimals` outside 0 to 6, or an unknown rounding mode all raise.

Files