Technical description

1. Purpose: what is measured

LogoStats measures how the Bible is used: which verses, chapters and books are cited in sermons, articles, devotionals, verses of the day and other sources, and which are cited rarely or never. The basic record is the usage occurrence: one identifiable occasion of use, such as one sermon or one day's verse. Each occurrence cites one or more passages, each passage being one reference as the source writes it (it may be non-contiguous). Counting turns every passage into contributions to single verse units.

Four kinds of measurement are kept apart and are never added together: usage, prescribed readings (lectionaries), aggregate tallies published by third parties, and private reading (never public).

Sources: architecture/70-observations.md §2, §3.1; architecture/84-counting-definitions.md §1.

2. Data model

Occurrences

An occurrence carries dates by role (occurred, published, recorded, broadcast, accessed, retrieved) with stated precision, the audience as a value or range per kind of measurement, its evidence (source collection, release, document, locator) and three quality axes: evidence basis, verification level and dispute status. Speaker, author, organisation, event, topic, place, language and denomination are resolution slots: the raw value of the source is always kept next to the resolved entity, with a level of specificity (exact, family, broad category, partial record). There is no shared “unknown” placeholder, and a Bible translation is never assumed. Target age, purpose and the role of a passage are recorded separately from the type of use; “not recorded” differs from an investigated “unknown”, and an inferred value needs evidence and a confidence.

Passages, verse units and sequences

A passage is stored as an immutable passage shape: a list of elements with roles (core, optional, alternative, context only). Under a mapping release it resolves to verse units; a unit counts at most once per passage, and a partial verse (such as “8a”) gives partial coverage without creating a new unit. Each unit has a public, citable key of the form nrf1:BOOK.ccc.vvv; positions in a sequence (a canon with an ordering) belong to one deterministic, checksummed build of that sequence.

Sources and claims

A source collection is a dataset with its sampling design and known biases; each collection release is pinned by SHA-256, row count, retrieval date and licence. Collections, publications, documents and organisations are distinct things. Every value keeps its provenance, from the raw row through claims, resolutions, verification events and merges to the audit log. Coverage is explicit (not covered, exhaustive, partial, undeclared), so a missing label is never read as a zero.

Persons and other entities, and their privacy rules

Entities are persons, organisations, denominations (in competing classification systems, without one universal hierarchy), events, places and concepts; relations between them are dated and evaluated as of a date. The rules for persons fail closed:

• speaker, contributor, evidence source and user account are four identities that are never merged;
• data about living persons, and about persons whose living status is unknown, are restricted by default; a name is shown only on a lawful basis such as having been manifestly made public;
• religious affiliation is never inferred from a citation; it is special-category data and public only for deceased persons, with explicit consent or where manifestly made public;
• no personal attribute is published as a dimension of the statistics, and records of living persons count in no public figure unless the person has consented or is cleared under the research protocol;
• reading histories have no public setting; consents are separate, append-only and can be withdrawn at once;
• erasure removes personal data also from the audit trail, and frozen releases record an adjustment instead of being silently changed.

Sources: architecture/70-observations.md §3.2–3.7; 35-passages-sequences-annotation.md §2, §4–5; 40-sources-claims.md §2.1–2.4; 50-entities.md §2, §8; 87-privacy-consent.md §1, §3–4.

3. Versification and mapping releases

Bibles number their verses differently. LogoStats separates the label a source writes (a verse number in some versification) from the neutral unit that is counted. Labels reach units only through sourced mapping assertions (one-to-one, one-to-many, many-to-one, partial, omitted, additional, approximate and others), grouped in mapping sets and compiled into a mapping release. Expert-curated sets take precedence over imported ones. A release moves from draft through review to published, and a published release never changes: a new release supersedes it, and the difference between two releases drives the re-resolution of affected passages. The reference data come from published, cited sources (mainly STEPBible TVTMS and the libpalaso versification files), anchored on BHS for the Hebrew Bible and on NA/UBS for the New Testament. The versification systems and their differences are described on /versification*.

Sources: architecture/30-scripture-reference-mapping.md §2, §7.1–7.5; versification/README.md.

4. Counting rules, metrics and inclusion profiles

The headline metric is verse-level uses, always computed on neutral units: for each unit, the sum over all passages that cover it of repetition × weight. The baseline counting rule CR-BASE counts repetitions each time and counts a chapter or range once for each of its verses (a range of ten verses gives ten verse-level uses and one passage occurrence); optional verses are left out, a partial verse counts one, an unknown repetition counts one and is flagged as a lower bound, and unresolved references count for no unit but are reported. Each variant changes one parameter (for example CR-EXPLICIT-VERSE, the default of the public verse charts, or CR-ONCE-PER-OCCURRENCE). Rules are versioned and never edited in place.

An inclusion profile decides which records count. The public site uses the official profile: approved records only, with a minimum evidence quality (official@2). Further metrics count occurrences, passages, distinct sources and events, audience exposure and sliding windows. The full list, with every rule, metric and profile as stored in the database, is on /methodology*.

Sources: architecture/84-counting-definitions.md §2–7.

5. Statistics epochs and citable data releases

The live statistics change only when a new epoch is published (append-only, with one current epoch); the engine recomputes them regularly. Numbers meant to be cited come from a data release, which freezes the epoch together with the schema migration version, the engine's commit, the mapping release, the PostgreSQL version, a SHA-256 manifest of the exact record versions included, and the archive with its checksum; a release may carry a DOI. A release is built, frozen, then published (or retracted) and archived; later erasures are logged as adjustments. Every result carries a disclosure of the rules, profile and release or epoch it was computed from. The releases are listed on /releases*.

Sources: architecture/90-statistics-public.md §1, §3.2, §3.5, §6.

6. The parallel map

Some verses are identical or very similar to others (parallel accounts, quotations of the Old Testament in the New). The parallel map records this similarity between different places, separately from versification mapping, which records the identity of the same text under different numbering. Links are pairwise between word spans and never transitive; each is classed as identical, near-identical or similar, with a similarity score and a flag for formula-like wording. Sets are built per edition and contain only positions, hashes and scores, never Bible text. When a citation could stand for several parallel places, this is detected and shown, never resolved silently. See /parallels*.

Sources: versification/PARALLEL-MAP-PROPOSAL.md §0–3; versification/parallels/README.md.

7. Import formats and review

Data enter through documented formats, chiefly the Citation CSV (current version 3.2, schema version 5), with Full, Base and Simple templates whose column headers are offered in the interface languages; further formats cover lectionaries, aggregate counts, entities and mappings. Every batch is previewed, decided and committed as a whole and can be rolled back. Review follows one state machine in which nobody approves their own submission; batches are checked by documented random samples (method, seed and strata are recorded), and collected sources need a sign-off by a second person. The sampling rules are set out in the research protocol.

Sources: architecture/60-ingestion-moderation.md §2.3–2.4, §11, §17.13–17.15; app/src/server/import/README.md.

8. Privacy and the research protocol

The research protocol states the research questions, how data are collected, checked and analysed, the limits of the results and the rules for results about persons; in particular, a Bible citation is never taken as evidence of a person's religious affiliation. How personal data are processed is described in the privacy statement.

9. Reproducibility and the repository

Everything that determines a number is versioned and stored: the counting rules, profiles and metrics, the mapping release, the epoch and the code version. A frozen data release, re-run on its recorded versions, gives the same result, and its manifest checksum lets anyone check that the same records were used. The rules live in the database itself (PostgreSQL, with row-level security), and the project is developed in a git repository with automated tests of the database on PostgreSQL 17 and 18, tests of the web application, and an automatic check that keeps copyrighted Bible text out of the project files.

Sources: architecture/90-statistics-public.md §3.2, §3.5; architecture/10-foundation.md §8.

* These pages open when the public statistics are switched on.