bayesplain.teach.natural_frequencies

bayesplain.teach.natural_frequencies(base_rate, sensitivity, specificity, n=1000, case_label='cases', condition_label='the condition', flag_label='flagged')[source]

Lay out a detection problem as whole counts instead of probabilities.

People are far better at reasoning about “144 of these 312” than about P(A|B), and the two are mathematically identical. This builds the grid of counts so a class can find the answer by dividing one number by another, and only afterwards be told they have just applied Bayes’ rule.

Parameters:
base_rate : float

Share of cases that actually have the condition, in (0, 1).

sensitivity : float

Share of cases with the condition that get flagged, in (0, 1].

specificity : float

Share of cases without the condition that correctly do not get flagged, in (0, 1].

n : int, default 1000

How many cases to imagine. A round number is the point; 1,000 keeps every cell a whole number for most realistic inputs.

case_label : str, default 'cases'

Plural noun for one row of the imagined data, e.g. "permits".

condition_label : str, default 'the condition'

The thing being detected, e.g. "a code violation".

flag_label : str, default 'flagged'

Past-tense verb for what the detector does, e.g. "flagged".

Returns:

Call .summary() to print the grid.

Return type:

NaturalFrequencies

Examples

An inspection-targeting tool that is 90% accurate both ways, looking for a violation that 5% of permits actually have:

>>> import bayesplain as bp
>>> grid = bp.teach.natural_frequencies(
...     base_rate=0.05, sensitivity=0.90, specificity=0.90,
...     n=1000, case_label="permits", condition_label="a violation",
... )
>>> grid.flagged
140
>>> round(grid.posterior_given_flag, 3)
0.321

Ninety percent accurate both ways, and yet only about a third of the permits it flags actually have a violation. Raise the base rate to 16% and the same tool gets it right 63% of the time — the detector did not change, the world did.

Notes

Counts are rounded so that every row and column sums exactly, which means NaturalFrequencies.posterior_given_flag can differ from NaturalFrequencies.bayes_rule_check() in the third decimal place. That discrepancy is worth showing rather than hiding: it is the cost of insisting on whole permits, and it is smaller than any decision would turn on.