Skip to content
priorityx docs — menu
On this page

Saved result bundles

priorityx.results provides a small, portable interchange format for the local visualisation application. A ResultDataset identifies one entity type and cadence (monthly or quarterly) and can contain independent matrix, movement and transition tables. A missing table is represented by null; an empty table retains its column schema.

Build and open a bundle

Use your own saved file paths and actual coverage periods:

from priorityx.results import ResultBundle, import_results_csv

dataset = import_results_csv(
    entity_type="entity", cadence="monthly", source_id="saved-results-2026",
    coverage_start="2025-01", as_of="2026-09",
    matrix_path="priority_matrix.csv", movement_path="movement.csv",
    transitions_path="transitions.csv",
)
ResultBundle([dataset]).save("results.json")
bundle = ResultBundle.load("results.json")
python -m priorityx app --bundle results.json

The files are analytical outputs: the matrix from fit_priority_matrix(), movement from track_movement(), and transitions from extract_transitions(). The library returns DataFrames by default. Save the full tables explicitly with matrix.to_csv("priority_matrix.csv", index=False) and the corresponding movement/transition filenames, or pass existing DataFrames directly to import_results_csv(matrix=matrix, movement=movement, transitions=transitions, ...). Do not substitute a plot’s filtered trajectory/timeline CSV for full history.

An empty transition result still needs the required header columns below. If there is no transition table, omit transitions_path; the app will mark the timeline unavailable. Neither case requires inventing events.

Required columns

Each supplied table must contain these columns. A missing table is allowed.

Saved CSV roleIdentity shown and linkedPeriod columnOther required columns
MatrixentityNone; bundle as_of dates the snapshotx_score, y_score, count, quadrant
Movement, Quarterlyentityquarter, e.g. 2025-Q1period_x, period_y, period_quadrant, global_quadrant
Movement, Monthlyentitymonth, e.g. 2025-01; legacy quarter with monthly values is also acceptedSame movement columns
Transitions, Quarterlyentitytransition_quarter, e.g. 2025-Q1from_quadrant, to_quadrant, risk_level
Transitions, Monthlyentitytransition_month or legacy transition_quarter, with YYYY-MM valuesSame transition columns

Use only one accepted period column per table; supplying both aliases is ambiguous and rejected. track_movement() returns its canonical quarter column even for Monthly, while saved monthly tables may use month. extract_transitions() uses transition_quarter for both cadences.

entity must be a nonempty string, identical across tables for the same entity. It is both the chart label and linkage key; an extra name column is retained as metadata but does not replace the displayed identifier. To show names instead of codes, explicitly map every table’s entity to the same unique names before creating the bundle. Preserve the original code in an extra column if needed; do not merge different identities under a duplicate name.

Scores must be finite numbers; count is a non-negative integer. Matrix and movement quadrants are Q1–Q4. Transition from_quadrant uses Q1–Q4; to_quadrant also accepts *X, *Y or *XY suffixes. Supported risk_level values are critical, high, medium, low, stable (case-sensitive). For existing event-class/spike preparation, retain cumulative_count in movement when available; without it event colors use the documented Investigate fallback. Additional known numeric fields include movement’s global_x, global_y, count_total, x_delta, y_delta, period_count, cumulative_count and transitions’ volume_change, growth_change. Optional delta/period-count fields may be empty; required scores and counts may not.

Quarterly periods use exactly YYYY-Q1 through YYYY-Q4, Monthly exactly YYYY-MM. A date such as 2025-03-31 is not a saved period label. Both coverage_start and as_of must use the chosen cadence’s format, in order, and all movement/transition periods must lie within them. When both tables are supplied, each transition must match an existing movement entity/period. Matrix identifiers must be unique, movement entity/period pairs unique, and transition entity/period/from/to combinations unique. Matrix and movement populations may legitimately differ.

Map existing result columns

The importer does not expose entity_col or timestamp_col: it expects the saved schema above. Rename the identifier and period columns explicitly in your adapter. This example starts with already calculated result CSVs, not raw events; score/quadrant columns are retained unchanged:

import pandas as pd
from priorityx.results import ResultBundle, import_results_csv

matrix = pd.read_csv("saved_matrix.csv", dtype={"unit_id": str})
movement = pd.read_csv("saved_movement.csv", dtype={"unit_id": str})
transitions = pd.read_csv("saved_transitions.csv", dtype={"unit_id": str})

matrix = matrix.rename(columns={"unit_id": "entity"})
movement = movement.rename(columns={"unit_id": "entity", "period": "quarter"})
transitions = transitions.rename(
    columns={"unit_id": "entity", "event_period": "transition_quarter"}
)

dataset = import_results_csv(
    entity_type="work_unit", type_label="Work units", cadence="quarterly",
    source_id="saved-analysis", coverage_start="2025-Q1", as_of="2025-Q4",
    matrix=matrix, movement=movement, transitions=transitions,
)
ResultBundle([dataset]).save("results.json")

Here period and event_period already contain YYYY-Qn labels. If your saved result uses dates inside the represented period, convert deliberately, for example pd.to_datetime(movement["quarter"], errors="raise").dt.to_period("Q").astype(str).str.replace("Q", "-Q", regex=False). For Monthly use .dt.to_period("M").astype(str) and the month column. For an exclusive cutoff date, first identify the represented period: 2025-04-01 can mean the end of Q1, even though that date falls in Q2. Convert the represented period end, not the boundary blindly; keep the same interpretation across tables. Check that conversion has not collapsed two saved rows into one entity/period; the validator rejects duplicates. Do not aggregate or change scores to make an import pass. Reading an identifier as a string preserves 001; converting an already parsed integer back to text cannot restore lost leading zeros.

For raw-event analysis, keep your own source headers and pass their names to the existing analysis API:

import pandas as pd
import priorityx as px

events = pd.read_csv("events.csv", dtype={"unit_id": str})
events["observed_at"] = pd.to_datetime(events["observed_at"], errors="raise")
# These run analysis; they are not AutoViz import or layout controls:
# matrix = px.fit_priority_matrix(events, entity_col="unit_id",
#     timestamp_col="observed_at", temporal_granularity="quarterly")
# movement = px.track_movement(events, entity_col="unit_id",
#     timestamp_col="observed_at", temporal_granularity="quarterly")

Validation and provenance

CSV roles are passed explicitly; filenames are never inferred. Identifiers are read as strings (so values such as 001 remain unchanged), while known numeric columns are validated for finite values and non-negative integer counts. Full movement history is retained. The JSON schema is versioned (schema_version: 1) and records table columns plus records, without pickle or serialized Python objects. Recorded source filenames are basenames, not absolute paths. Caller-supplied metadata and extra table columns are retained, so review them before sharing a bundle or offline HTML; arbitrary metadata is not scrubbed.

entity_type and the optional type_label are caller-defined; PriorityX does not reserve domain categories. This importer accepts PriorityX’s generic result columns. Source-specific raw columns and transformations belong in the caller’s adapter before import; no source schema is inferred or built into the package.

Unknown bundle/dataset schema fields and duplicate JSON fields are rejected. Additional CSV table columns are retained as caller metadata; PriorityX does not guess their meaning. The local workspace uses the same import validator.

Optional selections keys control saved display choices: timeline_entities and trajectory_entities are ordered unique identifier lists, timeline_risk_levels filters saved transition risks, timeline_start_period sets an explicit canonical display cutoff, and trajectory_periods selects the recent path window (1–120 periods). These choices never replace the full tables. Timeline classes and suffixes are prepared using full saved movement history.

An explicit trajectory_entities list wins, including its order and an empty list. When it is absent, both renderers select up to three entities with saved points in the recent path window: 12 months or eight quarters by default. Selection ranks the sum of absolute consecutive changes in period_y, descending. Changes are calculated over full saved history before selecting the window, so the change into its first period is included when an earlier point exists. Ties use the exact entity identifier in ascending order; input row order does not decide the selection. A single saved point contributes zero movement. The optional y_delta column is not required, and source tables remain unchanged.

Synced from okkymabruri/priorityx at v0.7.2 on 2026-10-19.