Skip to content
priorityx docs — menu
On this page

Saving results and output names

Explicit paths

The plotting API displays figures by default; it writes files only when an explicit path or a legacy save flag is supplied. Prefer plot_path / csv_path:

from pathlib import Path
import priorityx as px

plot_dir = Path("workspace/plots")
fig = px.plot_priority_matrix(
    results,
    entity_name="Service",
    plot_path=plot_dir / "matrix.png",
    csv_path=Path("workspace/tables/matrix.csv"),
)

Each path enables that output and takes precedence over its corresponding legacy save flag, directory and filename. Parent directories are created. Supplying a legacy directory or filename alone does not enable saving. close_fig=True closes a figure after rendering; it is independent of saving.

The original plot helpers write PNG image content, including when an explicit path has a different suffix. Use a .png path with those helpers. For another Matplotlib-supported format, omit plot_path and call fig.savefig("matrix.svg") on the returned figure. AutoViz’s separate print renderer supports PNG and SVG; see exports.

Save full analytical tables

Keep complete analysis outputs separately from plot-selected exports:

matrix.to_csv("priority_matrix.csv", index=False)
movement.to_csv("movement.csv", index=False)
transitions.to_csv("transitions.csv", index=False)

Use the actual variable name for your fitted matrix (results in the example above). DataFrame to_csv() needs its parent directory to exist. The plotting functions handle their own output directories.

ExportContents
Matrix plot csv_pathCore matrix columns plus explicitly mapped X/Y columns; other enrichment columns are omitted
Timeline plot csv_pathFiltered/selected displayed transitions, with display helper columns
Trajectory plot csv_pathSelected entities and retained path periods, after plot filters
Direct movement.to_csv()Full movement table supplied by analysis

Do not overwrite the full movement CSV with a trajectory plot’s selected subset. AutoViz needs the saved-result schema, full movement history for event classes, and explicit source/coverage metadata. If extraction returns an empty transition table without headers, assign the required empty schema as shown in the quickstart.

Legacy automatic names

The following applies only when save_plot=True / save_csv=True is used without an explicit output path. Defaults are results/plot and results/csv, relative to the current working directory. The workstation’s current date supplies the filename date; it is not the data coverage date.

HelperPNG prefixCSV prefix
plot_priority_matrix()priority_matrixpriority_matrix
plot_transition_timeline()transition_timelinetransitions
plot_entity_trajectories()trajectoriestrajectories

Names use <prefix>-<entity_slug>-<cadence>-<YYYYMMDD>.<extension>. Timeline/trajectory entity_slug is entity_name.lower().replace(" ", "_"). The original matrix helper uses entity_name.lower() and keeps spaces. Cadence suffixes are Q (Quarterly), M (Monthly), S (Semiannual) and Y (Yearly). The cadence argument controls filename suffixes; it does not resample supplied tables.

results/plot/transition_timeline-service-Q-20251018.png
results/csv/transitions-service-Q-20251018.csv
results/csv/trajectories-service-M-20251018.csv

CSV helpers and movement reuse

priorityx.utils.helpers.save_dataframe_to_csv() saves the supplied table using the same naming convention. generate_output_path() constructs that path and creates the directory; it returns a relative path when output_dir is relative. These helpers’ output_dir arguments remain supported. An optional key replaces the date with a 16-character lowercase hexadecimal fingerprint; keyed saves use an atomic replacement. latest_artifact_csv() without a key searches date-only names; with a key, it finds only that exact request and never falls back to a different key or dated file.

load_or_track_movement() uses keyed filenames:

movement-service-Q-a8f3c2d194e76b02.csv

The key reflects the complete supplied DataFrame (including index, column names, dtypes and order), identity/date mappings, normalized schedule, thresholds, priors, inactivity window, effective seed and package/cache version. These are illustrative keys, not data coverage dates. Apply data filters before calling; changes to unused columns also invalidate the cache conservatively.

RequestBehavior
Same data and settingsReuse the exact CSV; no fitting or rewriting
Changed data or settingsCompute a separate keyed file; preserve other results
use_cache=FalseRecompute and atomically replace only the matching file
Only old date-only CSVs existLeave them untouched and compute a keyed result
Matching keyed CSV is unreadableRaise an error; do not silently refit

Failed fitting or saving leaves previous output intact. No manifest, timestamp or run counter is added to keyed cache names. A readable file’s manually edited values are not detected; these are request fingerprints, not output checksums. The first call after upgrading can refit because old caches cannot establish which inputs produced them.

For Monthly, the wrapper returns canonical quarter in memory and saves month on disk. Cache reads never rewrite a header. This explicit analysis/cache helper has disk effects; opening results in AutoViz does not invoke it.

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