pymixef.data module

Dependency-light input adapters, stable row identities, and data auditing.

class pymixef.data.AuditRecord(row_id, input_position, source_index, action, reason_code, missingness=None, columns=(), details=<factory>)[source]

Bases: object

Audit disposition for one original input row.

Parameters:

  • row_id (str)

  • input_position (int)

  • source_index (Any)

  • action (str)

  • reason_code (str)

  • missingness (MissingnessKind | None)

  • columns (tuple[str, ...])

  • details (Mapping[str, Any])

row_id: str
input_position: int
source_index: Any
action: str
reason_code: str
missingness: MissingnessKind | None
columns: tuple[str, ...]
details: Mapping[str, Any]
to_dict()[source]
Return type:

dict[str, Any]

class pymixef.data.AuditedData(source, data, audit, retained_positions)[source]

Bases: object

Analysis subset paired with its complete source-row audit.

Parameters:
source: ColumnarData
data: ColumnarData
audit: DataAudit
retained_positions: tuple[int, ...]
property row_ids: tuple[str, ...]
class pymixef.data.ColumnSchema(name, dtype, categorical=False, levels=(), ordered=False, missing_count=0, role=None, unit=None)[source]

Bases: object

Normalized metadata for one input column.

Parameters:

  • name (str)

  • dtype (str)

  • categorical (bool)

  • levels (tuple[Any, ...])

  • ordered (bool)

  • missing_count (int)

  • role (str | None)

  • unit (str | None)

name: str
dtype: str
categorical: bool
levels: tuple[Any, ...]
ordered: bool
missing_count: int
role: str | None
unit: str | None
to_dict()[source]
Return type:

dict[str, Any]

class pymixef.data.ColumnarData(columns, row_ids, source_index, schema, source_type='mapping')[source]

Bases: Mapping[str, NDArray[Any]]

Immutable column-oriented internal table.

Arrays are copied on ingestion and marked read-only. The internal format is deliberately independent of pandas, Polars, Arrow, and xarray.

Parameters:

  • columns (Mapping[str, NDArray[Any]])

  • row_ids (tuple[str, ...])

  • source_index (tuple[Any, ...])

  • schema (tuple[ColumnSchema, ...])

  • source_type (str)

columns: Mapping[str, NDArray[Any]]
row_ids: tuple[str, ...]
source_index: tuple[Any, ...]
schema: tuple[ColumnSchema, ...]
source_type: str
property n_rows: int
property n_columns: int
property column_names: tuple[str, ...]
take(positions)[source]

Return a row subset while preserving original stable identifiers.

Parameters:

positions (ArrayLike)

Return type:

ColumnarData

to_dict(*, copy=True)[source]

Return columns, copied by default.

Parameters:

copy (bool)

Return type:

dict[str, NDArray[Any]]

property fingerprint: str

Stable content hash including schema, order, and missing markers.

class pymixef.data.DataAdapter[source]

Bases: object

Namespace-style adapter for callers preferring an object API.

static adapt(data, *, column_names=None, roles=None, units=None)[source]

Delegate to adapt_data().

Parameters:

  • data (Any)

  • column_names (Sequence[str] | None)

  • roles (Mapping[str, str] | None)

  • units (Mapping[str, str] | None)

Return type:

ColumnarData

class pymixef.data.DataAudit(input_rows, analysis_rows, records, factor_levels=<factory>, factor_ordered=<factory>, contrast_coding=<factory>, transformations=(), source_fingerprint=None, analysis_fingerprint=None)[source]

Bases: object

Complete reconciliation of source and analysis rows.

Parameters:

  • input_rows (int)

  • analysis_rows (int)

  • records (tuple[AuditRecord, ...])

  • factor_levels (Mapping[str, tuple[Any, ...]])

  • factor_ordered (Mapping[str, bool])

  • contrast_coding (Mapping[str, str])

  • transformations (tuple[Mapping[str, Any], ...])

  • source_fingerprint (str | None)

  • analysis_fingerprint (str | None)

input_rows: int
analysis_rows: int
records: tuple[AuditRecord, ...]
factor_levels: Mapping[str, tuple[Any, ...]]
factor_ordered: Mapping[str, bool]
contrast_coding: Mapping[str, str]
transformations: tuple[Mapping[str, Any], ...]
source_fingerprint: str | None
analysis_fingerprint: str | None
property excluded_rows: int
property excluded_row_ids: tuple[str, ...]
property reason_counts: Mapping[str, int]
to_dict()[source]
Return type:

dict[str, Any]

pymixef.data.InputAdapter(data, *, column_names=None, roles=None, units=None)

Normalize a mapping or supported dataframe-like object.

Parameters:

  • data (Any)

  • column_names (Sequence[str] | None)

  • roles (Mapping[str, str] | None)

  • units (Mapping[str, str] | None)

Return type:

ColumnarData

class pymixef.data.MissingnessKind(*values)[source]

Bases: StrEnum

Semantically distinct missing-record conditions.

MISSING_RESPONSE = 'missing-response'
CENSORED_RESPONSE = 'censored-response'
STRUCTURALLY_ABSENT_ENDPOINT = 'structurally-absent-endpoint'
INVALID_RECORD = 'invalid-record'
MISSING_COVARIATE = 'missing-covariate'
class pymixef.data.PatternMixtureRecord(row_id, input_position, source_index, stratum, before, delta, after)[source]

Bases: object

One response-scale adjustment applied to an explicitly imputed value.

Parameters:

  • row_id (str)

  • input_position (int)

  • source_index (Any)

  • stratum (tuple[Any, ...])

  • before (float)

  • delta (float)

  • after (float)

row_id: str
input_position: int
source_index: Any
stratum: tuple[Any, ...]
before: float
delta: float
after: float
to_dict()[source]

Return a JSON-compatible audit record.

Return type:

dict[str, Any]

class pymixef.data.PatternMixtureResult(data, response, imputed_column, stratified_by, records, source_fingerprint)[source]

Bases: object

Adjusted completed data paired with a row-level sensitivity audit.

Parameters:

  • data (ColumnarData)

  • response (str)

  • imputed_column (str | None)

  • stratified_by (tuple[str, ...])

  • records (tuple[PatternMixtureRecord, ...])

  • source_fingerprint (str)

data: ColumnarData
response: str
imputed_column: str | None
stratified_by: tuple[str, ...]
records: tuple[PatternMixtureRecord, ...]
source_fingerprint: str
property adjusted_rows: int

Number of explicitly imputed response values adjusted.

to_dict()[source]

Return serializable metadata without duplicating the full adjusted data.

Return type:

dict[str, Any]

pymixef.data.adapt_data(data, *, column_names=None, roles=None, units=None)[source]

Normalize a mapping or supported dataframe-like object.

Parameters:

  • data (Any)

  • column_names (Sequence[str] | None)

  • roles (Mapping[str, str] | None)

  • units (Mapping[str, str] | None)

Return type:

ColumnarData

pymixef.data.audit_data(data, *, response=None, covariates=(), censored=None, structurally_absent=None, invalid=None, missing='drop', factor_levels=None, contrast_coding=None)[source]

Apply the missingness contract and produce a row-complete audit.

missing may be "drop", "raise", or "keep". Invalid and structurally absent records are always excluded; censored records are retained even when their response value is absent.

Parameters:

  • data (Any)

  • response (str | None)

  • covariates (Sequence[str])

  • censored (str | ArrayLike | None)

  • structurally_absent (str | ArrayLike | None)

  • invalid (str | ArrayLike | None)

  • missing (str)

  • factor_levels (Mapping[str, Sequence[Any]] | None)

  • contrast_coding (Mapping[str, str] | None)

Return type:

AuditedData

pymixef.data.find_duplicate_keys(data, keys)[source]

Return duplicate key values in deterministic first-seen order.

Parameters:

  • data (Any)

  • keys (Sequence[str])

Return type:

tuple[tuple[Any, …], …]

pymixef.data.is_missing(value)[source]

Return whether a scalar is missing without requiring pandas.

Parameters:

value (Any)

Return type:

bool

pymixef.data.missing_mask(values)[source]

Return a one-dimensional missing-value mask.

Parameters:

values (ArrayLike)

Return type:

NDArray[bool]

pymixef.data.pattern_mixture_adjust(data, *, response, imputed, delta, by=None)[source]

Apply an audited delta adjustment only to explicitly imputed responses.

This is a controlled pattern-mixture data transformation, not an imputation algorithm. Callers first complete the response under their primary missing-at-random procedure, then identify those imputed cells with imputed. A scalar delta applies one response-scale shift. A mapping requires by and supplies a shift for every selected stratum; with multiple by columns, mapping keys are tuples in the same order.

Observed response values and every non-response column are preserved exactly. The returned records retain source row identities, the base imputed value, applied shift, and adjusted value.

Parameters:

  • data (Any)

  • response (str)

  • imputed (str | ArrayLike)

  • delta (float | Mapping[Any, float])

  • by (str | Sequence[str] | None)

Return type:

PatternMixtureResult

pymixef.data.prepare_data(data, *, response=None, covariates=(), censored=None, structurally_absent=None, invalid=None, missing='drop', factor_levels=None, contrast_coding=None)

Apply the missingness contract and produce a row-complete audit.

missing may be "drop", "raise", or "keep". Invalid and structurally absent records are always excluded; censored records are retained even when their response value is absent.

Parameters:

  • data (Any)

  • response (str | None)

  • covariates (Sequence[str])

  • censored (str | ArrayLike | None)

  • structurally_absent (str | ArrayLike | None)

  • invalid (str | ArrayLike | None)

  • missing (str)

  • factor_levels (Mapping[str, Sequence[Any]] | None)

  • contrast_coding (Mapping[str, str] | None)

Return type:

AuditedData

pymixef.data.stable_sort(data, keys)[source]

Stable lexicographic sort returning the source-position permutation.

Parameters:

  • data (Any)

  • keys (Sequence[str])

Return type:

tuple[ColumnarData, tuple[int, …]]

pymixef.data.validate_monotonic_time(data, *, group, time)[source]

Raise if time decreases within a group in source row order.

Parameters:

  • data (Any)

  • group (str)

  • time (str)

Return type:

None

On this page
Show Source