> For the complete documentation index, see [llms.txt](https://help.resouris.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.resouris.com/reference/statistical-definitions.md). # Statistical definitions Every figure ReSouris shows is computed, not estimated by eye. This page gives the formal definition of each one, so that a statistician, an auditor or an academic reviewer can check what the product means by a number rather than inferring it from a label. Notation is standard. Where an estimator is **undefined**, that is stated explicitly and the product renders nothing rather than substituting a zero — the distinction between *measured zero* and *not measured* is load-bearing throughout and is the single most common way a workforce statistic misleads. *** ## 1. Equity ### 1.1 Expected contribution For a dimension $d$ (weekends, nights, and so on), a cohort $C$ of staff with contracted hours $h\_i$, and cohort mean count $\mu\_d$: $$ E\_{i,d} ;=; \mu\_d \cdot \frac{h\_i}{\max\_{j \in C} h\_j} $$ Expectation is **pro rata to contracted hours**, normalised against the largest contract in the cohort. A full-time member is expected to carry the cohort mean; a half-time member half of it. $E\_{i,d} = 0$ when $\max\_j h\_j \le 0$. ### 1.2 Deficit $$ D\_{i,d} ;=; E\_{i,d} - c\_{i,d} $$ where $c\_{i,d}$ is the observed count. $D\_{i,d} > 0$ means the member is **behind** their expected share; $D\_{i,d} < 0$ means ahead. The sign is preserved rather than clamped, so over-contribution reduces future priority instead of being discarded. ### 1.3 Standardised position $$ z\_{i,d} ;=; \frac{c\_{i,d} - \mu\_d}{\sigma\_d} $$ $$ z\_{i,d} ;\text{is undefined when}\quad |C| < 3 \quad\text{or}\quad \sigma\_d = 0 $$ ⚠️ **Undefined is recorded as NULL, not as zero.** With fewer than three cohort members $\sigma\_d$ is too noisy to support a "this person is two standard deviations out" claim, and with $\sigma\_d = 0$ the statistic does not exist. A zero here would read as "exactly average", which is a different and false claim. ### 1.4 Slot-level equity term For staff member $i$ and slot $s$, where $\Delta(s)$ is the set of dimensions the slot contributes to, $\mathcal{D}\_i$ the dimensions with counters for $i$, and $X\_i$ the dimensions excluded by an active adjustment: $$ \mathrm{Eq}(i,s) ;=; \sum\_{d ,\in, (\Delta(s) \cap \mathcal{D}*i) \setminus X\_i} D*{i,d} $$ $$ \mathrm{Eq}(i,s) = 0 \quad\text{if}\quad \Delta(s) = \varnothing ;;\text{or};; i \text{ is paused} $$ *** ## 2. Competency value ### 2.1 Urgency For a requirement $r$ with planned completion date $t\_r$, evaluation date $t\_0$, horizon $H = 365$ days, and $\delta\_r = t\_r - t\_0$ in days: $$ u(r) ;=; \begin{cases} 1 & \delta\_r \le 0 \quad \text{(at or past deadline)}\\\[4pt] \dfrac{H - \delta\_r}{H} & 0 < \delta\_r < H\\\[8pt] 0 & \delta\_r \ge H\\\[4pt] 0.5 & t\_r \ \text{undefined (no deadline)} \end{cases} $$ A linear ramp, not a step: a requirement does not become urgent on a single day. ### 2.2 Scarcity For the set $Q(s)$ of skill–level pairs qualifying for slot $s$, and $n\_{k,\ell}$ the number of slots in the horizon requiring pair $(k,\ell)$: $$ \varsigma(s) ;=; \frac{1}{\max\_{(k,\ell) \in Q(s)} n\_{k,\ell}} \qquad \varsigma(s) = 1 \ \text{when the counts are unknown or the maximum is } 0 $$ ⚠️ **The maximum, not the minimum.** A requirement competes against the *most common* matching skill: if a slot can be filled by a common competency, training somebody in a rare one earns little credit from this slot. ### 2.3 Value With base value $b = 1$, summed over that member's incomplete requirements ($\text{completed}\_r < \text{target}\_r$): $$ V(i,s) ;=; \sum\_{r ,\in, R\_i,\ u(r) > 0} b \cdot u(r) \cdot \varsigma(s) $$ The quantity is **dimensionless**; it acquires units only through the policy weight in §4. *** ## 3. Entitlement debt Raw debt is cumulative expected minus credited activity. A carry-over policy of kind $\kappa$ maps raw debt $\rho$ and elapsed periods $p$ to the debt that counts: $$ \mathrm{decay}(\rho, \kappa, p) ;=; \begin{cases} \max(0, \rho) & \kappa = \texttt{rolling}\\\[4pt] \rho & \kappa = \texttt{accumulate}\\\[4pt] \begin{cases} 0 & \rho > 0\ \rho & \rho \le 0\end{cases} & \kappa = \texttt{none}\\\[10pt] \rho \cdot 2^{-p/\lambda} & \kappa = \texttt{half\_life},\ \lambda > 0 \end{cases} $$ $\lambda$ is the half-life in policy periods: after $\lambda$ periods a debt counts half. For slot $s$ with activity $a(s)$: $$ \mathrm{Debt}(i,s) ;=; \sum\_{e ,\in, E\_i,\ a(e) = a(s)} \mathrm{decay}(\rho\_e, \kappa\_e, p\_e) \qquad \mathrm{Debt}(i,s) = 0 \ \text{if } a(s) \ \text{undefined} $$ *** ## 4. The allocation objective The three terms combine into one integer for the constraint solver. With policy weights $w\_t$ and scale $K = 100$: $$ \mathrm{score}(i,s) ;=; \Big\lfloor K \cdot \big( w\_V,V(i,s) + w\_{Eq},\mathrm{Eq}(i,s) + w\_{Debt},\mathrm{Debt}(i,s) \big) \Big\rceil $$ where $\lfloor\cdot\rceil$ is round-half-to-even. The solver maximises the sum of $\mathrm{score}$ over chosen assignments subject to the hard constraints. ⚠️ **All weights default to $0$.** With default policy the objective term is identically zero and allocation is decided by the hard constraints alone. Weights are a published, versioned decision by the organisation — the product ships no opinion about the relative worth of fairness and training. *** ## 5. Utilisation For a period, with $\mathcal{S}$ the set of space half-days the estate opened and $\mathcal{F} \subseteq \mathcal{S}$ those delivered: $$ U ;=; \frac{|\mathcal{F}|}{|\mathcal{S}|} \qquad \text{unused} ;=; |\mathcal{S}| - |\mathcal{F}| $$ ⚠️ **The workforce and estate views of a period share one numerator and one denominator.** "Sessions the department could not staff" and "space half-days unused" are the same quantity $|\mathcal{S}| - |\mathcal{F}|$ described from two sides. They must never be added. *** ## 6. Training impact (the counterfactual) The engine re-plans the department's whole horizon with one additional competency granted, and differences the result. No sampling, no extrapolation from a subset. ### 6.1 Marginal sessions For candidate $c$ (a staff member, a skill, a level), with $\Pi$ the coverage attained under a plan: ⚠️ **The unit of $\Pi$ is the covered position-occurrence** — one position, on one session, on one calendar day — not the session. A service line defines an ordered list of positions, so a session running a two-position service line contributes two occurrences to $\Pi$ and can be partially covered. The product surface labels $S\_{\text{add}}$ "sessions staffed" because that is the operational word; the two coincide only where every service line defines exactly one position. Where they differ, this definition governs. $$ S\_{\text{add}}(c) ;=; \Pi\big(\mathcal{G} \cup {c}\big) - \Pi\big(\mathcal{G}\big) $$ where $\mathcal{G}$ is the currently held set of competencies. This is a **marginal** quantity: it is the effect of granting $c$ **and nothing else**. ⚠️ **Marginal effects are not additive.** For candidates $c\_1 \neq c\_2$, $$ S\_{\text{add}}(c\_1) + S\_{\text{add}}(c\_2) ;\neq; \Pi(\mathcal{G} \cup {c\_1,c\_2}) - \Pi(\mathcal{G}) $$ in general, because two candidates may release the same sessions or need the same contracted hours. The product therefore shows no total row, and a combined figure requires a re-solve after each selection rather than a sum. ### 6.2 Attendances With $\bar{a}$ the department's **measured** mean attendances per delivered session: $$ A\_{\text{add}}(c) ;=; S\_{\text{add}}(c) \cdot \bar{a} \qquad A\_{\text{add}}(c) \ \text{undefined when} \ \bar{a} \ \text{undefined or} \ \bar{a} \le 0 $$ ⚠️ **A department with no recorded attendance has not achieved zero patients per session — it has not measured any.** The estimator is undefined and the figure is withheld; substituting a plausible mean here is the single largest failure mode available to this calculation. ### 6.3 Annualisation Measured over a horizon of $H$ days: $$ \hat{A}(c) ;=; A\_{\text{add}}(c) \cdot \frac{365}{H} $$ ⚠️ **This assumes the measured horizon is representative of the year**, which is a real and unsafe assumption — a July-to-September horizon carries summer leave. The assumption is stated on screen in the confidence note, not buried here, because a reader who knows the department can judge it and nobody can judge what they cannot see. ### 6.4 First-year benefit Training completing in $L$ weeks leaves $52 - L$ weeks to deliver: $$ \varphi(L) ;=; \begin{cases} 1 & L \le 0 \ \text{or undefined}\\\[4pt] \dfrac{52 - L}{52} & 0 < L < 52\\\[8pt] 0 & L \ge 52 \end{cases} \qquad\qquad A^{(1)}(c) ;=; \hat{A}(c) \cdot \varphi(L\_c) $$ ### 6.5 Value for money With one-off cost $\pounds k\_c$: $$ \text{attendances per pound} ;=; \frac{A^{(1)}(c)}{k\_c} \qquad \text{cost per attendance} ;=; \frac{k\_c}{A^{(1)}(c)} $$ Candidates are ranked by attendances per pound, descending. The comparison against bank, waiting-list and agency rates divides the same denominator into a different numerator, so the ratio is like-for-like. ⚠️ **Comparator rates are flagged ASSUMED until an organisation supplies its own.** They are inputs to the comparison, not outputs of the measurement. *** ## 7. Job-plan reconciliation For plan $j$ with planned and delivered programmed activities $P\_j, \Lambda\_j$: $$ v\_j ;=; \frac{\Lambda\_j - P\_j}{P\_j} \qquad\qquad \text{band}(j) = \begin{cases} \text{green} & |v\_j| \le 0.05\\ \text{amber} & 0.05 < |v\_j| \le 0.15\\ \text{red} & |v\_j| > 0.15 \end{cases} $$ The variance is **signed** — over-delivery and under-delivery are different findings — while the band is taken on $|v\_j|$, because a plan 30% over is as much a job-planning failure as one 30% under. Departmental delivery: $$ \text{delivery ratio} ;=; \frac{\sum\_j \Lambda\_j}{\sum\_j P\_j} $$ ⚠️ **Signed, and reported as a distribution rather than a mean.** A department where everyone is 5% under and one where half are 30% over and half 30% under share a delivery ratio and require entirely different conversations. *** ## 8. Attainment For a standard with criteria $\mathcal{K}$, met set $\mathcal{M}$, and level thresholds $T\_\ell \subseteq \mathcal{K}$: $$ \text{level} ;=; \max\Big{, N ;:; \forall, \ell \le N,\ T\_\ell \subseteq \mathcal{M} ,\Big} \qquad (,0 \text{ if } T\_1 \nsubseteq \mathcal{M},) $$ ⚠️ **The quantifier is the whole definition, and it is stricter than it looks.** Attainment is **sequential**: the level is the highest $N$ such that *every* level up to and including $N$ is wholly met. It is **not** $\max{\ell : T\_\ell \subseteq \mathcal{M}}$ — a fully-met level 3 sitting above an unmet level 2 scores 1, not 3. Evaluation stops at the first level that is not wholly met, and also at the first level that defines no criteria. So a level is never a proportion passing a cut-off, and progress cannot be claimed by skipping a level that is hard. $\mathcal{M}$ partitions into **measured** criteria (computed, with the arithmetic shown) and **attested** criteria (asserted by a named person). An attestation may be withdrawn, so $\mathcal{M}$ can shrink and the level can fall. *** ## Assumptions, stated once | | | | ------------------------ | --------------------------------------------------------------------------------------- | | Representative horizon | §6.3 scales a measured period to a year. Seasonal horizons bias this in both directions | | Measured attendance mean | §6.2 is undefined without recorded attendance, and is never imputed | | Marginal, not additive | §6.1 — figures describe one change against the current plan | | Cohort size for $z$ | §1.3 requires $\lvert C\rvert \ge 3$; below that the statistic is withheld | | Comparator rates | §6.5 are organisational inputs, flagged until replaced | | Weights are policy | §4 — the product ships all weights at zero and holds no opinion | *** ## Where these are implemented | Definition | Module | | ------------------- | --------------------------------------------------------------------------------- | | §1 Equity | `application/equity/counter_compute.py`, `application/engine/equity_deficit.py` | | §2 Competency value | `application/engine/competency_value.py` | | §3 Entitlement debt | `application/job_plan/debt.py`, `application/engine/entitlement_debt.py` | | §4 Objective | `application/engine/objective_compose.py`, `application/engine/per_candidate.py` | | §6 Counterfactual | `application/counterfactual/ranking.py`, `application/counterfactual/coverage.py` | --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://help.resouris.com/reference/statistical-definitions.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.