causalis.data_contracts.rct_causal_data

RCT data with multiple outcomes and binary or one-hot treatment arms.

Module Contents

Classes

RctCausalData

Validated data for multiple outcomes sharing treatment and confounders.

API

class causalis.data_contracts.rct_causal_data.RctCausalData(/, **data: Any)

Bases: pydantic.BaseModel

Validated data for multiple outcomes sharing treatment and confounders.

outcomes accepts a column name or a non-empty list of names. Repeated names are removed in input order. All roles must be disjoint. Outcomes and confounders must be finite, real numeric or boolean, and non-constant; each treatment column must contain both 0 and 1. A single treatment column uses 0 as control. Multiple columns must encode mutually exclusive arms, including an explicit control_treatment column, with exactly one 1 per row. The control column is ordered first. This validates data structure, not whether treatment assignment was actually randomized. Used columns cannot contain missing values or identical column values. Optional user IDs must be unique.

Construction stores an independent copy of only the selected columns, preserving the index and numeric dtypes (booleans and treatment become int8). Shared columns are validated once, regardless of outcome count. Missing/finite checks operate column by column, avoiding a table-sized boolean mask. Duplicate screening uses a small sample, then full-column fingerprints and exact comparisons for candidates only. Sampling never determines equality. There is no fixed limit on the number of outcomes.

outcomes/Y, treatments/D, and X return independent DataFrames. treatment exposes a stored Series for a single treatment, or a copied DataFrame for multiple arms. user_id exposes a stored Series. Use :meth:for_outcome to create a validated single-outcome contract for existing estimators; that conversion copies and validates its subset.

Initialization

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

model_config

‘ConfigDict(…)’

df: pandas.DataFrame

None

treatment_names: list[str]

‘Field(…)’

control_treatment: str | None

None

outcome_names: list[str]

‘Field(…)’

confounders_names: list[str]

‘Field(…)’

user_id_name: str | None

‘Field(…)’

classmethod from_df(df: pandas.DataFrame, treatment: str | list[str] | None = None, outcomes: str | list[str] | None = None, confounders: str | list[str] | None = None, user_id: str | None = None, **kwargs: Any) → causalis.data_contracts.rct_causal_data.RctCausalData

Construct from a DataFrame and role column names.

property outcomes: pandas.DataFrame

Outcome matrix in the requested order, as an independent copy.

property Y: pandas.DataFrame

Alias for the two-dimensional outcome matrix, even for one outcome.

property treatment: pandas.Series | pandas.DataFrame

Binary Series for one column, or independent treatment-arm matrix.

property treatment_name: str

Single treatment name; use treatment_names for multiple arms.

property treatments: pandas.DataFrame

Independent treatment matrix, with control first for multiple arms.

property D: pandas.DataFrame

Alias for the two-dimensional treatment matrix.

property confounders: list[str]

Confounder names in input order.

property X: pandas.DataFrame

Independent confounder matrix, retaining the observation index.

property user_id: pandas.Series

Stored user IDs, or an empty Series when no ID was specified.

get_df(columns: list[str] | None = None, include_treatment: bool = True, include_outcomes: bool = True, include_confounders: bool = True, include_user_id: bool = False) → pandas.DataFrame

Copy selected columns; explicit columns are additive to role flags.

for_outcome(outcome: str) → causalis.data_contracts.causaldata.CausalData | causalis.data_contracts.multicausaldata.MultiCausalData

Create CausalData (binary) or MultiCausalData (multiple arms).

The destination contract validates the copied subset, including its own constraints (such as MultiCausalData’s treatment-count limit).

__repr__() → str