spine_summary

Say in words what a partition found.

Nothing is recomputed, so it can be called whenever you like, including on a Result loaded back from a saved file long after the run.

Syntax and options

from entropy_spine import spine_summary
help(spine_summary)

Help on function spine_summary in module entropy_spine.interface.summary:

spine_summary(result, *, report: 'bool' = True) -> 'str'
    spine_summary: say in words what a partition found.

        spine_summary(result)              prints
        txt = spine_summary(result, report=False)   returns the text, prints nothing

    Nothing is recomputed. Call it whenever you like, including on a Result loaded
    back from a saved file long after the run. Returning the text means it
    composes: it can go into a figure title, a log, or a methods paragraph.

A partition with structure

import numpy as np
from entropy_spine import spine

rng = np.random.default_rng(20260810)
X = np.vstack([rng.standard_normal((240, 8)),
               rng.standard_normal((45, 8)) + 6,
               rng.standard_normal((15, 8)) + 30])
_, result = spine(X, "robustrownorm", "upper")
spine_summary(result);

SPINE   300 objects, 3 strata        measure robustrownorm | orientation upper

  stratum  objects        measure range        score
        1      240       0.5973 to 4.165        0.000
        2       45        9.653 to 13.63        0.223
        3       15        59.87 to 63.17        1.000

  cuts at 4.165, 13.63
  result.boundary_values applies these cuts to new data.

When there is nothing to find

A single stratum is an answer, not a failure, and the summary says so rather than reporting a cut that does not exist.

rng = np.random.default_rng(3)
_, flat = spine(rng.standard_normal((300, 4)), "dist2median", "upper")
spine_summary(flat);

SPINE   300 objects, 1 stratum        measure dist2median | orientation upper

  stratum  objects        measure range        score
        1      300       0.5043 to 4.458        0.000

  No cut. This measure does not separate these objects into scales,
  which is a property of the measure, not a failure of the partition.

Notes appear when they matter

Omitted objects, dropped columns, thinning, a measure used against its conventional orientation: each adds a line, and none appears otherwise.

Xm = np.column_stack([X, np.ones(X.shape[0])])   # a column with no spread
Xm[4, 1] = np.nan
_, noted = spine(Xm, "zrownorm", "upper", missing="omit")
spine_summary(noted);

SPINE   300 objects, 2 strata        measure zrownorm | orientation upper

  stratum  objects        measure range        score
        1      284        0.687 to 1.863        0.000
        2       15        11.28 to 11.89        1.000

  cut at 1.863
  result.boundary_values applies these cuts to new data.

  note: 1 column dropped for having no spread: 9
  note: 1 object omitted for missing values; their scores are NaN

Returning the text

With report=False it returns the text and prints nothing, so it composes into a figure title, a log, or a methods paragraph.

txt = spine_summary(result, report=False)
print(f"{len(txt)} characters returned, nothing printed")

375 characters returned, nothing printed

See also

spine to produce a Result, spine_compare to compare several measures, and spine_data_plot to see the partition rather than read it.