gcubed.data.logged_zero_preparation

Shared preparation and validation of logged database observations.

LOGGED_ZERO_EPSILON: float = 1e-20

LOGGED_ZERO_PREPARATION_POLICY_VERSION: str = '1'

LOGGED_ZERO_REFERENCE_STAGE: str = 'after division by 100, before GDP scaling'

def validate_logged_zero_preparation_state(state: dict[str, object]) -> None:

Fail closed when a serialized working database predates this policy.

def raise_if_logged_zero_preparation_already_applied(database: object) -> None:

Reject a derived database before any unit transformation can repeat.

def prepare_logged_zero_observations( data: pandas.DataFrame, variable_summary: pandas.DataFrame, zero_variables_selector: pandas.Series, allowed_missing_variable_names: Collection[str] = ()) -> pandas.DataFrame:

Replace eligible exact zeros while retaining explicitly deferred rows.

Overview

Applies the common pre-log zero treatment, while allowing an explicit, tightly scoped set of later-generated rows to remain missing.

Arguments

data: Database observations at the shared pre-log reference stage.
variable_summary: Model metadata indexed by fully articulated names.
zero_variables_selector: Rows excluded from logarithmic treatment.
allowed_missing_variable_names: Active logged rows calculated by a later database-generation stage. Deferral permits missing values only; negative and infinite values remain invalid.

Returns

Compact provenance for each exact-zero substitution.

Exceptions

Raises ValueError when a deferred name is ineligible or a non-deferred logged observation is non-finite or negative.

def validate_logged_observations( data: pandas.DataFrame, variable_summary: pandas.DataFrame, zero_variables_selector: pandas.Series, variable_names: Collection[str] | None = None, stage: str = 'during validation') -> None:

Require selected active logged observations to be finite and positive.

Overview

Validates final values for every active logged row or a named eligible subset, so a producer can be checked at the stage where it has finished.

Arguments

data: Database values to validate.
variable_summary: Model metadata indexed by fully articulated names.
zero_variables_selector: Rows excluded from logarithmic treatment.
variable_names: Optional active logged rows to validate. Omitting it validates every active logged row.
stage: Description included in an error message to locate the producer.

Returns

None.

Exceptions

Raises ValueError when a selected name is ineligible or an observation is non-finite or non-positive. Selecting only later-stage rows avoids treating intentionally unpopulated model families as final-data errors.

def complete_logged_zero_preparation_diagnostics( diagnostics: pandas.DataFrame, data: pandas.DataFrame, database_kind: str, scaling_factors: pandas.Series) -> pandas.DataFrame:

Add database-specific scaling and final stored values to provenance.