Glossary

This page defines every term that the manual links to from its pages. Each entry gives a plain definition, then one sentence on how Starfold uses the word, with a link to the page that explains it.

adjusted Rand index

A score for how alike two ways of splitting the same rows into groups are, equal to 1 for identical splits and about 0 for random ones, where the group numbers do not matter. Starfold floors it at 0. Prediction agreement is its average over held-out rows and has no coverage factor, because coverage is a separate term of the score. Refit agreement, consensus agreement and agreement with known classes multiply it by coverage (Prediction agreement).

agreement

A word this manual does not use alone. Starfold has four separate agreements: prediction agreement, refit agreement, consensus agreement and agreement with known classes. All four rest on the adjusted Rand index. A fifth, backend agreement, compares CPU and GPU fits. Which one to read depends on your question (Which agreement do I read).

agreement with known classes

The adjusted Rand index, floored at 0, between Starfold’s groups and classes you already know, on the assigned rows, times the share of rows assigned (coverage). It is a post hoc check and never enters the search. Starfold does not print it in result; you compute it (Check a result against known labels).

alpha

The cut-off for the p-value, 0.05 by default. A p-value at or below it counts as support. Starfold sets Config.alpha to 0.05 and raises no_structure_supported when the p-value is above it (Calibration p-value).

alpha elements

Elements built mainly in massive stars that explode as supernovae, such as oxygen, magnesium, silicon and calcium. The ratio [alpha/M] compares their abundance with the Sun’s, relative to the metals as a whole. The disc stars of the APOGEE DR19 example table fall on a high-alpha and a low-alpha sequence at fixed iron content [Fe/H] (Tutorial: two groups in the APOGEE DR19 example table, part 1).

APOGEE

The Apache Point Observatory Galactic Evolution Experiment, an infrared spectroscopic survey of stars of the Milky Way, part of the Sloan Digital Sky Survey. Starfold’s bundled second example, the APOGEE DR19 example table, holds 9,242 stars from its data release 19 (Tutorial: two groups in the APOGEE DR19 example table, part 1).

ASPCAP

The APOGEE Stellar Parameters and Chemical Abundances Pipeline, which fits each star’s spectrum to get its temperature, surface gravity and abundances. The three abundance columns of the APOGEE DR19 example table, [Fe/H], [alpha/M] and [Mg/Fe], come from it (Tutorial: two groups in the APOGEE DR19 example table, part 1).

backend agreement

How well the partition from the CPU fit of one setting matches the partition from the cuML fit, as the adjusted Rand index times coverage per seed, and normalised by the smaller assigned share. Starfold prints it as result.backends when Config(check_backends=True), and raises backend_disagreement below 0.8 (Compare the CPU and cuML partitions).

Clopper-Pearson interval

An exact interval for a share estimated from counted yes-or-no outcomes, built from the binomial distribution, with a stated nominal level such as 95 percent (Clopper and Pearson 1934, doi:10.1093/biomet/26.4.404). Starfold uses it on the share of copies that reach your table, as the Monte Carlo interval (Calibration p-value).

co-association

For a pair of rows, the share of refits that put both in the same group, among the refits that assigned both to a group. Starfold builds a distance from it for the consensus check (Co-association, contrast and the consensus check).

column

One quantity measured for every object in your table, such as a pixel value or an abundance. Starfold puts every column on a common scale with scaling, which does not give each column equal influence, so the columns you choose define what “similar” means (Prepare your table for recover).

community

In a graph, a set of nodes that have more links among themselves than chance would give. Starfold’s modularity asks how well the groups of a fit act as communities of the nearest-neighbour graph of your rows (Modularity).

confidence interval

A range computed by a rule that covers the true value in a stated share of repeated studies. Starfold reports no confidence intervals: its percentile ranges over refits are stability intervals (What Starfold does not claim).

consensus agreement

The adjusted Rand index, floored at 0, between the regrouping of the consensus check and the full-fit labels on the rows it used, times coverage. Starfold prints it as result.consensus.agreement and raises consensus_disagrees below 0.5; it judges the cut, and the contrast needs no cut (Co-association, contrast and the consensus check).

consensus check

A check that turns the share of refits placing two rows together into a distance, regroups the rows from that distance alone, and compares the result with your partition. Starfold runs it on the reference partition, on a recorded subset of rows when the matrix does not fit its memory budget (Co-association, contrast and the consensus check).

contrast

The average co-association of row pairs in the same group minus its average over pairs in different groups. Starfold prints it as result.consensus.contrast; a value near 1 means the refits agree with your partition, and it needs no regrouping (Co-association, contrast and the consensus check).

count interval

The range from the 5th to the 95th percentile of the number of groups found by the refits, widened outwards to whole numbers. Starfold prints it as result.worlds.count_interval and treats it as a stability interval, never as an estimate of how many populations exist (Count interval).

coverage

The share of held-out rows that two fits both place in a group and not in noise. Starfold takes the geometric mean of it with prediction agreement and modularity to form the score, so calling most rows noise does not pay (Coverage).

cuML

The RAPIDS library from NVIDIA that runs UMAP, HDBSCAN and related steps on a GPU with a scikit-learn style interface. Starfold uses it as one engine when it imports with a visible CUDA device (Run Starfold on a GPU).

deployed settings

The setting the search chose, with min_cluster_size and min_samples rescaled from the row count of a resample to the row count of the full table. Starfold stores them as result.deployed_params; they produced result.labels (How Starfold chains the tools).

dex

A unit for a logarithmic quantity, where 1 dex is a factor of 10, that is, a difference of 1 in the base-10 logarithm. Starfold reports group properties in the units of your columns, so the APOGEE abundances appear in dex (Tutorial: two groups in the APOGEE DR19 example table, part 1).

embedding

The low-dimensional map of your table that UMAP produces, in which rows that are similar sit close together. Starfold groups the rows in this map, and its axes carry no units (UMAP: a map of your table).

engine

The software that runs the fits: "cpu" (the reference libraries) or "cuml" (a GPU). Starfold takes engine="auto" by default, which uses cuML when it works and otherwise warns and uses the CPU (Run Starfold on a GPU).

exceedance

A copy whose statistic is at least as high as your table’s, in the calibration test. Starfold counts them as null.exceedances; with h of them among L copies, the p-value is (h + 1) / (L + 1) (Calibration p-value).

flag

A short name for one event or weakness in a run, derived from the evidence arrays so that people and scripts can check it. Starfold lists all 17 in result.flags (Flags).

fresh re-score

A second scoring of the best trials and the defaults on new subsets and new structureless copies. Starfold does it because the best score among many noisy trials is optimistic (the winner’s curse), and it selects the setting with the largest fresh gap (Gap).

full fit

The one fit of the chosen setting on all kept rows. Starfold reports it as result.labels; it is a single transparent fit and not a vote of the refits (How Starfold chains the tools).

Gaia

The European Space Agency mission that measures the positions, distances and motions of over a billion stars. Its third data release is Gaia DR3. The orbital columns of the APOGEE DR19 example table were integrated from Gaia DR3 measurements (Tutorial: two groups in the APOGEE DR19 example table, part 1).

galpy

A Python package for galactic dynamics that integrates orbits of stars in a model of the Milky Way (Bovy 2015, doi:10.1088/0067-0049/216/2/29). The orbital columns of the APOGEE DR19 example table (actions, angular momentum, eccentricity, energy) were computed with it; Starfold itself does not use it (Tutorial: two groups in the APOGEE DR19 example table, part 1).

gap

The score of a setting on your table minus its score on a structureless copy. Starfold maximises it by default, so a setting that scores as well on structureless data gains nothing. With Config(gap_family=None) it maximises the score instead (Gap).

Gaussian copula

A way to draw a random table that keeps every column’s values exactly and couples the columns through one Gaussian dependence. It converts each column to normal scores, fits a shrunk correlation to them, draws from a multivariate normal with it and reorders the values to match. The copy’s correlations come close to the table’s but are not exact, and two peaks in one column stay. Starfold uses it as its default family of structureless copy (Copies and gaps).

geometric mean

The n-th root of the product of n non-negative numbers, which is 0 whenever any one of them is 0. Starfold’s score is the geometric mean of prediction agreement, coverage and modularity, so no term can make up for another that is 0 (Score).

graph

A set of nodes joined by links. Here the nodes are rows of your table and each link joins a row to one of its nearest neighbours. Starfold builds a 15-nearest-neighbour graph of the scaled columns to compute modularity (Modularity).

group

A dense clump of rows that HDBSCAN reports, given an integer label from 0 upwards. Starfold’s result.labels assigns each kept row to a group or to noise (HDBSCAN: dense clumps and noise).

HDBSCAN

A clustering method that finds dense clumps of different densities in a map and leaves the rows between clumps as noise. Starfold runs it on the embedding and searches its min_cluster_size, min_samples and selection method (HDBSCAN: dense clumps and noise).

Jaccard index

The number of rows two groups share divided by the number of rows in either, which is 1 for identical groups and 0 for groups with no shared row. Starfold matches each reference group to its best refit cluster by this index to get recurrence (Group recurrence).

kept rows

The rows of your table that held only finite values and were used. Starfold stores their positions as result.kept_rows so that X[result.kept_rows] lines up with result.labels (Prepare your table for recover).

marginal

The distribution of one column taken by itself, ignoring the other columns. Starfold’s structureless copies keep every marginal exactly and change only how values are paired across columns (Copies and gaps).

min_cluster_size

The HDBSCAN setting for the smallest number of rows that may form a group. Starfold searches it on a log scale and rescales it from resample rows to full rows for the deployed settings (HDBSCAN: dense clumps and noise).

min_dist

The UMAP setting for how tightly the map may pack similar rows. Starfold searches it from 0.0 to 0.5 by default (UMAP: a map of your table).

min_samples

The HDBSCAN setting for how many neighbours define a row’s local density, where larger values call more rows noise. Starfold searches it as a fraction of min_cluster_size (HDBSCAN: dense clumps and noise).

modularity

A number that compares the share of links between nearby rows that stay inside groups with the share expected by chance. Starfold computes it on a 15-nearest-neighbour graph of your scaled columns, before any map is drawn, as one term of the score (Modularity).

Monte Carlo interval

The range of exceedance shares that a limited number of random copies leaves open, here a 95 percent Clopper-Pearson interval. Starfold prints it as null.p_intervals; it describes the precision of the simulation only (Calibration p-value).

n_components

The UMAP setting for how many coordinates the embedding has. Starfold searches it from 2 to 10 by default (UMAP: a map of your table).

n_neighbors

The UMAP setting for how many nearby rows each row looks at, where small values keep fine detail and large values the broad layout. Starfold searches it from 5 to 100 on a log scale (UMAP: a map of your table).

nearest neighbours

The rows closest to a given row by distance. Starfold uses the 15 nearest rows to predict the group of an unseen row and to build the modularity graph (Prediction agreement).

noise

The label -1 that HDBSCAN gives a row that no clump claimed. It means that no group took the row, not that the measurement was bad (HDBSCAN: dense clumps and noise).

null hypothesis

The default claim that a test tries to reject. Starfold’s null hypothesis is that your table is one structureless population from the declared copy family, and the p-value holds only for that family and the procedure simulated (Calibration p-value).

Optuna

A Python library that searches for good values of a set of numbers by proposing them, receiving a score and using the scores so far to propose the next. Starfold uses it to search the settings (Optuna: searching the settings).

own support

The support of a row for its own group in the full fit. Starfold keeps it as result.worlds.own_support, and it is NaN for noise rows (Support and own support).

p-value

The share of structureless copies whose statistic is at least as high as the table’s, counting the table as one more draw. If the table is itself a draw from the copy family, p at or below 0.05 comes up at most about 5 percent of the time. With several families, Starfold reports the largest of their p-values. Starfold prints null.p_value; a small value means the table beats almost every copy, and it is not the probability that the groups are real (Calibration p-value).

partition

The set of groups that one fit defines on the rows, including which rows are noise. Group numbers are arbitrary names, so two partitions agree when they split the rows alike and not when they use the same numbers (How Starfold chains the tools).

post hoc

Latin for after this. A check made after the analysis is fixed, with information the analysis never used. Starfold’s check against known classes is post hoc: the classes never enter the search, and you must not tune on it (Check a result against known labels).

posterior

The probability of a hypothesis after seeing the data, computed from a prior. Starfold computes no posteriors: recurrence and strengths are rates and within-fit strengths (Refits: reproducibility, not truth).

prediction agreement

How well a fit on one subset predicts the groups of a second fit on rows it never saw, measured by the adjusted Rand index floored at 0 and averaged over the six ordered pairs of three subsets. Starfold uses it as one term of the score, with no coverage factor inside it (Prediction agreement). It is stored as stability in each trial.

provenance

The record of how a result was produced: engines, library versions, configuration, seeds, budgets, fit counts, time per stage and a fingerprint of the input. Starfold stores it as result.provenance (Result fields).

pruning

Stopping a trial early because its first fits score below the median of finished trials. Starfold prunes only convergence trials, after two of their three fits (Optuna: searching the settings).

purity

The share of the rows of a group that belong to its most common known class. Starfold does not compute it; the notebooks plot it after the run as a post hoc check, and support is not a purity (Tutorial: groups in the scikit-learn digits dataset, part 1).

recurrence

How much of a group comes back in the refits: for each refit, the best Jaccard index match of the group, averaged over refits. 1 means a refit group holds exactly the drawn members every time and 0 means the group never comes back. Starfold’s group recurrence, support and unresolved mass all measure it, and none is a posterior (Group recurrence).

refit

A fit of the chosen setting on a random subset of the rows (80 percent by default), with a new seed and, if you give uncertainties, one redraw of your values. Starfold makes 32 and calls them worlds in the code; every measure of recurrence is taken over them (Refits: reproducibility, not truth).

refit agreement

For one refit, the adjusted Rand index, floored at 0, between its labels and the full-fit labels on the rows it drew, times coverage. Starfold prints the 32 values as result.worlds.world_agreement; the recorded run on the scikit-learn digits dataset, which notebook 01 writes and which ships in the repository as notebooks/runs/digits, has a median of 0.79 (Refits: reproducibility, not truth).

reproducibility

Whether a result comes back when the analysis is repeated, either with the same inputs and seed or on resampled data. Starfold’s refits measure the second kind, and its seed and provenance support the first (Reproduce a run).

row

One object in your table, such as an image or a star. Starfold gives each row a label, a support vector and a place in the embedding (Prepare your table for recover).

scaling

Rescaling each column so that no column dominates by its units. Starfold fits the scaler inside each subset on its own rows only, with "standard" (mean and standard deviation) or "robust" (median and interquartile range) (Choose between standard and robust scaling).

score

The one number per setting on your table, the base of the gap that the search maximises by default: the cube root of the product of prediction agreement, coverage and modularity. It is 0 whenever any of the three is 0 and it never reads the number of groups (Score).

seed

The starting number of a random number generator, which fixes the sequence of random choices. Starfold derives every seed from random_state and the position of the step in the procedure, so a stage does not depend on which worker runs it (Reproduce a run).

selection method

The HDBSCAN rule for picking clumps from its tree: "eom" keeps the most persistent clumps and "leaf" the finest ones. Starfold searches both (HDBSCAN: dense clumps and noise).

setting

One complete choice of the six values Starfold searches: n_neighbors, min_dist, n_components, min_cluster_size, min_samples and selection method. Starfold stores a setting as a Params object (Optuna: searching the settings).

Sobol design

A set of points placed to cover a range more evenly than random draws, without learning from any score. Starfold uses an Owen-scrambled Sobol design for trials 1 to 16 (Optuna: searching the settings).

Spearman correlation

A number from -1 to 1 that measures how well the ranks of two lists agree. Starfold’s benchmark uses it to check how well trial scores track the recovery of known classes (What Starfold does not claim).

stability interval

A range between percentiles of a quantity over refits, showing how far the answer moves under resampling. Starfold’s count interval and recurrence bands are stability intervals and not confidence intervals (Refits: reproducibility, not truth).

strengths

HDBSCAN’s within-fit membership strength for each row, between 0 and 1. They are not probabilities; Starfold stores them as result.strengths (HDBSCAN strengths).

structureless copy

A version of your table that keeps every value of every column and changes only which row each value sits in, so that structure across columns is lost, and every number in it was measured. Structure inside one column, such as two peaks, stays. Starfold scores settings on it to compute the gap and runs the calibration test on it (Copies and gaps).

support

For a row and a group of the full fit, the average share of the row’s refit group that belongs to that group in the full fit, taken over the refits that drew the row. It is not a purity and not a probability. Starfold’s own support is the support for the row’s own group (Support and own support).

TPE

The tree-structured Parzen estimator, an Optuna sampler that sorts earlier trials into good and poor, draws candidates near the good ones and keeps the one most typical of good trials and least typical of poor ones. Starfold uses it after the Sobol design, in its multivariate form (Optuna: searching the settings).

trial

One proposed setting with its score. Starfold runs up to 48 trials, and trial 0 is the library defaults, moved to the nearest bound if your ranges exclude them (Optuna: searching the settings).

UMAP

A method that turns a table into a low-dimensional map by arranging rows so that each row stays near its most similar rows. Starfold uses it to make the embedding and searches its n_neighbors, min_dist and n_components (UMAP: a map of your table).

unresolved mass

For one refit, a row scores 1 if the refit called it noise. Otherwise it scores the share of its refit group that the full fit calls noise. Starfold averages that score over the refits that drew the row, then over rows. Starfold prints it as result.unresolved_mass and raises high_unresolved_mass above 0.5 (Unresolved mass).

winner’s curse

The bias that makes the best of many noisy scores look better than it is, because part of its lead is luck. Starfold counters it with a fresh re-score of the top trials (Gap).

world

The name the code uses for a refit. Starfold keeps it in names such as result.worlds, n_worlds and world_labels (Refits: reproducibility, not truth).