cca_zoo.tree

Gradient-boosted-tree nonlinear CCA methods. Requires pip install cca-zoo[tree].

---

XGBoostCCA

XGBoostCCA(
    latent_dimensions: int = 1,
    center: bool = True,
    n_estimators: int | list[int] = 50,
    max_depth: int | list[int] = 5,
    learning_rate: float | list[float] = 0.1,
    subsample: float | list[float] = 0.8,
    colsample_bytree: float | list[float] = 0.8,
    min_child_weight: float | list[float] = 5,
    gauss_seidel: bool = True,
    random_state: int = 0,
)

Bases: TreeCCA

TreeCCA with XGBoost boosters as the per-view encoders.

See :class:TreeCCA for the shared Eckart-Young objective and Gauss-Seidel boosting recipe; this class fixes the gradient-boosting backend to XGBoost <https://xgboost.readthedocs.io/>_.

Examples:

>>> import numpy as np
>>> rng = np.random.default_rng(0)
>>> X1 = rng.standard_normal((100, 5))
>>> X2 = rng.standard_normal((100, 5))
>>> model = XGBoostCCA(latent_dimensions=2, n_estimators=10).fit([X1, X2])
>>> scores = model.transform([X1, X2])

A different tree depth and boosting budget per view:

>>> model = XGBoostCCA(
...     latent_dimensions=2, n_estimators=[10, 20], max_depth=[3, 6]
... ).fit([X1, X2])

Source code in cca_zoo/tree/_treecca.py

def __init__(
    self,
    latent_dimensions: int = 1,
    center: bool = True,
    n_estimators: int | list[int] = 50,
    max_depth: int | list[int] = 5,
    learning_rate: float | list[float] = 0.1,
    subsample: float | list[float] = 0.8,
    colsample_bytree: float | list[float] = 0.8,
    min_child_weight: float | list[float] = 5,
    gauss_seidel: bool = True,
    random_state: int = 0,
) -> None:
    super().__init__(latent_dimensions=latent_dimensions, center=center)
    self.n_estimators = n_estimators
    self.max_depth = max_depth
    self.learning_rate = learning_rate
    self.subsample = subsample
    self.colsample_bytree = colsample_bytree
    self.min_child_weight = min_child_weight
    self.gauss_seidel = gauss_seidel
    self.random_state = random_state

LightGBMCCA

LightGBMCCA(
    latent_dimensions: int = 1,
    center: bool = True,
    n_estimators: int | list[int] = 50,
    max_depth: int | list[int] = 5,
    learning_rate: float | list[float] = 0.1,
    subsample: float | list[float] = 0.8,
    colsample_bytree: float | list[float] = 0.8,
    min_child_weight: float | list[float] = 5,
    gauss_seidel: bool = True,
    random_state: int = 0,
)

Bases: TreeCCA

TreeCCA with LightGBM boosters as the per-view encoders.

See :class:TreeCCA for the shared Eckart-Young objective and Gauss-Seidel boosting recipe; this class fixes the gradient-boosting backend to LightGBM <https://lightgbm.readthedocs.io/>_, which requires the optional lightgbm package (pip install lightgbm, included in the tree extra).

Examples:

>>> import numpy as np
>>> rng = np.random.default_rng(0)
>>> X1 = rng.standard_normal((100, 5))
>>> X2 = rng.standard_normal((100, 5))
>>> model = LightGBMCCA(latent_dimensions=2, n_estimators=10).fit([X1, X2])
>>> scores = model.transform([X1, X2])

Source code in cca_zoo/tree/_treecca.py

def __init__(
    self,
    latent_dimensions: int = 1,
    center: bool = True,
    n_estimators: int | list[int] = 50,
    max_depth: int | list[int] = 5,
    learning_rate: float | list[float] = 0.1,
    subsample: float | list[float] = 0.8,
    colsample_bytree: float | list[float] = 0.8,
    min_child_weight: float | list[float] = 5,
    gauss_seidel: bool = True,
    random_state: int = 0,
) -> None:
    super().__init__(latent_dimensions=latent_dimensions, center=center)
    self.n_estimators = n_estimators
    self.max_depth = max_depth
    self.learning_rate = learning_rate
    self.subsample = subsample
    self.colsample_bytree = colsample_bytree
    self.min_child_weight = min_child_weight
    self.gauss_seidel = gauss_seidel
    self.random_state = random_state

fit

fit(views: list[ArrayLike], y: None = None) -> LightGBMCCA

Fit the model.

Args: as :meth:TreeCCA.fit.

Returns:

Name	Type	Description
self	LightGBMCCA	Fitted estimator.

Raises:

Type	Description
ValueError	If fewer than 2 views are provided.
ValueError	If views have inconsistent numbers of samples.
ImportError	If the lightgbm package is not installed.

Source code in cca_zoo/tree/_treecca.py

def fit(self, views: list[ArrayLike], y: None = None) -> LightGBMCCA:
    """Fit the model.

    Args: as :meth:`TreeCCA.fit`.

    Returns:
        self: Fitted estimator.

    Raises:
        ValueError: If fewer than 2 views are provided.
        ValueError: If views have inconsistent numbers of samples.
        ImportError: If the ``lightgbm`` package is not installed.
    """
    if not _LGBM_AVAILABLE:
        raise ImportError(
            "LightGBMCCA requires the lightgbm package. "
            "Install with: pip install lightgbm"
        )
    return super().fit(views, y)

CatBoostCCA

CatBoostCCA(
    latent_dimensions: int = 1,
    center: bool = True,
    n_estimators: int | list[int] = 50,
    max_depth: int | list[int] = 5,
    learning_rate: float | list[float] = 0.1,
    subsample: float | list[float] = 0.8,
    colsample_bytree: float | list[float] = 0.8,
    min_child_weight: float | list[float] = 5,
    gauss_seidel: bool = True,
    random_state: int = 0,
)

Bases: TreeCCA

TreeCCA with CatBoost boosters as the per-view encoders.

See :class:TreeCCA for the shared Eckart-Young objective and Gauss-Seidel boosting recipe; this class fixes the gradient-boosting backend to CatBoost <https://catboost.ai/>_, which requires the optional catboost package (pip install catboost, included in the tree extra).

Unlike :class:XGBoostCCA/:class:LightGBMCCA, which continue an existing booster in place, CatBoost has no in-place "add one tree" call: each round, every component is replaced by a freshly constructed CatBoostRegressor(iterations=1, ...) continued from the previous round's model via init_model=, using a custom loss object (:class:~cca_zoo.tree._treecca._CatBoostGradientObjective) that relays the EY gradient as CatBoost's expected (der1, der2) pair. As a consequence, fitting is markedly slower per round than :class:XGBoostCCA/:class:LightGBMCCA (CatBoost rebuilds its training pool and recomputes feature-importance statistics on every such call), a cost worth paying when CatBoost's ordered-boosting and symmetric-tree structure are themselves the point.

Examples:

>>> import numpy as np
>>> rng = np.random.default_rng(0)
>>> X1 = rng.standard_normal((100, 5))
>>> X2 = rng.standard_normal((100, 5))
>>> model = CatBoostCCA(latent_dimensions=2, n_estimators=10).fit([X1, X2])
>>> scores = model.transform([X1, X2])

Source code in cca_zoo/tree/_treecca.py

def __init__(
    self,
    latent_dimensions: int = 1,
    center: bool = True,
    n_estimators: int | list[int] = 50,
    max_depth: int | list[int] = 5,
    learning_rate: float | list[float] = 0.1,
    subsample: float | list[float] = 0.8,
    colsample_bytree: float | list[float] = 0.8,
    min_child_weight: float | list[float] = 5,
    gauss_seidel: bool = True,
    random_state: int = 0,
) -> None:
    super().__init__(latent_dimensions=latent_dimensions, center=center)
    self.n_estimators = n_estimators
    self.max_depth = max_depth
    self.learning_rate = learning_rate
    self.subsample = subsample
    self.colsample_bytree = colsample_bytree
    self.min_child_weight = min_child_weight
    self.gauss_seidel = gauss_seidel
    self.random_state = random_state

fit

fit(views: list[ArrayLike], y: None = None) -> CatBoostCCA

Fit the model.

Args: as :meth:TreeCCA.fit.

Returns:

Name	Type	Description
self	CatBoostCCA	Fitted estimator.

Raises:

Type	Description
ValueError	If fewer than 2 views are provided.
ValueError	If views have inconsistent numbers of samples.
ImportError	If the catboost package is not installed.

Source code in cca_zoo/tree/_treecca.py

def fit(self, views: list[ArrayLike], y: None = None) -> CatBoostCCA:
    """Fit the model.

    Args: as :meth:`TreeCCA.fit`.

    Returns:
        self: Fitted estimator.

    Raises:
        ValueError: If fewer than 2 views are provided.
        ValueError: If views have inconsistent numbers of samples.
        ImportError: If the ``catboost`` package is not installed.
    """
    if not _CATBOOST_AVAILABLE:
        raise ImportError(
            "CatBoostCCA requires the catboost package. "
            "Install with: pip install catboost"
        )
    return super().fit(views, y)