Docs
Methodology

Methodology

The published descriptor, releases and their versioning, model versions and the language of likelihood.

Every number the platform publishes comes from a model of the methodology, applied to data that names its source. The methodology is published as a descriptor generated from the very objects the computation reads, so the description cannot drift from what runs.

The descriptor

GET /methodology returns the release in force:

FieldContent
versionThe methodology release, in semantic versioning
fingerprintsha256: and the digest of the descriptor's canonical JSON
changelogEvery release, newest first, with its date, summary and changes
modelsEach model with its version, steps, parameters (values, units and rationale), references and limitations
indicesThe composite index frameworks

The workbench's Methodology module shows the same descriptor, searchable, with the release history.

Releases

The methodology is versioned independently of the API. A change that alters any published output is a release:

ReleaseWhen
PatchA correction that changes outputs only in edge cases, such as tie-breaking, or a wording that keeps its meaning
MinorA new model, a new parameter or a recalibrated parameter value
MajorA change to what a published quantity means: a scale, a definition or a band threshold

Each model also carries its own version, bumped when its computation changes. A change that alters no output, such as a refactoring, keeps the version.

In every response

Lens-scoped responses state methodology: { version, fingerprint }. Compare the version with the one you stored to know whether a difference between two reads comes from the data or from the method.

Verifying a fingerprint

The fingerprint is sha256: followed by the lowercase hexadecimal SHA-256 of the UTF-8 encoding of the descriptor's canonical JSON, computed without the fingerprint member. Canonical JSON sorts object keys by UTF-16 code unit, omits whitespace and undefined members, keeps array order, and writes strings and numbers as JSON.stringify does.

Verify the methodology fingerprint
function canonicalJson(value: unknown): string {
  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
  if (value !== null && typeof value === "object") {
    const members = Object.entries(value)
      .filter(([, member]) => member !== undefined)
      .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
      .map(
        ([key, member]) => `${JSON.stringify(key)}:${canonicalJson(member)}`,
      );
    return `{${members.join(",")}}`;
  }
  return JSON.stringify(value);
}

const response = await fetch(
  `${process.env.PRAXIS_URL}/api/v1/intelligence/methodology`,
  { headers: { Authorization: `Bearer ${process.env.PRAXIS_TOKEN}` } },
);
const { fingerprint, ...descriptor } = await response.json();
const digest = await crypto.subtle.digest(
  "SHA-256",
  new TextEncoder().encode(canonicalJson(descriptor)),
);
const hex = Array.from(new Uint8Array(digest), (byte) =>
  byte.toString(16).padStart(2, "0"),
).join("");

const verified = fingerprint === `sha256:${hex}`;

The language of likelihood

Every probability is also stated in the expressions of likelihood of Intelligence Community Directive 203. The lower bound is inclusive and the upper bound exclusive.

BandProbability
Almost no chance0 to 0.05
Very unlikely0.05 to 0.20
Unlikely0.20 to 0.45
Roughly even chance0.45 to 0.55
Likely0.55 to 0.80
Very likely0.80 to 0.95
Almost certain0.95 to 1

Index classes

Indices on 0 to 10, the country risk index and maritime stress, are classed with the risk classes of the INFORM Risk Index:

ClassScore
Very low0 to 2
Low2 to 3.5
Medium3.5 to 5
High5 to 6.5
Very high6.5 to 10

A number printed beside its class never rounds into another class.