cccpm 0.2.1__py3-none-any.whl

cccpm/simulation/simulate_multivariate.py

@@ -0,0 +1,252 @@
+"""
+Simulate multivariate predictors X, confounders Z, and a continuous outcome y.
+
+Data-generating process (pure confounding, no mediation):
+    Z ~ N(0, I_q)
+    X = Z A + E
+    y = X beta + Z gamma + eps
+
+- A (q x p) encodes how Z loads into columns of X (Z -> X).
+- beta (p,) encodes the direct effect of X on y (X -> y). Only a subset is nonzero.
+- gamma (q,) encodes the confounding path Z -> y.
+- E is column-correlated noise for X with optional AR(1) structure across columns.
+- eps is outcome noise for y.
+
+Author: (your name)
+"""
+
+from dataclasses import dataclass
+from typing import Dict, Any, Optional, Tuple
+
+import numpy as np
+from numpy.random import Generator
+from numpy.linalg import lstsq
+from scipy.linalg import toeplitz
+
+
+# ---------------------------------------------------------------------
+# Data container
+# ---------------------------------------------------------------------
+
+@dataclass
+class SimulationResult:
+    """
+    Container for simulated data and the generating parameters.
+
+    Attributes
+    ----------
+    X : np.ndarray, shape (n, p)
+        Predictor matrix.
+    Z : np.ndarray, shape (n, q)
+        Confounder matrix.
+    y : np.ndarray, shape (n,)
+        Continuous outcome.
+    beta : np.ndarray, shape (p,)
+        True direct effects of X on y (nonzero on a subset).
+    gamma : np.ndarray, shape (q,)
+        Effects of Z on y (confounding strength).
+    A : np.ndarray, shape (q, p)
+        Loadings from Z into X (confounding footprint inside X).
+    info : dict
+        Metadata: indices for signal features, which X columns are confounded,
+        and all simulation hyperparameters used.
+    """
+    X: np.ndarray
+    Z: np.ndarray
+    y: np.ndarray
+    beta: np.ndarray
+    gamma: np.ndarray
+    A: np.ndarray
+    info: Dict[str, Any]
+
+
+# ---------------------------------------------------------------------
+# Utilities
+# ---------------------------------------------------------------------
+
+def ar1_cov(p: int, rho: float, sigma2: float) -> np.ndarray:
+    """
+    Construct an AR(1) covariance matrix across p variables.
+
+    Var(X_j) = sigma2
+    Corr(X_j, X_{j+k}) = rho^k
+
+    Parameters
+    ----------
+    p : int
+        Number of variables (columns).
+    rho : float
+        AR(1) correlation parameter in [-1, 1].
+    sigma2 : float
+        Marginal variance for each variable.
+
+    Returns
+    -------
+    np.ndarray, shape (p, p)
+        AR(1) covariance matrix.
+    """
+    if abs(rho) < 1e-12:
+        return np.eye(p) * sigma2
+    first_col = (rho ** np.arange(p)) * sigma2
+    return toeplitz(first_col)
+
+
+def _rng(seed: Optional[int]) -> Generator:
+    """Create a NumPy Generator with a fixed seed (if provided)."""
+    return np.random.default_rng(seed)
+
+
+# ---------------------------------------------------------------------
+# Core simulator
+# ---------------------------------------------------------------------
+
+def simulate_confounders(
+    n_samples: int = 1000,           # number of samples
+    n_features: int = 50,            # number of predictors (columns of X)
+    n_confounds: int = 3,                      # number of confounders (columns of Z)
+    n_features_with_signal: int = 10,            # number of X columns with nonzero beta
+    n_confounded_features: int = 10,      # number of X columns influenced by Z (nonzero column in A)
+    beta_scale: float = 1.0,         # SD for nonzero beta entries
+    gamma_scale: float = 1.0,        # SD for entries of gamma (Z -> y strength)
+    z_to_x_strength: float = 0.7,    # typical magnitude of Z -> X loadings (A)
+    sigma_x: float = 1.0,            # SD for X-noise E
+    sigma_y: float = 1.0,            # SD for outcome noise eps
+    rho_x: float = 0.0,              # AR(1) correlation among columns of X-noise E
+    random_state: Optional[int] = 42 # RNG seed for reproducibility
+) -> SimulationResult:
+    """
+    Simulate (X, Z, y) with pure confounding (Z affects both X and y).
+
+    Model
+    -----
+    Z ~ N(0, I_q)
+    X = Z A + E,   E ~ N(0, Sigma_E) with AR(1) columns
+    y = X beta + Z gamma + eps,   eps ~ N(0, sigma_y^2 I_n)
+
+    Notes
+    -----
+    - Confounding arises when BOTH A != 0 (Z -> X) and gamma != 0 (Z -> y).
+    - If gamma_scale=0, there is no confounding even if Z strongly influences X.
+    - Only a subset of beta entries is nonzero (true signal features).
+
+    Returns
+    -------
+    SimulationResult
+        Data and parameters used to generate it, including indices of signal
+        features and which X columns are confounded.
+    """
+    rng = _rng(random_state)
+
+    # 1) Confounders: Z ~ N(0, I_q)
+    Z = rng.normal(0.0, 1.0, size=(n_samples, n_confounds))
+
+    # 2) Choose signal features and betas
+    if not (1 <= n_features_with_signal <= n_features):
+        raise ValueError(f"`num_signal` must be in [1, p]; got {n_features_with_signal} (p={n_features}).")
+    k = n_features_with_signal
+
+    signal_idx = np.arange(k)  # 0..k-1
+    beta = np.zeros(n_features)
+    beta[signal_idx] = rng.normal(0.0, beta_scale, size=k)
+
+    # 3) Choose confounded features
+    confounded_mask = np.zeros(n_features, dtype=bool)
+    confounded_mask[:n_confounded_features] = True  # first m columns are confounded
+
+    A = np.zeros((n_confounds, n_features))
+    if confounded_mask.any():
+        # Use scale / sqrt(q) so variance contribution is stable w.r.t. number of confounders
+        A[:, confounded_mask] = rng.normal(
+            loc=0.0,
+            scale=z_to_x_strength / np.sqrt(n_confounds),
+            size=(n_confounds, int(confounded_mask.sum()))
+        )
+
+    # 4) Column-correlated noise for X (optional AR(1) across columns)
+    Sigma_E = ar1_cov(p=n_features, rho=rho_x, sigma2=sigma_x ** 2)
+    E = rng.multivariate_normal(mean=np.zeros(n_features), cov=Sigma_E, size=n_samples)
+
+    # 5) Build X
+    #    Each column X_j is a linear combination of Z (via A) plus noise E_j.
+    X = Z @ A + E
+
+    # 6) Outcome y: direct X->y via beta, plus confounding Z->y via gamma
+    gamma = rng.normal(loc=0.0, scale=gamma_scale, size=n_confounds)
+    eps_y = rng.normal(loc=0.0, scale=sigma_y, size=n_samples)
+    y = X @ beta + Z @ gamma + eps_y
+
+    # 7) Metadata for inspection and downstream benchmarking
+    info: Dict[str, Any] = {
+        "n_samples": n_samples,
+        "n_features": n_features,
+        "n_confounds": n_confounds,
+        "n_features_with_signal": n_features_with_signal,
+        "signal_idx": signal_idx,                # indices where beta != 0
+        "confounded_mask": confounded_mask,      # columns of X with nonzero A
+        "n_confounded_features": n_confounded_features,
+        "beta_scale": beta_scale,
+        "gamma_scale": gamma_scale,
+        "z_to_x_strength": z_to_x_strength,
+        "sigma_x": sigma_x,
+        "sigma_y": sigma_y,
+        "rho_x": rho_x,
+        "random_state": random_state,
+    }
+
+    return SimulationResult(X=X, Z=Z, y=y, beta=beta, gamma=gamma, A=A, info=info)
+
+
+# ---------------------------------------------------------------------
+# (Optional) tiny extras that are often handy while testing
+# ---------------------------------------------------------------------
+
+def fit_ols(y: np.ndarray, X: np.ndarray, add_intercept: bool = True) -> np.ndarray:
+    """
+    Minimal OLS via least squares (useful sanity check; no regularization).
+
+    Returns
+    -------
+    np.ndarray
+        If add_intercept=True: [intercept, betas...]
+        Else: betas
+    """
+    if add_intercept:
+        X1 = np.column_stack([np.ones(X.shape[0]), X])
+        coef, *_ = lstsq(X1, y, rcond=None)
+        return coef
+    coef, *_ = lstsq(X, y, rcond=None)
+    return coef
+
+
+def residualize_against_Z(M: np.ndarray, Z: np.ndarray) -> np.ndarray:
+    """
+    Remove linear effects of Z from M (works for vector y or matrix X).
+
+    Computes residuals from OLS projection:
+        M_res = M - Proj_{[1,Z]}(M)
+
+    Parameters
+    ----------
+    M : np.ndarray
+        y (1D) or X (2D) to be residualized.
+    Z : np.ndarray, shape (n, q)
+        Confounders to regress out (intercept is added internally).
+
+    Returns
+    -------
+    np.ndarray
+        Residuals with the same shape as M.
+    """
+    n = Z.shape[0]
+    Z1 = np.column_stack([np.ones(n), Z])
+
+    if M.ndim == 1:
+        coef, *_ = lstsq(Z1, M, rcond=None)
+        return M - Z1 @ coef
+
+    if M.ndim == 2:
+        coef, *_ = lstsq(Z1, M, rcond=None)  # solves for all columns at once
+        return M - Z1 @ coef
+
+    raise ValueError("M must be a 1D vector (y) or a 2D matrix (X).")
+

cccpm/simulation/simulate_sem.py

@@ -0,0 +1,319 @@
+import numpy as np
+import pandas as pd
+from sklearn.linear_model import LinearRegression
+from sklearn.metrics import r2_score
+
+
+def _solve_rho_for_R2(r2_X_y: float, r2_X_y_given_Z: float, r2_Z_y: float,
+                      tol: float = 1e-4) -> float:
+    """
+    Find corr(X, Z) = rho that best matches the desired R2_X_y_given_Z.
+    If an exact match is impossible, return the closest achievable rho
+    and issue a warning instead of raising an error.
+    """
+    r_x = np.sqrt(r2_X_y)
+    r_z = np.sqrt(r2_Z_y)
+
+    # Special case: Z has no effect → cannot adjust X→y
+    if r2_Z_y < tol:
+        if abs(r2_X_y_given_Z - r2_X_y) > tol:
+            print(
+                f"Warning: R2_Z_y≈0, so R2_X_y_given_Z must equal R2_X_y. "
+                f"Using R2_X_y_given_Z = {r2_X_y:.4f} instead of {r2_X_y_given_Z:.4f}."
+            )
+        return 0.0
+
+    # Search over allowable rho values
+    rhos = np.linspace(-0.99, 0.99, 20001)
+    num = (r_x - rhos * r_z) ** 2
+    den = 1 - rhos**2
+    vals = num / den
+
+    # Find closest match
+    idx = np.argmin(np.abs(vals - r2_X_y_given_Z))
+    rho_best = float(rhos[idx])
+    val_best = float(vals[idx])
+
+    # If we cannot achieve exact target, warn and continue
+    if abs(val_best - r2_X_y_given_Z) > tol:
+        print(
+            f"Warning: Could not achieve R2_X_y_given_Z={r2_X_y_given_Z:.4f}. "
+            f"Closest possible value is {val_best:.4f}. Using that instead."
+        )
+
+    return rho_best
+
+
+
+def simulate_data_given_R2(
+    R2_X_y: float,
+    R2_X_y_given_Z: float,
+    R2_Z_y: float,
+    n_features: int = 100,
+    n_features_informative: int = 10,
+    n_confounds: int = 2,
+    n_samples: int = 10_000,
+    rho_informative: float = 0.5,
+    random_state: int | None = None,
+) -> pd.DataFrame:
+    """
+    Simulate data that matches specified R² relationships between a latent
+    predictor X, confounds Z, and outcome y.
+
+    Inputs (targets)
+    ----------------
+    R2_X_y : float
+        Naive R² from regressing y ~ X.
+    R2_X_y_given_Z : float
+        Unique / incremental R² from X after adjusting for all confounds Z:
+            R2_X_y_given_Z = R2(y ~ X + Z) - R2(y ~ Z).
+    R2_Z_y : float
+        Naive R² from regressing y ~ Z (all confounds jointly).
+
+    Data structure
+    --------------
+    - latent variable: true_X (standardized)
+    - confounds: conf1..confK (K = n_confounds)
+      * only conf1 is used to build the desired R² (others are noise)
+    - features: X1..Xn_features
+      * first n_features_informative are informative: correlated with true_X
+      * remaining are pure noise
+    - outcome: y (standardized)
+
+    R² logic
+    --------
+    - Naive R²(y ~ X) ≈ R2_X_y
+    - Naive R²(y ~ Z) ≈ R2_Z_y
+    - Unique R² of X given Z ≈ R2_X_y_given_Z
+      so:
+          R2_full ≈ R2_Z_y + R2_X_y_given_Z
+
+    Returns
+    -------
+    df : pandas.DataFrame
+        Columns:
+            conf1..confK
+            X1..Xn_features
+            true_X
+            y
+    """
+    rng = np.random.default_rng(random_state)
+
+    # --- basic validity checks ---
+    for name, val in [
+        ("R2_X_y", R2_X_y),
+        ("R2_X_y_given_Z", R2_X_y_given_Z),
+        ("R2_Z_y", R2_Z_y),
+    ]:
+        if not (0.0 <= val < 1.0):
+            raise ValueError(f"{name} must be in [0,1), got {val}.")
+
+    if R2_X_y_given_Z > R2_X_y + 1e-8:
+        raise ValueError(
+            "R2_X_y_given_Z cannot exceed R2_X_y (unique effect cannot be "
+            "larger than naive effect)."
+        )
+    if R2_Z_y + R2_X_y_given_Z >= 1.0:
+        raise ValueError(
+            "R2_Z_y + R2_X_y_given_Z must be < 1 (total R² cannot exceed 1)."
+        )
+    if n_features_informative > n_features:
+        raise ValueError("n_features_informative cannot be greater than n_features.")
+    if not (0.0 <= rho_informative < 1.0):
+        raise ValueError("rho_informative must be in [0, 1).")
+    if n_confounds < 1:
+        raise ValueError("n_confounds must be at least 1.")
+
+    # --- step 1: build correlation matrix for (X, Z, y) ---
+    r_x = np.sqrt(R2_X_y)
+    r_z = np.sqrt(R2_Z_y)
+
+    # Solve Corr(X, Z) = rho to match desired R2_X_y_given_Z
+    rho = _solve_rho_for_R2(R2_X_y, R2_X_y_given_Z, R2_Z_y)
+
+    # correlation matrix for [X, Z, y]
+    # order: [X, Z, y]
+    corr = np.array(
+        [
+            [1.0,  rho,  r_x],
+            [rho,  1.0,  r_z],
+            [r_x,  r_z,  1.0],
+        ]
+    )
+
+    # sanity check: positive semi-definite
+    eigvals = np.linalg.eigvalsh(corr)
+    if np.min(eigvals) < -1e-6:
+        raise ValueError(
+            "Requested R² combination leads to an invalid correlation matrix."
+        )
+
+    # --- step 2: sample (X, Z, y) as multivariate normal with this corr matrix ---
+    L = np.linalg.cholesky(corr + 1e-8 * np.eye(3))  # jitter for numeric safety
+    Z_samples = rng.normal(size=(n_samples, 3))
+    XYZ = Z_samples @ L.T
+    true_X = XYZ[:, 0]
+    Z_scalar = XYZ[:, 1]
+    y = XYZ[:, 2]
+
+    # Now:
+    #   Corr(true_X, y)^2 ≈ R2_X_y
+    #   Corr(Z_scalar, y)^2 ≈ R2_Z_y
+    # and the full regression y ~ X + Z_scalar has unique R² for X ≈ R2_X_y_given_Z.
+
+    # --- step 3: expand scalar Z into n_confounds (only conf1 matters) ---
+    conf_data = {}
+    conf_data["conf1"] = Z_scalar
+    for i in range(1, n_confounds):
+        conf_data[f"conf{i+1}"] = rng.normal(0.0, 1.0, size=n_samples)
+    conf_df = pd.DataFrame(conf_data)
+
+    # --- step 4: generate X features ---
+    # First n_features_informative are equicorrelated measures of true_X
+    # For informative features with Var=1 and pairwise corr=rho_informative:
+    #   Xj = sqrt(rho_inf)*true_X + sqrt(1-rho_inf)*N(0,1)
+    X_data = {}
+    loading = np.sqrt(rho_informative)
+    resid_sd = np.sqrt(1.0 - rho_informative)
+
+    for j in range(n_features_informative):
+        eps = rng.normal(0.0, resid_sd, size=n_samples)
+        X_data[f"X{j+1}"] = loading * true_X + eps
+
+    # Remaining features are pure noise
+    for j in range(n_features_informative, n_features):
+        X_data[f"X{j+1}"] = rng.normal(0.0, 1.0, size=n_samples)
+
+    X_df = pd.DataFrame(X_data)
+
+    # --- step 5: assemble final DataFrame ---
+    df = pd.concat([conf_df, X_df], axis=1)
+    df["true_X"] = true_X
+    df["y"] = y
+
+    return {'X': X_df.to_numpy(), 'Z': conf_df.to_numpy(), 'y': y.reshape(-1, 1), 'true_X': true_X.reshape(-1, 1)}
+
+
+def compute_r2s(sim: dict) -> dict:
+    """
+    Convenience function to empirically estimate the R² components from
+    the simulated data:
+
+        - r2_naive:      R²(y ~ true_X)
+        - r2_conf_only:  R²(y ~ all confounds)
+        - r2_full:       R²(y ~ true_X + all confounds)
+        - r2_unique_X:   r2_full - r2_conf_only
+    """
+    y = sim["y"]
+    X_naive = sim["true_X"]
+    X_conf = sim["Z"]
+
+    # Naive: y ~ true_X
+    mdl_naive = LinearRegression().fit(X_naive, y)
+    r2_naive = r2_score(y, mdl_naive.predict(X_naive))
+
+    # Confounds-only: y ~ conf1..confK
+    mdl_conf = LinearRegression().fit(X_conf, y)
+    r2_conf_only = r2_score(y, mdl_conf.predict(X_conf))
+
+    # Full: y ~ true_X + conf1..confK
+    X_full = np.column_stack([X_naive, X_conf])
+    mdl_full = LinearRegression().fit(X_full, y)
+    r2_full = r2_score(y, mdl_full.predict(X_full))
+
+    r2_unique_X = r2_full - r2_conf_only
+
+    return {
+        "r2_naive": r2_naive,
+        "r2_conf_only": r2_conf_only,
+        "r2_full": r2_full,
+        "r2_unique_X": r2_unique_X,
+    }
+
+
+def generate_four_scenarios(
+    n_features: int = 100,
+    n_features_informative: int = 10,
+    n_confounds: int = 2,
+    n_samples: int = 10_000,
+    rho_informative: float = 0.5,
+    random_state: int | None = 123,
+) -> dict[str, pd.DataFrame]:
+
+    rng = np.random.default_rng(random_state)
+    seeds = rng.integers(0, 2**32 - 1, size=4)
+
+    scenarios = {}
+
+    # 1. No confounding
+    scenarios["No Confounding Effect"] = simulate_data_given_R2(
+        R2_X_y=0.25,
+        R2_X_y_given_Z=0.25,
+        R2_Z_y=0.0,
+        n_features=n_features,
+        n_features_informative=n_features_informative,
+        n_confounds=n_confounds,
+        n_samples=n_samples,
+        rho_informative=rho_informative,
+        random_state=int(seeds[0]),
+    )
+
+    # 2. Weak/partial confounding
+    scenarios["Moderate Confounding Effect"] = simulate_data_given_R2(
+        R2_X_y=0.25,
+        R2_X_y_given_Z=0.15,
+        R2_Z_y=0.10,
+        n_features=n_features,
+        n_features_informative=n_features_informative,
+        n_confounds=n_confounds,
+        n_samples=n_samples,
+        rho_informative=rho_informative,
+        random_state=int(seeds[1]),
+    )
+
+    # 3. Full confounding
+    scenarios["Strong Confounding Effect"] = simulate_data_given_R2(
+        R2_X_y=0.25,
+        R2_X_y_given_Z=0.05,
+        R2_Z_y=0.20,
+        n_features=n_features,
+        n_features_informative=n_features_informative,
+        n_confounds=n_confounds,
+        n_samples=n_samples,
+        rho_informative=rho_informative,
+        random_state=int(seeds[2]),
+    )
+
+    # 4. No confounding but Z explains part of y
+    scenarios["No Confounding Effect But Useful Confounds"] = simulate_data_given_R2(
+        R2_X_y=0.25,
+        R2_X_y_given_Z=0.25,
+        R2_Z_y=0.25,
+        n_features=n_features,
+        n_features_informative=n_features_informative,
+        n_confounds=n_confounds,
+        n_samples=n_samples,
+        rho_informative=rho_informative,
+        random_state=int(seeds[3]),
+    )
+    return scenarios
+
+
+# -------------------------------------------------------------------
+# Example usage
+# -------------------------------------------------------------------
+if __name__ == "__main__":
+    scenarios = generate_four_scenarios(
+        n_features=100,
+        n_features_informative=10,
+        n_confounds=3,
+        n_samples=1000,
+        rho_informative=0.5,
+        random_state=43,
+    )
+
+    for name, df in scenarios.items():
+        print(f"\nScenario: {name}")
+        r2s = compute_r2s(df)
+        for k, v in r2s.items():
+            print(f"  {k}: {v:.3f}")

cccpm/simulation/simulate_simple.py

@@ -0,0 +1,37 @@
+import numpy as np
+
+
+def simulate_confounded_data_chyzhyk(link_type='direct_link',
+                                     n_samples=100, n_features=100):
+    """
+    This is code by Darya Chyzhyk et al. 2022
+    https://github.com/darya-chyzhyk/confound_prediction/blob/master/confound_prediction/data_simulation.py
+    :param link_type: str,
+        Type of the links between target and confound. Options: "no_link",
+        "direct_link", "weak_link"
+    :param n_samples: int,
+        number of samples
+    :param n_features: int,
+        number of features
+    :return:
+    """
+    np.random.seed(42)
+
+    mu, sigma = 0, 1.0  # mean and standard deviation
+    x_rand = np.random.normal(mu, sigma, [n_samples, n_features])
+    y_rand = np.random.normal(mu, sigma, n_samples)
+    z_rand = np.random.normal(mu, sigma, n_samples)
+
+    if link_type == 'no_link':
+        y = np.copy(y_rand)
+        z = 1 * y_rand + z_rand
+        X = x_rand + z.reshape(-1, 1)
+    elif link_type == 'direct_link':
+        y = np.copy(y_rand)
+        z = y_rand + z_rand
+        X = x_rand + y_rand.reshape(-1, 1) + z.reshape(-1, 1)
+    elif link_type == 'weak_link':
+        y = np.copy(y_rand)
+        z = 0.5 * y_rand + z_rand
+        X = x_rand + y_rand.reshape(-1, 1) + z.reshape(-1, 1)
+    return X, y, z.reshape(-1, 1)