Result fields

This page lists every field of Result and of the objects it holds, with the type, the meaning and the page that explains the value. It teaches nothing. Start from Metrics to learn how to read a number.

Shapes use these symbols: n_kept for the rows that were finite and used, G for the number of groups in the emitted partition, W for the number of refits, and d for the number of columns. Group ids of the emitted partition run from 0, and -1 marks noise.

Result

recover returns one Result. Its fields cannot be reassigned, but the arrays it holds can still be changed in place.

Field	Type	Meaning	Explained on
labels	int32, (n_kept,)	The emitted partition: one full-data fit of deployed_params, -1 for noise.	How Starfold chains the tools
strengths	float32, (n_kept,)	HDBSCAN within-fit strengths of that fit. They are not probabilities.	HDBSCAN strengths
default_labels	int32, (n_kept,)	One full-data fit of the library defaults, kept as the external comparator.	Default comparison
kept_rows	intp, (n_kept,)	Indices into the input of the rows that were finite and used. X[result.kept_rows] lines up with labels.	Prepare your table for recover
params	Params	The setting the search selected, validated on resample rows.	Optuna: searching the settings
deployed_params	Params	The setting that produced labels: params with min_cluster_size and min_samples rescaled from the resample row count to the full row count. Equal to params when the counts agree.	How Starfold chains the tools
default_params	Params	The library defaults, Params(15, 0.1, 2, 5, 5, "eom").	Default comparison
search	SearchResult	Trial table, candidates, fresh scores and the comparison with the defaults.	see below
worlds	WorldEvidence	Recurrence evidence over the refits.	see below
consensus	ConsensusCheck	The co-association check on the emitted partition.	see below
null	NullEvidence	The calibration test. Before it runs, skipped_reason is "null_not_run".	see below
backends	BackendAgreement or None	CPU against cuML agreement. None unless recover ran with Config(check_backends=True). A standalone compare_backends call returns its own BackendAgreement and leaves result.backends as None.	see below
flags	tuple[str, ...]	The raised flags, in vocabulary order.	Flags
provenance	dict	Engines, versions, configuration, seeds, budgets, fit counts, time per stage, peak memory and the input fingerprint.	see below

Three properties read from the parts: n_groups (number of groups in labels), support (the worlds.support matrix) and unresolved_mass (worlds.unresolved_mass).

SearchResult (result.search)

Field	Type	Meaning	Explained on
selected	Params	The chosen setting (equal to Result.params).	Optuna: searching the settings
trials	tuple[TrialRecord, ...]	Every trial, in trial order.	Score
candidates	tuple[Candidate, ...]	The re-scored configurations, best fresh gap first. Empty in exploration-only mode.	Gap
score_selected, score_default	float	Fresh scores of the selected setting and the defaults.	Default comparison
gap_selected, gap_default	float	Fresh scores minus the mean score on the fresh copies. Equal to the scores when no copy was scored.	Gap
paired_differences	tuple[float, ...]	Selected minus default fresh pair score, one per ordered pair of resamples (6 at n_resamples=3).	Default comparison
beats_default_under_objective	bool	gap_selected > gap_default. It does not test the size of the difference.	Default comparison
selected_is_default	bool	Whether trial 0 won.	Flags
exploration_max	float	Largest score among trials 0 to n_explore. The statistic of the calibration test.	Calibration p-value
stop_reason	str	"patience", "budget" or "exploration_only".	Flags
n_completed, n_pruned, n_completed_after_prune	int	Counts of complete trials, pruned trials, and pruned trials finished at the end.	Configuration fields
n_fits, seconds	int, float	Fits and wall time of the search.	Configuration fields
plan	ResamplePlan	The resample indices and seeds of the main plan.	How Starfold chains the tools

Each TrialRecord holds number, params, state ("complete", "pruned" or "failed"), score (the search gap the sampler maximises, which is raw_score minus null_score, or raw_score alone when no copy was scored; raw_score is the score on your table and null_score the score on the structureless copy), partial_score, stability (the prediction agreement), coverage, modularity, fit_counts (groups per fit), fit_noise (noise share per fit), seconds, error and phase ("default", "exploration", "convergence" or "completion"). See Score, Prediction agreement, Coverage and Modularity.

Each Candidate holds params, trial_number, score (search score), fresh_score, fresh_pair_scores, fit_counts, null_scores and gap.

WorldEvidence (result.worlds)

Field	Type	Meaning	Explained on
world_labels	int16, (W, n_kept)	Per refit: -2 not sampled, -1 noise, otherwise the refit’s cluster id.	Refits: reproducibility, not truth
n_sampled	uint16, (n_kept,)	Refits that sampled each row.	Support and own support
support	float32, (n_kept, G)	Recurrence support of each row for each group. NaN where no refit sampled the row.	Support and own support
unresolved	float32, (n_kept,)	Mass a row put on noise. support.sum(1) + unresolved is 1 on every sampled row.	Unresolved mass
own_support	float32, (n_kept,)	support[i, labels[i]], NaN for noise rows.	Support and own support
unresolved_mass	float	Mean of unresolved over sampled rows.	Unresolved mass
group_recurrence	float32, (G,)	Mean over refits of the best Jaccard match of each group.	Group recurrence
group_recurrence_band	float32, (G, 2)	5th and 95th percentiles of the per-refit Jaccard match.	Group recurrence
count_values	int16, (W,)	Number of clusters in each refit.	Count interval
count_interval	tuple[int, int]	Floor of the 5th and ceiling of the 95th percentile of count_values.	Count interval
count_reference	int	Number of groups in labels.	Count interval
property_median	float64, (G, d)	Median over refits of the per-column median of the matched refit cluster, in original units.	Group properties and their bands
property_band	float64, (G, d, 2)	5th and 95th percentiles of the same per-refit medians.	Group properties and their bands
property_propagated	bool	Whether refits carried measurement draws.	Pass measurement errors to recover
world_agreement	float32, (W,)	Per refit, the refit agreement: adjusted Rand index (floored at 0) times joint coverage against the emitted partition.	refit agreement
world_seeds	tuple[int, ...]	UMAP seed of each refit.	Reproduce a run
world_errors	tuple[str, ...]	Exception text of each refit whose fit raised, empty string otherwise.	Flags
n_fits, seconds	int, float	Refit fits attempted and wall time.	Configuration fields

ConsensusCheck (result.consensus)

Field	Type	Meaning	Explained on
labels	int32	Consensus partition over rows, -1 for noise.	Co-association, contrast and the consensus check
rows	intp	Sorted row indices the check used.	Co-association, contrast and the consensus check
agreement	float	The consensus agreement: adjusted Rand index (floored at 0) times joint coverage between labels and the emitted partition on rows.	Co-association, contrast and the consensus check
subsampled	bool	Whether the byte budget forced a seeded subset.	Co-association, contrast and the consensus check
n_rows, bytes_used	int	Rows used and 16 * n_rows**2.	Configuration fields
within_association, between_association	float	Mean co-association of pairs in the same group and in different groups.	Co-association, contrast and the consensus check
contrast	float	within_association - between_association. NaN when the cut is skipped.	Co-association, contrast and the consensus check

NullEvidence (result.null)

Field	Type	Meaning	Explained on
families	tuple[str, ...]	Families run, in order.	Calibration p-value
statistic_name	str	"exploration_design_max" or "full_search_max".	Calibration p-value
observed	float	The statistic on your table. For "exploration" it is the largest search gap among trials 0 to 16 at the defaults. For "full_search" it is the selected setting’s fresh score.	Calibration p-value
values	tuple[tuple[float, ...], ...]	The statistic on each copy, per family.	Calibration p-value
n_realisations, exceedances	tuple[int, ...]	Copies drawn, and copies at or above observed, per family.	Calibration p-value
p_values	tuple[float, ...]	(exceedances + 1) / (n_realisations + 1) per family.	Calibration p-value
p_intervals	tuple[tuple[float, float], ...]	Nominal 95 percent Clopper-Pearson interval on the exceedance share. It describes Monte Carlo precision only.	Calibration p-value
p_value	float	The largest p_values entry. 1.0 when skipped.	Calibration p-value
alpha	float	The declared level.	Calibration p-value
structure_supported	bool	p_value <= alpha.	Calibration p-value
stopped_early	tuple[bool, ...]	Whether the stopping rule ended a family before n_null_max.	Calibration p-value
skipped_reason	str or None	"null_not_run", "observed_statistic_zero" or None.	Flags
n_fits, seconds	int, float	Fits and wall time of the stage.	Configuration fields

BackendAgreement (result.backends)

Field	Type	Meaning	Explained on
agreement, mean_agreement	tuple[float, ...], float	The backend agreement, per seed and mean: adjusted Rand index times joint coverage between the CPU and cuML fits.	Compare the CPU and cuML partitions
ari, coverage	tuple[float, ...]	The two factors of agreement, per seed.	Compare the CPU and cuML partitions
assigned_cpu, assigned_cuml	tuple[float, ...]	Share of rows each backend put in a group, per seed.	Compare the CPU and cuML partitions
normalised, mean_normalised	tuple[float, ...], float	agreement divided by the smaller assigned share. mean_normalised is what backend_disagreement reads.	Compare the CPU and cuML partitions
n_groups_cpu, n_groups_cuml	tuple[int, ...]	Group count per seed on each backend.	Compare the CPU and cuML partitions

provenance keys

result.provenance is a dictionary with these keys. In memory, peak_rss_mb is NaN when the platform does not report it. save writes a non-finite float as JSON null.

Key	Holds
starfold_version, python, platform	Versions and operating system.
libraries	Installed versions of numpy, scipy, scikit-learn, umap-learn, hdbscan, optuna, joblib and cuml, or "absent".
engine_requested, engine_resolved	The engine you asked for and the one used.
n_jobs, n_jobs_forced_to_one_on_cuml	Worker processes used and whether cuML forced 1.
random_state	The base seed.
config	The full Config, with Space, as nested JSON.
n_input_rows, n_kept_rows, n_features	Rows given, rows kept and columns.
input_fingerprint	SHA-256 of the kept matrix as C-ordered float64 bytes plus its shape.
measurement	The measurement model of the refits. {"kind": "none"} without measurement errors. {"kind": "x_err", "x_err_fingerprint": ...} with X_err, where the fingerprint is the SHA-256 of the kept rows of X_err. {"kind": "sampler", "sampler": "module.qualname", "repr": ...} with measurement_sampler; the repr shows bound arguments of a functools.partial, but not state hidden in a closure.
stage_seconds, stage_fits, total_fits	Wall time per stage (search, reference, worlds, consensus, null, backends, total), fits per stage (the same names except consensus and total) and the fit total.
peak_rss_mb	Peak resident memory of the process in MB, NaN where unknown (saved as null).

Reproduce a run shows how to use these keys.