CausalScience 0.1.0a13__py3-none-any.whl

causalscience/CSCM.py

@@ -0,0 +1,427 @@
+"""Back-door-style preset with a hidden common cause of X, A, and Y."""
+from functools import partial
+from dataclasses import dataclass
+from inspect import signature
+from numbers import Real
+
+import numpy as np
+from scipy.special import expit, logit, ndtr
+from scipy import stats
+from scipy.integrate import quad_vec
+from scipy.optimize import minimize_scalar
+from scipy.special import logsumexp
+
+from .bdscm import BDSCM, IndependentNoise
+from .bdscm.covariates import OpenMLCovariates, SyntheticCovariates
+from .bdscm.outcome import OutcomeMechanism, CAPOOutcomeMechanism
+from .bdscm.treatment import TreatmentOptions
+from .bdscm.utils import EPS, _require, _integer
+
+
+@dataclass(frozen=True)
+class ConfounderOptions:
+    """Latent law, monotone effect, and positive loading magnitudes; frozen per task."""
+    distribution: str = 'normal'
+    function: str = 'linear'
+    strength_range: tuple = (.25, .75)
+    df: float = 5.
+    probability: float = .5
+
+    def __post_init__(self):
+        _require(self.distribution in ('normal', 'uniform', 'laplace', 'student_t', 'bernoulli', 'random'),
+                 'Unknown confounder distribution.')
+        _require(self.function in ('linear', 'tanh', 'signed_log', 'random'), 'Unknown confounder function.')
+        bounds = tuple(self.strength_range)
+        _require(len(bounds) == 2 and np.isfinite(bounds).all() and 0 < bounds[0] <= bounds[1],
+                 'strength_range must contain positive finite ordered bounds.')
+        _require(np.isfinite(self.df) and self.df > 2, 'df must be finite and greater than 2.')
+        _require(np.isfinite(self.probability) and 0 < self.probability < 1, 'probability must lie in (0, 1).')
+        object.__setattr__(self, 'strength_range', bounds)
+
+
+def _latent(z, family, options):
+    if family == 'normal':
+        return z
+    if family == 'bernoulli':
+        return (z > stats.norm.isf(options.probability)).astype(np.int64)
+    probability = np.clip(ndtr(z), EPS, 1-EPS)
+    if family == 'uniform':
+        return np.sqrt(12.)*(probability-.5)
+    return (stats.laplace.ppf(probability)/np.sqrt(2.) if family == 'laplace' else
+            stats.t.ppf(probability, options.df)/np.sqrt(options.df/(options.df-2)))
+
+
+def _draw_latent(rng, size, family, options):
+    return _latent(rng.standard_normal(size), family, options)
+
+
+def _effect(u, function):
+    return u if function == 'linear' else np.tanh(u) if function == 'tanh' else np.sign(u)*np.log1p(np.abs(u))
+
+
+def _accepts_offset(method):
+    try:
+        signature(method).bind_partial(score_offset=None)
+    except (TypeError, ValueError):
+        return False
+    return True
+
+
+def _noise(n, seed, start_row, base, latent, family, options):
+    values = base(n, seed, start_row)
+    values['U'] = _latent(latent(n, seed, start_row)['U_Y'], family, options)
+    return values
+
+
+def _x(U, noise, mechanism, loading, function):
+    U = _effect(U, function)
+    offset = U * loading if np.isscalar(loading) else U[:, None] * loading
+    return mechanism.encode(mechanism(noise, score_offset=offset), return_observed=True)[0]
+
+
+def _propensity(features, u, mechanism, mask, loading):
+    base = mechanism.propensity(features if mask.all() else features * mask)
+    return expit(logit(np.clip(base, EPS, 1-EPS)) + loading*u)
+
+
+def _a(X, U, noise, covariates, mechanism, mask, loading, function):
+    U = _effect(U, function)
+    return (noise < _propensity(covariates.encode(X), U, mechanism, mask, loading)).astype(np.int64)
+
+
+def _y(X, A, U, noise, covariates, mechanism, mask, loading, function):
+    U = _effect(U, function)
+    features = covariates.encode(X)
+    features = features if mask.all() else features * mask
+    offset = loading*U
+    return np.where(A == 1, mechanism(features, 1, noise, score_offset=offset),
+                    mechanism(features, 0, noise, score_offset=offset))
+
+
+class CSCM(BDSCM):
+    """Shared-engine preset with explicit-U and observed-X conditional means."""
+
+    def __init__(self, *args, confounder=None, unconfounded=False, confounding_power=1.,
+                 simpson_mode=False, **kwargs):
+        _require(type(simpson_mode) is bool, 'simpson_mode must be a bool.')
+        _require(type(unconfounded) is bool, 'unconfounded must be a bool.')
+        _require(isinstance(confounding_power, Real) and not isinstance(confounding_power, (bool, np.bool_))
+                 and np.isfinite(confounding_power), 'confounding_power must be a finite real number.')
+        self.unconfounded = unconfounded or bool(confounding_power == 0)
+        self.confounding_power = 0. if self.unconfounded else float(confounding_power)
+        self.simpson_mode = simpson_mode
+        if simpson_mode:
+            treatment = kwargs.get('treatment')
+            if treatment is None:
+                kwargs['treatment'] = TreatmentOptions(mechanism='independent')
+            else:
+                _require(isinstance(treatment, TreatmentOptions) and
+                         treatment.mechanism == 'independent' and
+                         treatment.independent_treatment_prob == .5,
+                         'simpson_mode requires independent treatment with probability 0.5.')
+        options = ConfounderOptions() if confounder is None else confounder
+        _require(isinstance(options, ConfounderOptions), 'confounder must be ConfounderOptions.')
+        super().__init__(*args, **kwargs)
+        if simpson_mode:
+            _require(type(self.f_Y) is OutcomeMechanism,
+                     'simpson_mode requires a built-in outcome mechanism.')
+            active = np.flatnonzero(self.outcome_mask)
+            _require(len(active) > 0, 'simpson_mode requires an active outcome covariate column.')
+            self.f_Y.simpson_feature_index = int(active[0])
+        _require(_accepts_offset(self.f_X) and _accepts_offset(self.f_Y) and
+                 _accepts_offset(getattr(self.f_Y, 'mean', None)),
+                 'CSCM covariate call and outcome call/mean must accept score_offset.')
+        choices = np.random.default_rng(np.random.SeedSequence([self.task_seed, 3043]))
+        family = str(choices.choice(('normal', 'uniform', 'laplace', 'student_t', 'bernoulli')))
+        function = str(choices.choice(('linear', 'tanh', 'signed_log')))
+        self.confounder_options = options
+        self.confounder_family = family if options.distribution == 'random' else options.distribution
+        self.confounder_function = function if options.function == 'random' else options.function
+        self.confounder_metadata = dict(distribution=self.confounder_family, function=self.confounder_function,
+            strength_range=options.strength_range, df=options.df, probability=options.probability,
+            unconfounded=self.unconfounded, confounding_power=self.confounding_power)
+        rng = np.random.default_rng(np.random.SeedSequence([self.task_seed, 3042]))
+        coefficients = rng.choice((-1., 1.), self.d_X+2) * rng.uniform(*options.strength_range, self.d_X+2)
+        loading_x = coefficients[:self.d_X].copy()
+        loading_x.setflags(write=False)
+        if isinstance(self.f_X, OpenMLCovariates):
+            loading_x = float(loading_x[0])
+        self.loadings = dict(X=loading_x if np.isscalar(loading_x) else tuple(loading_x),
+                             A=0. if self.unconfounded else float(coefficients[-2])*self.confounding_power,
+                             Y=float(coefficients[-1]))
+        if simpson_mode:
+            self.loadings.update(A=-self.confounding_power, Y=2.)
+            self.confounder_metadata['simpson_mode'] = dict(
+                treatment_logit='-confounding_power * g(U)', outcome_loading=2.,
+                score_contrast='1 + 0.75 * tanh(encoded_X[j])',
+                feature_index=self.f_Y.simpson_feature_index, base_treatment_probability=.5)
+        _require(np.isfinite(self.loadings['A']), 'Scaled treatment loading must be finite.')
+        latent_seed = int(np.random.SeedSequence([self.task_seed, 3041]).generate_state(1)[0])
+        self.scm.add_variable('U', lambda noise: noise, observed=False,
+            variable_type='binary' if self.confounder_family == 'bernoulli' else 'continuous',
+            noise_distribution=partial(_draw_latent, family=self.confounder_family, options=options))
+        self.scm = self.scm.replace_mechanism('X', partial(_x, mechanism=self.f_X,
+            loading=loading_x,
+            function=self.confounder_function), ['U'])
+        if not self.unconfounded:
+            self.scm = self.scm.replace_mechanism('A', partial(_a, covariates=self.f_X,
+                mechanism=self.f_A, mask=self.treatment_mask.copy(), loading=self.loadings['A'],
+                function=self.confounder_function), ['X', 'U'])
+        self.scm = self.scm.replace_mechanism('Y', partial(_y, covariates=self.f_X,
+            mechanism=self.f_Y, mask=self.outcome_mask.copy(), loading=self.loadings['Y'], function=self.confounder_function), ['X', 'A', 'U'])
+        self.scm._noise_provider = partial(_noise, base=self.scm._noise_provider,
+            latent=IndependentNoise(1, latent_seed), family=self.confounder_family, options=options)
+        self.scm._provider_nodes = frozenset(('X', 'A', 'Y', 'U'))
+        self.scm._block_compatible = True
+        self.scm._variables['U']['columns'] = ['U']
+        self.graph.nodes['U'].update(observed=False, variable_type=self.scm._variables['U']['variable_type'],
+                                     shape=(), dimension=1, columns=['U'])
+
+    def _truth_xu(self, features, u, u_y=None):
+        outcome_features = self._masked(features, self.outcome_mask)
+        effect = _effect(u, self.confounder_function)
+        offset = self.loadings['Y']*effect
+        propensity = (self.f_A.propensity(self._masked(features, self.treatment_mask)) if self.unconfounded else
+                      _propensity(features, effect, self.f_A, self.treatment_mask, self.loadings['A']))
+        result = dict(U=u.copy(), mu0_xu=self.f_Y.mean(outcome_features, 0, score_offset=offset),
+            mu1_xu=self.f_Y.mean(outcome_features, 1, score_offset=offset),
+            e_xu=propensity)
+        if u_y is not None:
+            result.update(Y0=self.f_Y(outcome_features, 0, u_y, score_offset=offset),
+                          Y1=self.f_Y(outcome_features, 1, u_y, score_offset=offset))
+        _require(all(np.isfinite(v).all() for v in result.values()), 'CSCM truth must be finite.')
+        return result
+
+    def truth_at(self, x, *, u=None, u_y=None, data_seed=None, start_row=0,
+                 atol=1e-6, rtol=1e-5, max_subdivisions=200, cdf_maxpts=20000):
+        """With u, retain latent-conditional truth; without u, integrate U|X.
+
+        The observed-X path returns mu0/mu1 and exact/numerical diagnostics.
+        It averages outcome noise, so individual-noise replay options are invalid.
+        Numerical convergence diagnostics are not certified error bounds.
+        """
+        x = np.asarray(x, dtype=float)
+        _require(x.ndim == 2 and x.shape[1] == self.d_X and not np.isinf(x).any(),
+                 f'Expected X of shape (n, {self.d_X}) without infinite values.')
+        if u is None:
+            _require(u_y is None and data_seed is None and start_row == 0,
+                     'Observed-X CAPO averages outcome noise; omit u_y, data_seed and start_row.')
+            return self._observed_truth(x, atol, rtol, max_subdivisions, cdf_maxpts)
+        u = np.broadcast_to(np.asarray(u, dtype=float), (len(x),))
+        _require(np.isfinite(u).all(), 'U must be finite.')
+        _require(self.confounder_family != 'bernoulli' or np.isin(u, (0, 1)).all(),
+                 'Bernoulli U must contain only 0 or 1.')
+        _require(u_y is None or data_seed is None, 'Supply u_y or data_seed, not both.')
+        _require(data_seed is not None or start_row == 0, 'start_row requires data_seed.')
+        if data_seed is not None:
+            u_y = self.f_U(len(x), data_seed, start_row)['U_Y']
+        if u_y is not None:
+            u_y = np.broadcast_to(np.asarray(u_y, dtype=float), (len(x),))
+            _require(np.isfinite(u_y).all(), 'U_Y must be finite.')
+        features = self.f_X.encode(x)
+        _require(np.isfinite(features).all(), 'X could not be encoded as finite features.')
+        return self._truth_xu(features, u, u_y)
+
+    def _observed_truth(self, x, atol, rtol, max_subdivisions, cdf_maxpts, *, latent_function=None):
+        _require(type(self.f_X) in (SyntheticCovariates, OpenMLCovariates),
+                 'Observed-X CAPO supports only the built-in covariate mechanisms.')
+        _require(np.isfinite([atol,rtol]).all() and atol>0 and rtol>0,
+                 'CAPO tolerances must be positive and finite.')
+        limit = _integer(max_subdivisions, 'max_subdivisions', 2)
+        budget = _integer(cdf_maxpts, 'cdf_maxpts', 128)
+        observed, features = self.f_X.encode(x, return_observed=True)
+        _require(np.isfinite(observed).all() and np.isfinite(features).all(), 'CAPO X must encode to finite values.')
+        population = (self.f_X.encode(self.f_X.table, return_observed=True)[0]
+                      if type(self.f_X) is OpenMLCovariates else None)
+        means, methods, errors, refinements = [], [], [], []
+        for row, feature in zip(observed, features):
+            def solve(points):
+                likelihood, meta = self.f_X._capo_likelihood(row, self.loadings['X'], points, population=population)
+                def arm_means(u):
+                    if latent_function is not None:
+                        return np.full(2, latent_function(u))
+                    values = self._truth_xu(feature[None,:], np.array([u]))
+                    return np.array([values['mu0_xu'][0],values['mu1_xu'][0]])
+                if self.confounder_family == 'bernoulli':
+                    prior = np.array([1-self.confounder_options.probability,self.confounder_options.probability])
+                    logs = np.array([likelihood(_effect(u,self.confounder_function)) for u in (0.,1.)])+np.log(prior)
+                    _require(np.isfinite(logsumexp(logs)), 'X has zero covariate likelihood.')
+                    weights = np.exp(logs-logsumexp(logs))
+                    result = sum(w*arm_means(u) for w,u in zip(weights,(0.,1.)) if w>0)
+                    return result, 'finite_bayes' if not meta['numerical_rectangle'] else 'numerical_rectangle', 0., meta
+                gaussian = self.confounder_family == 'normal' and self.confounder_function == 'linear'
+                center, scale = 0., 1.
+                if gaussian:
+                    scale = 1/np.sqrt(1+meta['information'])
+                    center = meta['score']*scale**2
+                    if latent_function is None and type(self.f_Y) is OutcomeMechanism and self.f_Y.family == 'gaussian':
+                        posterior_mean,numerical=meta['gaussian_mean']()
+                        meta['numerical_rectangle']=numerical
+                        method=('numerical_truncated_gaussian' if numerical else
+                                'analytic_gaussian' if meta['continuous_only'] else 'analytic_truncated_gaussian')
+                        return arm_means(posterior_mean),method,0.,meta
+                def log_target(z):
+                    u = float(_latent(np.array(z),self.confounder_family,self.confounder_options))
+                    return likelihood(_effect(u,self.confounder_function))-.5*z*z
+                peaks = [center]
+                if not gaussian or not meta['continuous_only']:
+                    grid = np.unique(np.r_[np.linspace(-12.,12.,49), center+scale*np.array([-4.,-1.,0.,1.,4.])])
+                    values = np.array([log_target(z) for z in grid])
+                    _require(np.isfinite(values).any(), 'X has zero or numerically unresolved likelihood.')
+                    peaks = []
+                    for j in range(1,len(grid)-1):
+                        if values[j]>=values[j-1] and values[j]>=values[j+1] and np.isfinite(values[j]):
+                            fit = minimize_scalar(lambda z:-log_target(z),bounds=(grid[j-1],grid[j+1]),method='bounded')
+                            peaks.append(float(fit.x))
+                    peaks = peaks or [float(grid[np.argmax(values)])]
+                    center = max(peaks,key=log_target)
+                    delta = 1e-3
+                    curvature = -(log_target(center+delta)-2*log_target(center)+log_target(center-delta))/delta**2
+                    if np.isfinite(curvature) and curvature>0:
+                        scale = 1/np.sqrt(curvature)
+                shift = log_target(center)
+                _require(np.isfinite(shift), 'X has zero or numerically unresolved likelihood.')
+                def integrand(t):
+                    z = center+scale*t
+                    value = log_target(z)-shift
+                    if not np.isfinite(value) or value < -745:
+                        return np.zeros(3)
+                    u = float(_latent(np.array(z),self.confounder_family,self.confounder_options))
+                    return np.exp(value)*np.r_[1.,arm_means(u)]
+                breakpoints = [0.,-1.,1.,-4.,4.]+[(p-center)/scale for p in peaks]
+                total,error,info = quad_vec(integrand,-np.inf,np.inf,points=breakpoints,
+                    epsabs=atol*.02,epsrel=rtol*.02,limit=limit,full_output=True)
+                _require(info.success and np.isfinite(total).all() and total[0]>0,
+                         'CAPO quadrature did not converge; increase max_subdivisions or relax tolerances.')
+                result = total[1:]/total[0]
+                normalized_error = float(error/total[0]*(1+np.max(np.abs(result))))
+                _require(np.all(normalized_error <= atol+rtol*np.abs(result)),
+                         'CAPO quadrature error is unresolved at the requested tolerance.')
+                return result,'numerical_quadrature',normalized_error,meta
+            result,method,error,meta = solve(budget)
+            change = 0.
+            if meta['numerical_rectangle']:
+                refined,_,refined_error,_ = solve(2*budget)
+                change = float(np.max(np.abs(refined-result)))
+                _require(np.all(np.abs(refined-result)<=atol+rtol*np.abs(refined)),
+                         'CAPO rectangle refinement did not converge; increase cdf_maxpts.')
+                result,error = refined,max(error,refined_error)
+                if method!='numerical_truncated_gaussian':
+                    method = 'numerical_rectangle_quadrature' if self.confounder_family!='bernoulli' else 'numerical_rectangle'
+            means.append(result); methods.append(method); errors.append(error); refinements.append(change)
+        result = np.asarray(means).reshape((-1,2))
+        return dict(mu0=result[:,0],mu1=result[:,1],diagnostics=dict(
+            conditioning='observed_X',methods=methods,atol=atol,rtol=rtol,
+            quadrature_error_estimates=errors,rectangle_refinement_deltas=refinements,
+            cdf_maxpts=budget,numerical_errors_certified=False))
+
+    def sample(self, n=1000, data_seed=42, start_row=0):
+        values, noise = self.scm._sample_arrays(n, data_seed, start_row, return_noise=True)
+        truth = self._truth_xu(self.f_X.encode(values['X']), values['U'], noise['Y'])
+        return {name: values[name] for name in ('X', 'A', 'Y')}, truth
+
+
+class CSCM_capo(CSCM):
+    """CSCM with directly parameterized observed-X CAPO and unchanged X/A mechanisms.
+
+    Gaussian, Bernoulli, and Poisson outcomes use a bounded latent residual
+    centered under U|X. Sampling therefore needs numerical posterior integration;
+    truth_at(X) reads the target arm networks without integration.
+    """
+
+    def __init__(self, *args, centering_options=None, **kwargs):
+        _require(kwargs.get('simpson_mode', False) is not True,
+                 'simpson_mode is supported by CSCM, not CSCM_capo.')
+        super().__init__(*args, **kwargs)
+        _require(type(self.f_X) in (SyntheticCovariates, OpenMLCovariates),
+                 'CSCM_capo requires built-in covariate likelihoods.')
+        defaults = dict(atol=1e-6, rtol=1e-5, max_subdivisions=200, cdf_maxpts=20000)
+        _require(centering_options is None or isinstance(centering_options, dict),
+                 'centering_options must be a dictionary.')
+        _require(not set(centering_options or {})-set(defaults), 'Unknown centering option.')
+        self.centering_options = dict(defaults, **(centering_options or {}))
+        self.f_Y = CAPOOutcomeMechanism(self.f_Y, self.loadings['Y'])
+        self._centering_cache = None
+        self.scm = self.scm.replace_mechanism('Y', self._generate_capo_y, ['X', 'A', 'U'])
+        self.scm._block_compatible = True
+
+    def _centering(self, x):
+        cache = self._centering_cache
+        options = self.centering_options
+        if cache is not None and cache[1] == options and np.array_equal(cache[0], x, equal_nan=True):
+            return cache[2]
+        observed = self.f_X.encode(x, return_observed=True)[0]
+        unique, inverse = np.unique(observed, axis=0, return_inverse=True)
+        result = self._observed_truth(unique, **options, latent_function=
+            lambda u: np.tanh(_effect(u, self.confounder_function)))
+        center = result['mu0'][inverse]
+        _require(np.isfinite(center).all() and (np.abs(center) <= 1).all(),
+                 'Conditional latent centering is outside [-1, 1].')
+        diagnostics = dict(result['diagnostics'])
+        for key in ('methods', 'quadrature_error_estimates', 'rectangle_refinement_deltas'):
+            diagnostics[key] = [diagnostics[key][j] for j in inverse]
+        error = np.asarray(diagnostics['quadrature_error_estimates']) + np.asarray(
+            diagnostics['rectangle_refinement_deltas'])
+        value = center, error, diagnostics
+        self._centering_cache = (np.array(x, copy=True), options.copy(), value)
+        return value
+
+    def _capo_context(self, x, u):
+        features = self.f_X.encode(x)
+        _require(np.isfinite(features).all(), 'X must encode to finite features.')
+        center, error, diagnostics = self._centering(x)
+        residual = (np.tanh(_effect(u, self.confounder_function))-center)/2
+        return self._masked(features, self.outcome_mask), residual, error, diagnostics
+
+    def _generate_capo_y(self, X, A, U, noise):
+        features, residual, _, _ = self._capo_context(X, U)
+        return self.f_Y(features, A, noise, residual=residual)
+
+    def truth_at(self, x, *, u=None, u_y=None, data_seed=None, start_row=0):
+        """Return direct mu0/mu1 targets; explicit u also returns corrected conditional truth.
+
+        Explicit-u diagnostics estimate numerical centering error, not certified
+        bounds. Outcome noise replay requires u, just as for CSCM.
+        """
+        x = np.asarray(x, dtype=float)
+        _require(x.ndim == 2 and x.shape[1] == self.d_X and not np.isinf(x).any(),
+                 f'Expected X of shape (n, {self.d_X}) without infinite values.')
+        features = self.f_X.encode(x)
+        _require(np.isfinite(features).all(), 'X must encode to finite features.')
+        outcome_features = self._masked(features, self.outcome_mask)
+        result = dict(mu0=self.f_Y.mean(outcome_features, 0), mu1=self.f_Y.mean(outcome_features, 1))
+        if u is None:
+            _require(u_y is None and data_seed is None and start_row == 0,
+                     'Observed-X CAPO averages outcome noise; omit u_y, data_seed and start_row.')
+            return result
+        u = np.broadcast_to(np.asarray(u, dtype=float), (len(x),))
+        _require(np.isfinite(u).all(), 'U must be finite.')
+        _require(self.confounder_family != 'bernoulli' or np.isin(u, (0, 1)).all(),
+                 'Bernoulli U must contain only 0 or 1.')
+        _require(u_y is None or data_seed is None, 'Supply u_y or data_seed, not both.')
+        _require(data_seed is not None or start_row == 0, 'start_row requires data_seed.')
+        if data_seed is not None:
+            u_y = self.f_U(len(x), data_seed, start_row)['U_Y']
+        if u_y is not None:
+            u_y = np.broadcast_to(np.asarray(u_y, dtype=float), (len(x),))
+            _require(np.isfinite(u_y).all(), 'U_Y must be finite.')
+        outcome_features, residual, error, diagnostics = self._capo_context(x, u)
+        effect = _effect(u, self.confounder_function)
+        propensity = (self.f_A.propensity(self._masked(features, self.treatment_mask)) if self.unconfounded else
+                      _propensity(features, effect, self.f_A, self.treatment_mask, self.loadings['A']))
+        result.update(U=u.copy(), e_xu=propensity, centering_error_estimate=error.copy())
+        for arm in (0, 1):
+            result[f'mu{arm}_xu'] = self.f_Y.conditional_mean(outcome_features, arm, residual)
+            result[f'mu{arm}_centering_error_estimate'] = np.abs(self.f_Y.residual_scale(result[f'mu{arm}']))*error/2
+            if u_y is not None:
+                result[f'Y{arm}'] = self.f_Y(outcome_features, arm, u_y, residual=residual)
+        result['diagnostics'] = dict(diagnostics, parameterization='observed_X_CAPO',
+            centering_function='tanh(g(U))', numerical_errors_certified=False)
+        return result
+
+    def sample(self, n=1000, data_seed=42, start_row=0):
+        values, noise = self.scm._sample_arrays(n, data_seed, start_row, return_noise=True)
+        truth = self.truth_at(values['X'], u=values['U'], u_y=noise['Y'])
+        # Inherited sample_episode slices each truth field by row.
+        truth.pop('diagnostics')
+        return {name: values[name] for name in ('X', 'A', 'Y')}, truth

causalscience/ENGINE_LICENSE.txt

@@ -0,0 +1,38 @@
+Engine snapshot provenance and license exceptions
+
+indexed_graph.py retains its original MIT header and separate MIT permissions.
+uca_compiler.py and uca_estimation.py originally had no confirmed upstream
+license declaration. On October 26, 2026, Yonghan Jung explicitly confirmed his
+authority to license these bundled snapshots and authorized their public
+distribution under the CausalEngine Noncommercial License 1.0 in the root LICENSE.
+This present author authorization does not assert a historical upstream license
+grant or a new MIT grant. The indexed_graph.py MIT permissions remain unchanged.
+
+The current root LICENSE applies only to material Yonghan Jung is entitled to
+license, subject to LICENSING.md. Prior valid MIT grants remain effective;
+LICENSE-MIT.txt preserves their original text without regranting the entire
+current package under MIT. Dependencies retain their own terms.
+
+ENGINE_SOURCES.json sha256 values cover canonical package source files. Prior
+pre-layout snapshot hashes and upstream_sha256 retain the original provenance.
+
+2026-10-25 local uca_estimation.py patch: feature weights use exact normalized
+minimum-L2 balance; finite weights retain the common-joint histogram/carrier
+source law and its analytic full-indicator solution. Backward regression ridge
+and source/evaluation splitting are unchanged. No upstream license is altered.
+
+2026-10-26 local uca_estimation.py patch: point-score backward regressions use
+XGBoost by default, including finite weight designs. Real-coordinate carriers
+are auxiliary Gaussian proposals; support and finite-score moments are assumed.
+Minimum-L2 weights and explicit finite/affine protocols are preserved. No
+automatic causal interval or new upstream license permission is implied.
+
+2026-10-26 local cleanup: backward fitting and one score-unit evaluation are
+extracted into private helpers without changing random draw order. Paired
+terminal-weight scores and shared-fit phase timings support a pilot comparison.
+Weight mathematics, default learners and inference claims are unchanged.
+
+2026-10-27 layout consolidation: the three engine modules now live directly in
+src/causalengine, with package-relative imports identical to the former installed
+payload. ENGINE_SOURCES.json records current hashes and preserves snapshot history.
+No algorithm or licensing terms changed.

causalscience/ENGINE_SOURCES.json

@@ -0,0 +1,47 @@
+{
+  "engine": {
+    "indexed_graph.py": {
+      "origin": "research/papers/universal_causal_adjustment/code/indexed_graph.py",
+      "sha256": "66a0dfb1042be91a47b09b2dc100faf0bbfabfef967d92698c5d06782dd47aad",
+      "license": "MIT header present",
+      "package_path": "indexed_graph.py"
+    },
+    "uca_compiler.py": {
+      "origin": "research/papers/universal_causal_adjustment/code/uca_compiler.py",
+      "sha256": "68e9ef54e131b1f330d1938f2f3e1193dfc662f9460882320d19169ca9c98320",
+      "license": "CausalEngine Noncommercial License 1.0; public distribution explicitly authorized by Yonghan Jung on 2026-10-26; no historical upstream license declaration confirmed",
+      "patch_history": [
+        {
+          "sha256": "97aee7ddfe1b41131029dc9a064dc0c64540e0e4400bda22169f233328a704c9",
+          "description": "Before 2026-10-27 layout consolidation; only local imports were namespaced."
+        }
+      ],
+      "package_path": "uca_compiler.py"
+    },
+    "uca_estimation.py": {
+      "origin": "research/papers/universal_causal_adjustment/code/uca_estimation.py",
+      "sha256": "792039f96d7a97c2cc349e20421e83a77d30c1ca216a5aa4f7d96dc83be82198",
+      "license": "CausalEngine Noncommercial License 1.0; public distribution explicitly authorized by Yonghan Jung on 2026-10-26; no historical upstream license declaration confirmed",
+      "upstream_sha256": "e0aec3d8bf12c8040c4bfdb8086835a1a806b3548e0b2d9a1fdc3fafb9ba777c",
+      "local_patch": "2026-10-26: behavior-preserving backward/evaluation helper extraction; paired terminal-weight score and shared phase timings for pilot comparison. RNG order and minimum-L2 weights unchanged.",
+      "patch_history": [
+        {
+          "sha256": "04bbbc98419c0d3c65a7393833a3cb80a17526d2a24b89ee3510bc990eb9f870",
+          "description": "2026-10-25: exact normalized minimum-L2 feature weights; finite analytic density-ratio certificate; unchanged backward regression and source designs."
+        },
+        {
+          "sha256": "a0ef078995f07407338783f8caa18ce238bc51ba59182eda68eae630898658c8",
+          "description": "2026-10-26: XGBoost backward regression for point-score execution, independent of finite/Riesz minimum-L2 weights; auxiliary real-coordinate proposals and explicit point-only inference conditions."
+        },
+        {
+          "sha256": "bd7214bc6f97993965693c7ca9796de10c74289aa2b234595770ab5fbe73fa05",
+          "description": "Before 2026-10-27 layout consolidation; only local imports were namespaced."
+        }
+      ],
+      "package_path": "uca_estimation.py"
+    }
+  },
+  "scope": "Alpha bundle; Yonghan Jung explicitly authorized public distribution of the bundled UCA snapshots on 2026-10-26 under the root CausalEngine Noncommercial License 1.0; indexed_graph.py retains MIT permissions",
+  "hash_scope": "sha256 records canonical package files under src/causalscience; source and wheel use identical relative imports. Historical snapshot hashes are retained in patch_history/upstream_sha256.",
+  "local_license_policy": "Root LICENSE applies to material Yonghan Jung is entitled to license, including the bundled UCA snapshots expressly authorized on 2026-10-26; LICENSING.md preserves prior MIT and separately licensed rights. This present authorization does not assert a historical upstream grant."
+}