bertuner 0.2.0__tar.gz → 0.2.2__tar.gz

{bertuner-0.2.0 → bertuner-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bertuner
-Version: 0.2.0
+Version: 0.2.2
 Summary: Hyperparameter optimization and fine-tuning for BERT-style text classifiers (Optuna + MLflow), with long-context ModernBERT support
 Author-email: elemets <alafunnell@gmail.com>
 License: MIT
@@ -109,6 +109,27 @@ Multi-label classification: pass several target columns — `target_cols=["l1",
 
 Grouped data (e.g. multiple notes per patient): pass `group_key="patient_id"` and the train/val/test split guarantees no group leaks across splits.
 
+### Using existing splits
+
+Supply `data_splits` instead of `data_path` or `dataframe` to reuse your own partitions:
+
+```python
+classifier = BERTuneClassifier(
+    models_dir="../models/",
+    text_feature="text_col",
+    target_cols=["label_col"],
+    data_splits={
+        "train": train_df,
+        "validation": validation_df,  # "val" also accepted
+        "test": test_df,
+    },
+)
+```
+
+Each value can also be a CSV path, such as `"data/train.csv"` (including `pathlib.Path` objects). All three splits must be nonempty and contain the text and target columns. Use the same numeric label encoding across all splits. Both optimization and final training preserve these partitions and their row order; no random splitting or stratification is performed. Class weights are calculated from training data, and threshold selection uses validation data.
+
+If you supply `group_key`, each split must contain that column with nonmissing IDs. Overlapping groups across splits raise an error, including in multi-label mode. Group comparisons ignore surrounding whitespace and case. Without `group_key`, checking for overlap between external partitions is the caller's responsibility; DataFrame indices are not treated as row IDs.
+
 ### Numerical-stability recovery
 
 Every attempt checks logits, loss, gradients before the optimizer step, and evaluation predictions for NaN/Inf. When a mixed-precision attempt becomes non-finite, BERTuner deletes its checkpoints, reloads the pretrained model, resets the seed, and retries the same Optuna trial and hyperparameters once in FP32. A second numerical failure prunes an optimization trial; final-model training raises `NonFiniteTrainingError`. Invalid labels, class weights, OOM errors, and other exceptions never trigger the retry.

{bertuner-0.2.0 → bertuner-0.2.2}/README.md

@@ -68,6 +68,27 @@ Multi-label classification: pass several target columns — `target_cols=["l1",
 
 Grouped data (e.g. multiple notes per patient): pass `group_key="patient_id"` and the train/val/test split guarantees no group leaks across splits.
 
+### Using existing splits
+
+Supply `data_splits` instead of `data_path` or `dataframe` to reuse your own partitions:
+
+```python
+classifier = BERTuneClassifier(
+    models_dir="../models/",
+    text_feature="text_col",
+    target_cols=["label_col"],
+    data_splits={
+        "train": train_df,
+        "validation": validation_df,  # "val" also accepted
+        "test": test_df,
+    },
+)
+```
+
+Each value can also be a CSV path, such as `"data/train.csv"` (including `pathlib.Path` objects). All three splits must be nonempty and contain the text and target columns. Use the same numeric label encoding across all splits. Both optimization and final training preserve these partitions and their row order; no random splitting or stratification is performed. Class weights are calculated from training data, and threshold selection uses validation data.
+
+If you supply `group_key`, each split must contain that column with nonmissing IDs. Overlapping groups across splits raise an error, including in multi-label mode. Group comparisons ignore surrounding whitespace and case. Without `group_key`, checking for overlap between external partitions is the caller's responsibility; DataFrame indices are not treated as row IDs.
+
 ### Numerical-stability recovery
 
 Every attempt checks logits, loss, gradients before the optimizer step, and evaluation predictions for NaN/Inf. When a mixed-precision attempt becomes non-finite, BERTuner deletes its checkpoints, reloads the pretrained model, resets the seed, and retries the same Optuna trial and hyperparameters once in FP32. A second numerical failure prunes an optimization trial; final-model training raises `NonFiniteTrainingError`. Invalid labels, class weights, OOM errors, and other exceptions never trigger the retry.

{bertuner-0.2.0 → bertuner-0.2.2}/bertuner/BERTuner.py

@@ -87,11 +87,10 @@ class BERTuneClassifier:
         retry_nonfinite_in_fp32: bool = True,
         max_grad_norm: float | None = 1.0,
         class_weight_warning_threshold: float | None = 100.0,
+        data_splits: dict[str, pd.DataFrame | str | os.PathLike] = None,
     ):
-        if data_path is None and dataframe is None:
-            raise ValueError("Provide either data_path (CSV) or dataframe, not neither.")
-        if data_path is not None and dataframe is not None:
-            raise ValueError("Provide either data_path (CSV) or dataframe, not both.")
+        if sum(source is not None for source in (data_path, dataframe, data_splits)) != 1:
+            raise ValueError("Provide exactly one of data_path (CSV), dataframe, or data_splits.")
         if precision not in {"auto", "fp32", "bf16", "fp16"}:
             raise ValueError("precision must be one of: 'auto', 'fp32', 'bf16', 'fp16'.")
         if max_grad_norm is not None and (
@@ -111,7 +110,26 @@ class BERTuneClassifier:
         self.text_feature = text_feature
         self.target_cols = target_cols
         self.seed = seed
-        self.df = pd.read_csv(data_path) if data_path is not None else dataframe.copy()
+        self._data_splits = None
+        if data_splits is not None:
+            self._data_splits = self._load_data_splits(data_splits, group_key)
+            self.df = pd.concat(self._data_splits.values(), ignore_index=True)
+        else:
+            self.df = pd.read_csv(data_path) if data_path is not None else dataframe.copy()
+        # Missing/NaN text values are coerced to empty strings so tokenization
+        # does not error on non-string inputs. Warn so callers know rows were
+        # altered rather than dropped.
+        n_missing = int(self.df[text_feature].isna().sum())
+        if n_missing:
+            warnings.warn(
+                f"{n_missing} missing (NaN) value(s) in text column "
+                f"'{text_feature}' were replaced with empty strings.",
+                stacklevel=2,
+            )
+        self.df[text_feature] = self.df[text_feature].fillna("").astype(str)
+        if self._data_splits is not None:
+            for frame in self._data_splits.values():
+                frame[text_feature] = frame[text_feature].fillna("").astype(str)
         if num_labels is not None:
             self.num_labels = num_labels
         elif self.is_multilabel:
@@ -152,7 +170,7 @@ class BERTuneClassifier:
         else:
             print(f"Logging mlflow runs locally to: {self.mlflow_uri} (no server needed)")
 
-        if self.is_multilabel and self.group_key:
+        if self.is_multilabel and self.group_key and self._data_splits is None:
             print(
                 "[WARNING] group_key is set but multi-label mode is active. "
                 "StratifiedGroupKFold does not support multi-label targets — "
@@ -462,12 +480,51 @@ class BERTuneClassifier:
     # Data preparation
     # ------------------------------------------------------------------
 
+    def _load_data_splits(self, data_splits, group_key):
+        """Copy external partitions, validating their schema and group isolation."""
+        if not isinstance(data_splits, dict):
+            raise ValueError("data_splits must be a dict with train, validation, and test keys.")
+        sources = dict(data_splits)
+        if "val" in sources and "validation" not in sources:
+            sources["validation"] = sources.pop("val")
+        if set(sources) != {"train", "validation", "test"}:
+            raise ValueError("data_splits requires exactly train, validation (or val), and test.")
+        required = [self.text_feature, *self.target_cols]
+        if group_key is not None:
+            required.append(group_key)
+        frames = {}
+        for name in ("train", "validation", "test"):
+            source = sources[name]
+            if isinstance(source, pd.DataFrame):
+                frame = source.copy()
+            elif isinstance(source, (str, os.PathLike)):
+                frame = pd.read_csv(source)
+            else:
+                raise ValueError(f"data_splits['{name}'] must be a DataFrame or CSV path.")
+            missing = [col for col in required if col not in frame.columns]
+            if missing:
+                raise ValueError(f"Split '{name}' is missing required columns: {missing}")
+            if frame.empty:
+                raise ValueError(f"Split '{name}' must not be empty.")
+            frames[name] = frame
+        if group_key is not None:
+            seen = set()
+            for name, frame in frames.items():
+                if frame[group_key].isna().any():
+                    raise ValueError(f"Split '{name}' contains missing group IDs in '{group_key}'.")
+                groups = set(frame[group_key].astype(str).str.strip().str.casefold())
+                if seen & groups:
+                    raise ValueError(f"Group leakage detected in supplied splits for '{group_key}'.")
+                seen.update(groups)
+        return frames
+
     def _prepare_datasets(self, tokenizer, group_key, max_length=512):
         """
         Splits, balances, and tokenizes data.
 
         Splitting strategy
         ------------------
+        data_splits supplied    → preserve external partitions and row order
         Multi-label + group_key  → standard split (group stratification not supported
                                    for multi-label targets; warning shown in __init__)
         Single-label + group_key → StratifiedGroupKFold split
@@ -478,7 +535,11 @@ class BERTuneClassifier:
             not self.is_multilabel and group_key is not None and group_key in self.df.columns
         )
 
-        if use_group_split:
+        if self._data_splits is not None:
+            train, val, test = (
+                self._data_splits[name] for name in ("train", "validation", "test")
+            )
+        elif use_group_split:
             self.df[group_key] = self.df[group_key].astype(str).str.strip().str.casefold()
             train, val, test = split_group_stratified(
                 self.df,

{bertuner-0.2.0 → bertuner-0.2.2}/bertuner/__init__.py

@@ -1,6 +1,6 @@
 """bertuner: hyperparameter optimization and fine-tuning for BERT-style text classifiers."""
 
-__version__ = "0.2.0"
+__version__ = "0.2.2"
 
 from bertuner.BERTuner import BERTuneClassifier
 from bertuner.Predictor import BERTunePredictor

{bertuner-0.2.0 → bertuner-0.2.2}/bertuner.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bertuner
-Version: 0.2.0
+Version: 0.2.2
 Summary: Hyperparameter optimization and fine-tuning for BERT-style text classifiers (Optuna + MLflow), with long-context ModernBERT support
 Author-email: elemets <alafunnell@gmail.com>
 License: MIT
@@ -109,6 +109,27 @@ Multi-label classification: pass several target columns — `target_cols=["l1",
 
 Grouped data (e.g. multiple notes per patient): pass `group_key="patient_id"` and the train/val/test split guarantees no group leaks across splits.
 
+### Using existing splits
+
+Supply `data_splits` instead of `data_path` or `dataframe` to reuse your own partitions:
+
+```python
+classifier = BERTuneClassifier(
+    models_dir="../models/",
+    text_feature="text_col",
+    target_cols=["label_col"],
+    data_splits={
+        "train": train_df,
+        "validation": validation_df,  # "val" also accepted
+        "test": test_df,
+    },
+)
+```
+
+Each value can also be a CSV path, such as `"data/train.csv"` (including `pathlib.Path` objects). All three splits must be nonempty and contain the text and target columns. Use the same numeric label encoding across all splits. Both optimization and final training preserve these partitions and their row order; no random splitting or stratification is performed. Class weights are calculated from training data, and threshold selection uses validation data.
+
+If you supply `group_key`, each split must contain that column with nonmissing IDs. Overlapping groups across splits raise an error, including in multi-label mode. Group comparisons ignore surrounding whitespace and case. Without `group_key`, checking for overlap between external partitions is the caller's responsibility; DataFrame indices are not treated as row IDs.
+
 ### Numerical-stability recovery
 
 Every attempt checks logits, loss, gradients before the optimizer step, and evaluation predictions for NaN/Inf. When a mixed-precision attempt becomes non-finite, BERTuner deletes its checkpoints, reloads the pretrained model, resets the seed, and retries the same Optuna trial and hyperparameters once in FP32. A second numerical failure prunes an optimization trial; final-model training raises `NonFiniteTrainingError`. Invalid labels, class weights, OOM errors, and other exceptions never trigger the retry.

{bertuner-0.2.0 → bertuner-0.2.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "bertuner"
-version = "0.2.0"
+version = "0.2.2"
 description = "Hyperparameter optimization and fine-tuning for BERT-style text classifiers (Optuna + MLflow), with long-context ModernBERT support"
 readme = "README.md"
 license = { text = "MIT" }

{bertuner-0.2.0 → bertuner-0.2.2}/tests/test_bertuner.py

@@ -85,6 +85,93 @@ class TestConstruction:
         assert clf.num_labels == 7
 
 
+class TestExternalSplits:
+    @staticmethod
+    def splits():
+        df = make_df(n=12)
+        return {"train": df.iloc[:6], "validation": df.iloc[6:9], "test": df.iloc[9:]}
+
+    @pytest.mark.parametrize("multilabel", [False, True])
+    @pytest.mark.parametrize("csv", [False, True])
+    def test_preserves_partitions_across_preparations(self, tmp_path, monkeypatch, multilabel, csv):
+        splits = self.splits()
+        targets = ["target"]
+        if multilabel:
+            targets.append("other")
+            splits = {name: frame.assign(other=1 - frame.target) for name, frame in splits.items()}
+        sources = splits
+        if csv:
+            sources = {}
+            for name, frame in splits.items():
+                sources[name] = tmp_path / f"{name}.csv"
+                frame.to_csv(sources[name], index=False)
+        clf = make_classifier(tmp_path, dataframe=None, data_splits=sources, target_cols=targets)
+        def no_split(*args, **kwargs):
+            pytest.fail("External partitions must never be split again")
+        monkeypatch.setattr("bertuner.BERTuner.train_val_test_split", no_split)
+        monkeypatch.setattr("bertuner.BERTuner.split_group_stratified", no_split)
+        def tokenizer(texts, **kwargs):
+            return {"input_ids": [[int(text.rsplit(" ", 1)[1])] for text in texts]}
+        for seed in (7, 99):
+            clf.seed = seed
+            datasets = clf._prepare_datasets(tokenizer, None)
+            for ds, frame in zip(datasets, splits.values()):
+                assert ds[:]["input_ids"].tolist() == [[i] for i in frame.index]
+                expected = frame[targets].values.tolist() if multilabel else frame.target.tolist()
+                assert ds[:]["labels"].tolist() == expected
+
+    def test_copies_inputs_and_cleans_text(self, tmp_path):
+        splits = self.splits()
+        splits["train"] = splits["train"].copy()
+        splits["train"].iloc[0, 0] = None
+        splits["val"] = splits.pop("validation")
+        with pytest.warns(UserWarning, match="missing"):
+            clf = make_classifier(tmp_path, dataframe=None, data_splits=splits)
+        assert clf._data_splits["train"].iloc[0, 0] == ""
+        assert splits["train"].iloc[0, 0] is None
+        splits["train"].iloc[1, 0] = "changed"
+        assert clf._data_splits["train"].iloc[1, 0] == "sample text 1"
+
+    @pytest.mark.parametrize("problem,match", [
+        ("missing_split", "requires exactly"),
+        ("extra_split", "requires exactly"),
+        ("empty", "must not be empty"),
+        ("column", "missing required columns"),
+        ("type", "DataFrame or CSV path"),
+    ])
+    def test_invalid_splits(self, tmp_path, problem, match):
+        splits = self.splits()
+        if problem == "missing_split":
+            splits.pop("test")
+        elif problem == "extra_split":
+            splits["val"] = splits["validation"]
+        elif problem == "empty":
+            splits["test"] = splits["test"].iloc[:0]
+        elif problem == "column":
+            splits["test"] = splits["test"].drop(columns="target")
+        else:
+            splits["test"] = None
+        with pytest.raises(ValueError, match=match):
+            make_classifier(tmp_path, dataframe=None, data_splits=splits)
+
+    def test_rejects_conflicting_sources(self, tmp_path):
+        with pytest.raises(ValueError, match="exactly one"):
+            make_classifier(tmp_path, data_splits=self.splits())
+
+    @pytest.mark.parametrize("multilabel", [False, True])
+    def test_group_validation(self, tmp_path, multilabel):
+        splits = {name: frame.assign(patient=name, other=1) for name, frame in self.splits().items()}
+        kwargs = dict(dataframe=None, data_splits=splits, group_key="patient",
+                      target_cols=["target", "other"] if multilabel else ["target"])
+        make_classifier(tmp_path, **kwargs)
+        splits["test"]["patient"] = " TRAIN "
+        with pytest.raises(ValueError, match="Group leakage"):
+            make_classifier(tmp_path, **kwargs)
+        splits["test"]["patient"] = None
+        with pytest.raises(ValueError, match="missing group IDs"):
+            make_classifier(tmp_path, **kwargs)
+
+
 class TestMlflowUri:
     def test_plain_path_becomes_file_uri(self, tmp_path):
         clf = make_classifier(tmp_path, mlflow_tracking_uri="./mlruns")