combatlearn 2.2.0__tar.gz → 2.4.0__tar.gz

{combatlearn-2.2.0 → combatlearn-2.4.0}/PKG-INFO

@@ -1,19 +1,24 @@
 Metadata-Version: 2.4
 Name: combatlearn
-Version: 2.2.0
+Version: 2.4.0
 Summary: Batch-effect harmonization for machine learning frameworks.
 Author-email: Ettore Rocchi <ettoreroc@gmail.com>
-License: MIT
+License-Expression: MIT
 Keywords: machine-learning,harmonization,combat,preprocessing
-Classifier: Development Status :: 3 - Alpha
+Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Science/Research
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: pandas>=1.3
 Requires-Dist: numpy>=1.21
+Requires-Dist: scipy>=1.8
 Requires-Dist: scikit-learn>=1.2
 Requires-Dist: matplotlib>=3.4
 Requires-Dist: seaborn>=0.12
@@ -23,11 +28,13 @@ Requires-Dist: umap-learn>=0.5
 Provides-Extra: dev
 Requires-Dist: pytest>=7; extra == "dev"
 Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: hypothesis>=6.0; extra == "dev"
 Requires-Dist: ruff>=0.8; extra == "dev"
 Requires-Dist: pre-commit>=3.0; extra == "dev"
 Requires-Dist: mypy>=1.0; extra == "dev"
 Requires-Dist: pandas-stubs; extra == "dev"
 Requires-Dist: statsmodels>=0.14; extra == "dev"
+Requires-Dist: inmoose>=0.7; extra == "dev"
 Provides-Extra: docs
 Requires-Dist: sphinx>=7.0.0; extra == "docs"
 Requires-Dist: pydata-sphinx-theme>=0.15.0; extra == "docs"
@@ -40,7 +47,7 @@ Dynamic: license-file
 
 [![Python versions](https://img.shields.io/badge/python-%3E%3D3.10-blue?logo=python)](https://www.python.org/)
 [![Test](https://github.com/EttoreRocchi/combatlearn/actions/workflows/test.yaml/badge.svg)](https://github.com/EttoreRocchi/combatlearn/actions/workflows/test.yaml)
-[![Documentation](https://readthedocs.org/projects/combatlearn/badge/?version=latest)](https://combatlearn.readthedocs.io)
+[![Documentation](https://app.readthedocs.org/projects/combatlearn/badge/?version=latest)](https://combatlearn.readthedocs.io)
 [![PyPI Version](https://img.shields.io/pypi/v/combatlearn?cacheSeconds=300)](https://pypi.org/project/combatlearn/)
 [![License](https://img.shields.io/github/license/EttoreRocchi/combatlearn)](https://github.com/EttoreRocchi/combatlearn/blob/main/LICENSE)
 
@@ -50,14 +57,23 @@ Dynamic: license-file
 
 **combatlearn** makes the popular _ComBat_ (and _CovBat_) batch-effect correction algorithm available for use into machine learning frameworks. It lets you harmonise high-dimensional data inside a scikit-learn `Pipeline`, so that cross-validation and grid-search automatically take batch structure into account, **without data leakage**.
 
-**Six methods**:
+**Inductive `ComBat` methods** (fit on train, apply to held-out data, cross-validation-safe):
 - `method="johnson"` - classic ComBat (Johnson _et al._, 2007)
 - `method="fortin"` - neuroComBat (Fortin _et al._, 2018)
 - `method="chen"` - CovBat (Chen _et al._, 2022)
-- `method="longitudinal"` - Longitudinal ComBat for repeated measures (Beer _et al._, 2020)
 - `method="gam"` - ComBat-GAM, nonlinear (spline) covariate effects (Pomponio _et al._, 2020)
 - `method="covbat_gam"` - CovBat with the same nonlinear covariate modeling
 
+**Inductive estimators with their own signature** (same fit/transform contract, separate classes):
+- `NestedComBat` - harmonizes over several batch variables at once (e.g. site, scanner, protocol) with optional order optimization and Gaussian-mixture grouping (Nested / OPNested / GMM ComBat, Horng _et al._, 2022)
+- `LongitudinalComBat` - repeated-measures / longitudinal designs with a per-subject random intercept (Beer _et al._, 2020). Inductive under a stricter precondition than `ComBat`: the batch **and** the subject must have been seen at fit; unseen subjects degrade to the population correction, or raise with `on_unseen_subject="error"`
+- `GLMComBat` - non-Gaussian data via a parametric GLM plus a strictly per-observation quantile map:
+  - `method="seq"` - ComBat-seq for raw RNA-seq counts, negative-binomial with a library-size offset (Zhang _et al._, 2020). Integer in, integer out
+  - `method="met"` - ComBat-met for DNA-methylation beta-values, beta regression with a logit link (Wang, 2025). Output stays strictly inside `(0, 1)`
+  - Both are **cross-validation-safe**, which no published implementation of either method offers: upstream they are whole-cohort functions
+
+**Whole-cohort (transductive)** - `combatlearn.transductive.TransductiveComBat` holds configurations that cannot be frozen at fit, namely those protecting a condition-of-interest / outcome term in the design, used as a one-shot `fit_transform`. Its principal occupants are `method="seq"` and `method="met"`, the condition-protected ComBat-seq / ComBat-met variants for differential expression and differential methylation. `method="longitudinal"` is deprecated in favor of `LongitudinalComBat`, as is `ComBat(method="longitudinal")`; both are removed in v3.0.0.
+
 ## Installation
 
 ```bash
@@ -121,6 +137,74 @@ print(f"Best CV AUROC: {grid.best_score_:.3f}")
 
 For a full example of how to use **combatlearn** see the [notebook demo](https://github.com/EttoreRocchi/combatlearn/blob/main/docs/source/demo/combatlearn_demo.ipynb)
 
+## Multiple batch variables (`NestedComBat`)
+
+When more than one technical variable needs harmonizing, `NestedComBat` applies ComBat to each in sequence. It picks the harmonization order that minimizes the residual batch effect, and can optionally add a latent Gaussian-mixture grouping. It is inductive and fits inside a `Pipeline` just like `ComBat`.
+
+```python
+import pandas as pd
+from combatlearn import NestedComBat
+
+batch = pd.DataFrame({"site": site, "scanner": scanner})  # one column per batch variable
+
+nested = NestedComBat(
+    batch=batch,
+    continuous_covariates=age,
+    discrete_covariates=diag,
+    method="fortin",      # per-step engine: "fortin"/"chen"/"gam"/"covbat_gam"
+    optimize_order=True,  # choose the order (OPNested)
+    gmm=None,             # or "batch" (+GMM) / "covariate" (-GMM)
+)
+X_corrected = nested.fit_transform(X)
+print("Harmonization order:", nested.order_)
+```
+
+## Counts and proportions (`GLMComBat`)
+
+RNA-seq counts and methylation beta-values are not Gaussian, and standardizing them destroys the structure downstream tools rely on. `GLMComBat` fits a negative-binomial GLM (`method="seq"`) or a beta regression (`method="met"`) and then maps each observation through the CDF of its own batch's fitted distribution into the corresponding quantile of a batch-free one.
+
+That quantile map is **strictly per observation** - it uses only the sample's own measurements, batch label, covariates and (for `"seq"`) library size - so the model freezes at `fit` and `transform` applies to held-out data. The published ComBat-seq and ComBat-met implementations are whole-cohort functions with no such split.
+
+```python
+from combatlearn import GLMComBat
+
+harmonizer = GLMComBat(
+    batch=batch,
+    method="seq",                 # raw integer counts; "met" for 0-1 beta-values
+    discrete_covariates=tissue,   # ordinary covariates, preserved
+    reference_batch="site_A",     # recommended under cross-validation
+)
+
+counts_corrected = harmonizer.fit_transform(counts)   # reproduces the reference exactly
+
+harmonizer.fit(counts_train)                          # ... or freeze and reuse
+counts_test_corrected = harmonizer.transform(counts_test)
+```
+
+`fit_transform` on a whole cohort is verified bit-exact against InMoose `pycombat_seq`, and to within 1e-6 against committed fixtures from the ComBat-met R package. The **inductive** path has no external reference to compare with - it is validated by its defining property, that a held-out sample is corrected identically alone or in company.
+
+If the term you want to protect *is* the supervised target of a differential analysis on the same cohort, use `TransductiveComBat(method="seq"/"met", condition=...)` instead; if it is known at intake, it is an ordinary covariate and belongs here.
+
+## Repeated measures (`LongitudinalComBat`)
+
+When the same subjects are measured more than once, `LongitudinalComBat` adds a per-subject random intercept (REML) to the Fortin model, so within-subject correlation is modeled rather than treated as noise. It keeps the `fit`/`transform` contract, so a frozen correction can be applied to later visits of subjects already in the reference cohort.
+
+```python
+from combatlearn import LongitudinalComBat
+
+harmonizer = LongitudinalComBat(
+    batch=batch,
+    subject_id=subject,        # required: one label per sample
+    time_covariate=visit,      # optional: continuous time variable
+    continuous_covariates=age,
+)
+
+X_corrected = harmonizer.fit_transform(X)          # whole cohort in one pass
+X_new = harmonizer.fit(X_ref).transform(X_visits)  # or freeze and apply
+```
+
+Its precondition is one step stricter than `ComBat`'s: `ComBat` needs the *batch* to have been seen at fit, `LongitudinalComBat` needs the *batch and the subject*. A subject unseen at fit degrades to the population correction (zero random intercept), or raises with `on_unseen_subject="error"`. The transform is leakage-free in every split - each subject's intercept is estimated from that subject's training visits only - but for cross-validated prediction on *genuinely new* subjects there is no advantage over `method="fortin"`; the payoff is incremental harmonization of returning subjects.
+
 ## `ComBat` parameters
 
 The following section provides a detailed explanation of all parameters available in the scikit-learn-compatible `ComBat` class. For complete API documentation, see the [API Reference](https://combatlearn.readthedocs.io/en/latest/api/).
@@ -139,11 +223,11 @@ The following section provides a detailed explanation of all parameters availabl
 
 | Parameter | Type | Default | Description |
 | --- | --- | --- | --- |
-| `method` | str | `"johnson"` | ComBat method to use: <ul><li>`"johnson"` - Classical ComBat (_Johnson et al. 2007_)</li><li>`"fortin"` - ComBat with covariates (_Fortin et al. 2018_)</li><li>`"chen"` - CovBat, PCA-based correction (_Chen et al. 2022_)</li><li>`"longitudinal"` - Longitudinal ComBat with a per-subject random intercept (_Beer et al. 2020_)</li><li>`"gam"` - ComBat-GAM, nonlinear (spline) covariates (_Pomponio et al. 2020_)</li><li>`"covbat_gam"` - CovBat with the same nonlinear covariate modeling</li></ul> Case- and separator-insensitive literature aliases are also accepted (e.g. `"covbat"`, `"neurocombat"`, `"combat_gam"`). |
-| `parametric` | bool | `True` | Whether to use the **parametric empirical Bayes** formulation. If `False`, a non-parametric iterative scheme is used. |
-| `mean_only` | bool | `False` | If `True`, only the **mean** is corrected, while variances are left unchanged. Useful for preserving variance structure in the data. |
+| `method` | str | `"johnson"` | ComBat method to use: <ul><li>`"johnson"` - Classical ComBat (_Johnson et al. 2007_)</li><li>`"fortin"` - ComBat with covariates (_Fortin et al. 2018_)</li><li>`"chen"` - CovBat, PCA-based correction (_Chen et al. 2022_)</li><li>`"longitudinal"` - Longitudinal ComBat with a per-subject random intercept (_Beer et al. 2020_); **deprecated**, use `combatlearn.LongitudinalComBat`</li><li>`"gam"` - ComBat-GAM, nonlinear (spline) covariates (_Pomponio et al. 2020_)</li><li>`"covbat_gam"` - CovBat with the same nonlinear covariate modeling</li></ul> Case- and separator-insensitive literature aliases are also accepted (e.g. `"covbat"`, `"neurocombat"`, `"combat_gam"`). |
+| `parametric` | bool | `True` | Whether to use the **parametric empirical Bayes** formulation. If `False`, the non-parametric estimate of `sva::ComBat` (`int.eprior`) is used, whose cost grows with the square of the number of features. |
+| `mean_only` | bool | `False` | If `True`, only the **mean** is corrected, while variances are left unchanged. Useful for preserving variance structure in the data. For `"chen"` and `"covbat_gam"` it applies to the ComBat step only; the covariance step still harmonizes the PC-score variances. |
 | `reference_batch` | str or `None` | `None` | If specified, acts as a reference batch - other batches will be corrected to match this one. |
-| `covbat_cov_thresh` | float, int | `0.9` | For `"chen"` method only: Cumulative variance threshold in `(0, 1]` to retain PCs in PCA space (e.g., 0.9 = retain 90% explained variance). If an integer is provided, it represents the number of principal components to use. |
+| `covbat_cov_thresh` | float, int | `0.9` | For the `"chen"` and `"covbat_gam"` methods (also inside `NestedComBat`): Cumulative variance threshold in `(0, 1]` to retain PCs in PCA space (e.g., 0.9 = retain 90% explained variance). If an integer is provided, it represents the number of principal components to use. |
 | `smooth_terms` | list of str or int, or `None` | `None` | For `"gam"`/`"covbat_gam"` only: continuous covariates to model nonlinearly with B-splines, by column name or integer position. `None` smooths all continuous covariates. |
 | `spline_df` | int | `10` | For the GAM methods: B-spline degrees of freedom (basis functions) per smooth term. |
 | `spline_degree` | int | `3` | For the GAM methods: B-spline degree (3 = cubic). |
@@ -205,3 +289,7 @@ Please consider citing the original papers:
 - [**Longitudinal ComBat**](https://github.com/jcbeer/longCombat) - Beer JC et al. _Neuroimage_. 2020. doi: [10.1016/j.neuroimage.2020.117129](https://doi.org/10.1016/j.neuroimage.2020.117129)
 
 - [**ComBat-GAM**](https://github.com/rpomponio/neuroHarmonize) - Pomponio R et al. _Neuroimage_. 2020. doi: [10.1016/j.neuroimage.2019.116450](https://doi.org/10.1016/j.neuroimage.2019.116450)
+
+- [**ComBat-seq**](https://github.com/zhangyuqing/ComBat-seq) - Zhang Y, Parmigiani G, Johnson WE. _NAR Genom Bioinform_. 2020. doi: [10.1093/nargab/lqaa078](https://doi.org/10.1093/nargab/lqaa078)
+
+- [**ComBat-met**](https://github.com/JmWangBio/ComBatMet) - Wang J. _NAR Genom Bioinform_. 2025. doi: [10.1093/nargab/lqaf062](https://doi.org/10.1093/nargab/lqaf062)

{combatlearn-2.2.0 → combatlearn-2.4.0}/README.md

@@ -2,7 +2,7 @@
 
 [![Python versions](https://img.shields.io/badge/python-%3E%3D3.10-blue?logo=python)](https://www.python.org/)
 [![Test](https://github.com/EttoreRocchi/combatlearn/actions/workflows/test.yaml/badge.svg)](https://github.com/EttoreRocchi/combatlearn/actions/workflows/test.yaml)
-[![Documentation](https://readthedocs.org/projects/combatlearn/badge/?version=latest)](https://combatlearn.readthedocs.io)
+[![Documentation](https://app.readthedocs.org/projects/combatlearn/badge/?version=latest)](https://combatlearn.readthedocs.io)
 [![PyPI Version](https://img.shields.io/pypi/v/combatlearn?cacheSeconds=300)](https://pypi.org/project/combatlearn/)
 [![License](https://img.shields.io/github/license/EttoreRocchi/combatlearn)](https://github.com/EttoreRocchi/combatlearn/blob/main/LICENSE)
 
@@ -12,14 +12,23 @@
 
 **combatlearn** makes the popular _ComBat_ (and _CovBat_) batch-effect correction algorithm available for use into machine learning frameworks. It lets you harmonise high-dimensional data inside a scikit-learn `Pipeline`, so that cross-validation and grid-search automatically take batch structure into account, **without data leakage**.
 
-**Six methods**:
+**Inductive `ComBat` methods** (fit on train, apply to held-out data, cross-validation-safe):
 - `method="johnson"` - classic ComBat (Johnson _et al._, 2007)
 - `method="fortin"` - neuroComBat (Fortin _et al._, 2018)
 - `method="chen"` - CovBat (Chen _et al._, 2022)
-- `method="longitudinal"` - Longitudinal ComBat for repeated measures (Beer _et al._, 2020)
 - `method="gam"` - ComBat-GAM, nonlinear (spline) covariate effects (Pomponio _et al._, 2020)
 - `method="covbat_gam"` - CovBat with the same nonlinear covariate modeling
 
+**Inductive estimators with their own signature** (same fit/transform contract, separate classes):
+- `NestedComBat` - harmonizes over several batch variables at once (e.g. site, scanner, protocol) with optional order optimization and Gaussian-mixture grouping (Nested / OPNested / GMM ComBat, Horng _et al._, 2022)
+- `LongitudinalComBat` - repeated-measures / longitudinal designs with a per-subject random intercept (Beer _et al._, 2020). Inductive under a stricter precondition than `ComBat`: the batch **and** the subject must have been seen at fit; unseen subjects degrade to the population correction, or raise with `on_unseen_subject="error"`
+- `GLMComBat` - non-Gaussian data via a parametric GLM plus a strictly per-observation quantile map:
+  - `method="seq"` - ComBat-seq for raw RNA-seq counts, negative-binomial with a library-size offset (Zhang _et al._, 2020). Integer in, integer out
+  - `method="met"` - ComBat-met for DNA-methylation beta-values, beta regression with a logit link (Wang, 2025). Output stays strictly inside `(0, 1)`
+  - Both are **cross-validation-safe**, which no published implementation of either method offers: upstream they are whole-cohort functions
+
+**Whole-cohort (transductive)** - `combatlearn.transductive.TransductiveComBat` holds configurations that cannot be frozen at fit, namely those protecting a condition-of-interest / outcome term in the design, used as a one-shot `fit_transform`. Its principal occupants are `method="seq"` and `method="met"`, the condition-protected ComBat-seq / ComBat-met variants for differential expression and differential methylation. `method="longitudinal"` is deprecated in favor of `LongitudinalComBat`, as is `ComBat(method="longitudinal")`; both are removed in v3.0.0.
+
 ## Installation
 
 ```bash
@@ -83,6 +92,74 @@ print(f"Best CV AUROC: {grid.best_score_:.3f}")
 
 For a full example of how to use **combatlearn** see the [notebook demo](https://github.com/EttoreRocchi/combatlearn/blob/main/docs/source/demo/combatlearn_demo.ipynb)
 
+## Multiple batch variables (`NestedComBat`)
+
+When more than one technical variable needs harmonizing, `NestedComBat` applies ComBat to each in sequence. It picks the harmonization order that minimizes the residual batch effect, and can optionally add a latent Gaussian-mixture grouping. It is inductive and fits inside a `Pipeline` just like `ComBat`.
+
+```python
+import pandas as pd
+from combatlearn import NestedComBat
+
+batch = pd.DataFrame({"site": site, "scanner": scanner})  # one column per batch variable
+
+nested = NestedComBat(
+    batch=batch,
+    continuous_covariates=age,
+    discrete_covariates=diag,
+    method="fortin",      # per-step engine: "fortin"/"chen"/"gam"/"covbat_gam"
+    optimize_order=True,  # choose the order (OPNested)
+    gmm=None,             # or "batch" (+GMM) / "covariate" (-GMM)
+)
+X_corrected = nested.fit_transform(X)
+print("Harmonization order:", nested.order_)
+```
+
+## Counts and proportions (`GLMComBat`)
+
+RNA-seq counts and methylation beta-values are not Gaussian, and standardizing them destroys the structure downstream tools rely on. `GLMComBat` fits a negative-binomial GLM (`method="seq"`) or a beta regression (`method="met"`) and then maps each observation through the CDF of its own batch's fitted distribution into the corresponding quantile of a batch-free one.
+
+That quantile map is **strictly per observation** - it uses only the sample's own measurements, batch label, covariates and (for `"seq"`) library size - so the model freezes at `fit` and `transform` applies to held-out data. The published ComBat-seq and ComBat-met implementations are whole-cohort functions with no such split.
+
+```python
+from combatlearn import GLMComBat
+
+harmonizer = GLMComBat(
+    batch=batch,
+    method="seq",                 # raw integer counts; "met" for 0-1 beta-values
+    discrete_covariates=tissue,   # ordinary covariates, preserved
+    reference_batch="site_A",     # recommended under cross-validation
+)
+
+counts_corrected = harmonizer.fit_transform(counts)   # reproduces the reference exactly
+
+harmonizer.fit(counts_train)                          # ... or freeze and reuse
+counts_test_corrected = harmonizer.transform(counts_test)
+```
+
+`fit_transform` on a whole cohort is verified bit-exact against InMoose `pycombat_seq`, and to within 1e-6 against committed fixtures from the ComBat-met R package. The **inductive** path has no external reference to compare with - it is validated by its defining property, that a held-out sample is corrected identically alone or in company.
+
+If the term you want to protect *is* the supervised target of a differential analysis on the same cohort, use `TransductiveComBat(method="seq"/"met", condition=...)` instead; if it is known at intake, it is an ordinary covariate and belongs here.
+
+## Repeated measures (`LongitudinalComBat`)
+
+When the same subjects are measured more than once, `LongitudinalComBat` adds a per-subject random intercept (REML) to the Fortin model, so within-subject correlation is modeled rather than treated as noise. It keeps the `fit`/`transform` contract, so a frozen correction can be applied to later visits of subjects already in the reference cohort.
+
+```python
+from combatlearn import LongitudinalComBat
+
+harmonizer = LongitudinalComBat(
+    batch=batch,
+    subject_id=subject,        # required: one label per sample
+    time_covariate=visit,      # optional: continuous time variable
+    continuous_covariates=age,
+)
+
+X_corrected = harmonizer.fit_transform(X)          # whole cohort in one pass
+X_new = harmonizer.fit(X_ref).transform(X_visits)  # or freeze and apply
+```
+
+Its precondition is one step stricter than `ComBat`'s: `ComBat` needs the *batch* to have been seen at fit, `LongitudinalComBat` needs the *batch and the subject*. A subject unseen at fit degrades to the population correction (zero random intercept), or raises with `on_unseen_subject="error"`. The transform is leakage-free in every split - each subject's intercept is estimated from that subject's training visits only - but for cross-validated prediction on *genuinely new* subjects there is no advantage over `method="fortin"`; the payoff is incremental harmonization of returning subjects.
+
 ## `ComBat` parameters
 
 The following section provides a detailed explanation of all parameters available in the scikit-learn-compatible `ComBat` class. For complete API documentation, see the [API Reference](https://combatlearn.readthedocs.io/en/latest/api/).
@@ -101,11 +178,11 @@ The following section provides a detailed explanation of all parameters availabl
 
 | Parameter | Type | Default | Description |
 | --- | --- | --- | --- |
-| `method` | str | `"johnson"` | ComBat method to use: <ul><li>`"johnson"` - Classical ComBat (_Johnson et al. 2007_)</li><li>`"fortin"` - ComBat with covariates (_Fortin et al. 2018_)</li><li>`"chen"` - CovBat, PCA-based correction (_Chen et al. 2022_)</li><li>`"longitudinal"` - Longitudinal ComBat with a per-subject random intercept (_Beer et al. 2020_)</li><li>`"gam"` - ComBat-GAM, nonlinear (spline) covariates (_Pomponio et al. 2020_)</li><li>`"covbat_gam"` - CovBat with the same nonlinear covariate modeling</li></ul> Case- and separator-insensitive literature aliases are also accepted (e.g. `"covbat"`, `"neurocombat"`, `"combat_gam"`). |
-| `parametric` | bool | `True` | Whether to use the **parametric empirical Bayes** formulation. If `False`, a non-parametric iterative scheme is used. |
-| `mean_only` | bool | `False` | If `True`, only the **mean** is corrected, while variances are left unchanged. Useful for preserving variance structure in the data. |
+| `method` | str | `"johnson"` | ComBat method to use: <ul><li>`"johnson"` - Classical ComBat (_Johnson et al. 2007_)</li><li>`"fortin"` - ComBat with covariates (_Fortin et al. 2018_)</li><li>`"chen"` - CovBat, PCA-based correction (_Chen et al. 2022_)</li><li>`"longitudinal"` - Longitudinal ComBat with a per-subject random intercept (_Beer et al. 2020_); **deprecated**, use `combatlearn.LongitudinalComBat`</li><li>`"gam"` - ComBat-GAM, nonlinear (spline) covariates (_Pomponio et al. 2020_)</li><li>`"covbat_gam"` - CovBat with the same nonlinear covariate modeling</li></ul> Case- and separator-insensitive literature aliases are also accepted (e.g. `"covbat"`, `"neurocombat"`, `"combat_gam"`). |
+| `parametric` | bool | `True` | Whether to use the **parametric empirical Bayes** formulation. If `False`, the non-parametric estimate of `sva::ComBat` (`int.eprior`) is used, whose cost grows with the square of the number of features. |
+| `mean_only` | bool | `False` | If `True`, only the **mean** is corrected, while variances are left unchanged. Useful for preserving variance structure in the data. For `"chen"` and `"covbat_gam"` it applies to the ComBat step only; the covariance step still harmonizes the PC-score variances. |
 | `reference_batch` | str or `None` | `None` | If specified, acts as a reference batch - other batches will be corrected to match this one. |
-| `covbat_cov_thresh` | float, int | `0.9` | For `"chen"` method only: Cumulative variance threshold in `(0, 1]` to retain PCs in PCA space (e.g., 0.9 = retain 90% explained variance). If an integer is provided, it represents the number of principal components to use. |
+| `covbat_cov_thresh` | float, int | `0.9` | For the `"chen"` and `"covbat_gam"` methods (also inside `NestedComBat`): Cumulative variance threshold in `(0, 1]` to retain PCs in PCA space (e.g., 0.9 = retain 90% explained variance). If an integer is provided, it represents the number of principal components to use. |
 | `smooth_terms` | list of str or int, or `None` | `None` | For `"gam"`/`"covbat_gam"` only: continuous covariates to model nonlinearly with B-splines, by column name or integer position. `None` smooths all continuous covariates. |
 | `spline_df` | int | `10` | For the GAM methods: B-spline degrees of freedom (basis functions) per smooth term. |
 | `spline_degree` | int | `3` | For the GAM methods: B-spline degree (3 = cubic). |
@@ -166,4 +243,8 @@ Please consider citing the original papers:
 
 - [**Longitudinal ComBat**](https://github.com/jcbeer/longCombat) - Beer JC et al. _Neuroimage_. 2020. doi: [10.1016/j.neuroimage.2020.117129](https://doi.org/10.1016/j.neuroimage.2020.117129)
 
-- [**ComBat-GAM**](https://github.com/rpomponio/neuroHarmonize) - Pomponio R et al. _Neuroimage_. 2020. doi: [10.1016/j.neuroimage.2019.116450](https://doi.org/10.1016/j.neuroimage.2019.116450)
+- [**ComBat-GAM**](https://github.com/rpomponio/neuroHarmonize) - Pomponio R et al. _Neuroimage_. 2020. doi: [10.1016/j.neuroimage.2019.116450](https://doi.org/10.1016/j.neuroimage.2019.116450)
+
+- [**ComBat-seq**](https://github.com/zhangyuqing/ComBat-seq) - Zhang Y, Parmigiani G, Johnson WE. _NAR Genom Bioinform_. 2020. doi: [10.1093/nargab/lqaa078](https://doi.org/10.1093/nargab/lqaa078)
+
+- [**ComBat-met**](https://github.com/JmWangBio/ComBatMet) - Wang J. _NAR Genom Bioinform_. 2025. doi: [10.1093/nargab/lqaf062](https://doi.org/10.1093/nargab/lqaf062)

combatlearn-2.4.0/combatlearn/__init__.py

@@ -0,0 +1,6 @@
+from .glm import GLMComBat
+from .sklearn_api import ComBat, LongitudinalComBat, NestedComBat
+
+__all__ = ["ComBat", "GLMComBat", "LongitudinalComBat", "NestedComBat"]
+__version__ = "2.4.0"
+__author__ = "Ettore Rocchi"

{combatlearn-2.2.0 → combatlearn-2.4.0}/combatlearn/_mixed.py

@@ -1,23 +1,8 @@
-"""Random-intercept linear mixed model fitting for Longitudinal ComBat.
+"""Random-intercept linear mixed model, fit by REML, for Longitudinal ComBat.
 
-Fits, for every feature (column of ``Y``) simultaneously, the model
-
-    y = X @ beta + Z @ u + eps,    u ~ N(0, tau^2 I),   eps ~ N(0, sigma^2 I)
-
-where ``Z`` is the subject (random-intercept) indicator matrix. Estimation is
-by REML, profiling out ``beta`` and ``sigma^2`` so that only the scalar
-variance ratio ``lambda = tau^2 / sigma^2`` is optimized per feature.
-
-The single random-intercept grouping makes the marginal covariance
-``V = sigma^2 (I + lambda Z Z^T)`` block diagonal (one block per subject), so
-``V^{-1}`` is available in closed form via Sherman-Morrison and every operation
-is O(n) per feature. The variance ratio is found by a vectorized grid search
-over ``lambda`` followed by a parabolic refinement, after which the fixed
-effects, residual variance, and random-intercept BLUPs are computed in a single
-per-feature pass.
-
-This keeps Longitudinal ComBat dependency-free (numpy only); correctness is
-cross-checked against ``statsmodels.MixedLM`` in the test suite.
+Fits ``y = X beta + Z u + eps`` per feature, profiling out ``beta`` and ``sigma^2``
+so only ``lambda = tau^2 / sigma^2`` is searched; the block-diagonal covariance is
+inverted in O(n) via Sherman-Morrison.
 """
 
 from __future__ import annotations
@@ -84,6 +69,8 @@ def fit_random_intercept(
 ) -> tuple[FloatArray, FloatArray, FloatArray, FloatArray]:
     """Fit a random-intercept LME per feature by REML.
 
+    ``lambda`` is found by a log-spaced grid search refined by a parabolic step.
+
     Parameters
     ----------
     X : ndarray of shape (n, p)
@@ -120,7 +107,6 @@ def fit_random_intercept(
     n_features = Y.shape[1]
     ridge = eps * float(np.trace(X.T @ X)) / max(p, 1)
 
-    # Vectorized grid search for the variance ratio (per feature).
     log_grid = np.linspace(-4.0, 4.0, n_grid)
     lam_grid = np.concatenate([[0.0], 10.0**log_grid])
     fvals = np.empty((lam_grid.size, n_features), dtype=np.float64)
@@ -129,7 +115,6 @@ def fit_random_intercept(
     best = np.argmin(fvals, axis=0)
     lam_opt = lam_grid[best].astype(np.float64)
 
-    # Vectorized parabolic refinement (log10 space) for interior positive optima.
     interior = (best >= 2) & (best <= n_grid - 1)
     if np.any(interior):
         bi = best[interior]
@@ -142,7 +127,6 @@ def fit_random_intercept(
         step = log_grid[1] - log_grid[0]
         lam_opt[interior] = 10.0 ** (log_grid[bi - 1] + delta * step)
 
-    # Final per-feature fixed effects, residual variance, and random-intercept BLUPs.
     beta = np.empty((p, n_features), dtype=np.float64)
     sigma2 = np.empty(n_features, dtype=np.float64)
     blup = np.zeros((n_groups, n_features), dtype=np.float64)