spacr.derived_tables

Recreate tables from saved definitions without changing input data.

Use the same derived tables for charts and measurement filters.

Default definitions delegate to spacr.merge_tables, the measurement aggregation used by Regression. Custom definitions describe explicit joins onto unique base observations; children are aggregated before joining. JSON sidecars preserve definitions without altering source tables. A definition is bound to a canonical database path and the selected tables’ column schemas.

Functions

allowed_methods(series, *[, identifier])	List aggregations compatible with a column's actual values.
column_sample(path, table[, limit])	Read a bounded sample for controls; execution always validates all rows.
default_definition(path, tables, *[, name, base, policy])	Describe the established spaCR merge, with no inferred external keys.
execute(path, definition)	Revalidate and materialize a merge without writing source tables.
identity_columns(frame)	Return image and time provenance actually present in a frame.
load_definitions(path)	Read saved definitions scoped to one database; execution revalidates schemas.
save_definition(path, definition)	Validate then atomically save a named definition alongside its source.
schemas(path)	Discover user tables and declared column types without changing them.
sidecar_path(path)	Return the source-adjacent definition file without modifying the database.
validate_source(path, definition)	Refuse reuse on another database or a changed selected-table schema.

Module Contents

spacr.derived_tables.allowed_methods(series, *, identifier=False)

List aggregations compatible with a column’s actual values.

Parameters:

• series – Source column values.

• identifier – Whether these values identify observations.

Returns:

Supported deterministic method names.

spacr.derived_tables.column_sample(path, table, limit=200)

Read a bounded sample for controls; execution always validates all rows.

Parameters:

• path – Database path.

• table – Source table name.

• limit – Maximum sampled rows.

Returns:

Sample frame preserving SQLite column types when possible.

spacr.derived_tables.default_definition(path, tables, *, name='Merged measurements', base=None, policy=None)

Describe the established spaCR merge, with no inferred external keys.

Parameters:

• path – SQLite data source.

• tables – Tables to combine, including the output observation table.

• name – Display name for this derived table.

• base – Output table; defaults to cell, cytoplasm, or the first table.

• policy – Optional existing MergePolicy to retain user choices.

Returns:

JSON-serializable definition; execution validates the schema.

spacr.derived_tables.execute(path, definition)

Revalidate and materialize a merge without writing source tables.

Parameters:

• path – Source SQLite database.

• definition – Default or acknowledged custom merge configuration.

Returns:

(frame, diagnostics) with full counts and actual aggregation rules.

Raises:

MergeError – Missing keys, changed schemas, cardinality or type violations.

Genuine base provenance is kept: external names are never turned into image identities just because they happen to be unique. One-to-one joins, once validated, still go through the same typed plan on their singleton groups, so explicit count and nunique overrides stay real. Gate and filter identities use timeID, and the original time_id spelling is preserved too, so a chart that selects time_id stays reproducible.

spacr.derived_tables.identity_columns(frame)

Return image and time provenance actually present in a frame.

Parameters:

frame – An object measurement frame.

Returns:

Ordered identity columns, excluding the object label.

spacr.derived_tables.load_definitions(path)

Read saved definitions scoped to one database; execution revalidates schemas.

Parameters:

path – Database path.

Returns:

Name-to-definition mapping, empty when no definitions exist.

spacr.derived_tables.save_definition(path, definition)

Validate then atomically save a named definition alongside its source.

Parameters:

• path – Database path.

• definition – Reproducible configuration, including the display name.

Returns:

Saved display name.

spacr.derived_tables.schemas(path)

Discover user tables and declared column types without changing them.

Parameters:

path – SQLite database path.

Returns:

Table names mapped to lists of column-name/type pairs.

spacr.derived_tables.sidecar_path(path)

Return the source-adjacent definition file without modifying the database.

Parameters:

path – Database path.

Returns:

Path to its JSON derived-table definitions.

spacr.derived_tables.validate_source(path, definition)

Refuse reuse on another database or a changed selected-table schema.

Parameters:

• path – Database being used now.

• definition – Saved derived-table definition.

Raises:

MergeError – Source or schema no longer matches.