spacr.columns

Report missing columns and offer the columns that are available.

Without this check, a misnamed dependent_variable passes the early checks and fails inside the merge, after the whole score table has been read, with a message that names the missing column but not the available ones.

Three rules apply:

1. Only the header row is read (nrows=0). The check runs before the run, sometimes to populate a GUI dropdown on the GUI thread, and a score CSV can be hundreds of megabytes.

2. A missing file is reported separately from a missing column. A missing file has no header to compare against; a missing column is reported with the columns that do exist.

3. Suggestions are given in addition to the full column list. Near-misses are listed first because predictions for prediction is a common typo, and the full list is always included as well.

Exceptions

ColumnNotFound

Raised when a named column is absent; the message lists those present.

Functions

available(→ List[str])	Every column across paths, in order, without duplicates.
describe(→ str)	Return the message to print or raise when column name is missing.
headers(→ Dict[str, List[str]])	{path: [column, ...]} for every readable CSV in paths.
missing(→ List[str])	Return the paths whose header could not be read by headers().
numeric_headers(→ Dict[str, List[str]])	{path: [column, ...]} of the numeric columns that can be a response.
pred_guidance(→ str)	The sentence that says where a pred column comes from.
pred_missing(→ List[str])	The readable files among paths that have no pred column.
resolve(→ str)	name if the CSVs have it, else raise with what they do have.
suggest(→ List[str])	Column names close to name, best first.

Module Contents

exception spacr.columns.ColumnNotFound(message: str, *, name: str = '', available: Sequence[str] = ())

Bases: KeyError

Raised when a named column is absent; the message lists those present.

Parameters:

• message – human-readable explanation returned for the exception.

• name – the column that was asked for, kept so a caller can recover it without parsing message.

• available – the columns the file does have, in file order. Not sorted, because file order is what a user reading the header sees, and sorting hides that related columns are grouped together.

A KeyError subclass so existing except KeyError paths still catch it, and so settings['x'] failures and this one read the same way to a caller that does not care which it was.

Initialize a readable error with structured column context.

__str__() → str

Return the message without KeyError’s added quoting.

spacr.columns.available(paths) → List[str]

Every column across paths, in order, without duplicates.

Parameters:

paths – one CSV path, a sequence of paths, or None.

Across, not per file: score_data is routinely a list of one CSV per plate with identical headers, and a user choosing a column does not care which plate it came from.

spacr.columns.describe(name, paths, *, what: str = 'column', setting: str = '') → str

Return the message to print or raise when column name is missing.

Parameters:

• name – missing column name to explain.

• paths – CSV paths whose headers should be reported.

Names the setting, the files that were read, the near-misses and then every column.

spacr.columns.headers(paths) → Dict[str, List[str]]

{path: [column, ...]} for every readable CSV in paths.

Parameters:

paths – one path, a sequence of them, or None.

Returns:

a dict in the order given. A path that does not exist or cannot be parsed is absent from the result rather than mapped to an empty list – see rule 2. Use missing() to ask which those were.

spacr.columns.missing(paths) → List[str]

Return the paths whose header could not be read by headers().

Parameters:

paths – one CSV path, a sequence of paths, or None.

spacr.columns.numeric_headers(paths, rows: int = 200) → Dict[str, List[str]]

{path: [column, ...]} of the numeric columns that can be a response.

Parameters:

• paths – one path, a sequence of them, or None.

• rows – how many rows are read to tell a number from a label. The header decides the names and a short sample decides the type, so the cost stays the same for a score file of any size.

Returns:

a dict in the order given. Identifier columns (RESPONSE_EXCLUDED) are left out; an unreadable file is absent.

spacr.columns.pred_guidance() → str

The sentence that says where a pred column comes from.

spacr.columns.pred_missing(paths) → List[str]

The readable files among paths that have no pred column.

Parameters:

paths – one path, a sequence of them, or None.

spacr.columns.resolve(name, paths, *, what: str = 'column', setting: str = '') → str

name if the CSVs have it, else raise with what they do have.

Parameters:

• name – the column asked for.

• paths – the CSVs to look in.

• what – what kind of column, for the message (“response column”, “count column”).

• setting – the settings key this came from, so the message names the control the user has to change.

Raises:

ColumnNotFound – carrying available, so a GUI can offer the list rather than re-reading the files to build it.

A case-insensitive match is accepted and returned in the file’s spelling: Predictions resolves to predictions when the file uses that name.

spacr.columns.suggest(name, columns: Iterable[str]) → List[str]

Column names close to name, best first.

Parameters:

• name – missing column name for which to find near-matches.

• columns – available column names to search.

Matching is case-insensitive, so Prediction is suggested for prediction.