wrapevofs 0.2.0__py3-none-any.whl

wrapevofs/__init__.py

@@ -0,0 +1,63 @@
+"""Public API for wrapevofs."""
+
+from wrapevofs._version import (
+    ARTIFACT_SCHEMA_VERSION,
+    CONFIG_SCHEMA_VERSION,
+    __version__,
+)
+
+from wrapevofs.config import (
+    BorutaRFWrapperConfig,
+    FirstStageConfig,
+    GAConfig,
+    LockingConfig,
+    PipelineConfig,
+    PreprocessingConfig,
+    RFECVConfig,
+    ScoringConfig,
+    SplitConfig,
+    SVML1WrapperConfig,
+    XGBoostWrapperConfig,
+)
+from wrapevofs.pipeline import WrapEvoPipeline, PipelineResult, PreparedData
+from wrapevofs.locking import (
+    LockingCandidate,
+    LockingResult,
+    lock_representative_run,
+    score_candidate_feature_sets,
+)
+from wrapevofs.preprocessing import TabularPreprocessor
+from wrapevofs.validation import validate_locking_artifact_directory
+from wrapevofs.selectors.genetic_rf import GASolution, GeneticRFResult, run_genetic_rf
+from wrapevofs.split import parse_split_ratio, train_test_split_frame
+
+__all__ = [
+    "ARTIFACT_SCHEMA_VERSION",
+    "BorutaRFWrapperConfig",
+    "CONFIG_SCHEMA_VERSION",
+    "FirstStageConfig",
+    "GAConfig",
+    "LockingConfig",
+    "LockingCandidate",
+    "LockingResult",
+    "GASolution",
+    "WrapEvoPipeline",
+    "GeneticRFResult",
+    "PipelineConfig",
+    "PipelineResult",
+    "PreparedData",
+    "PreprocessingConfig",
+    "RFECVConfig",
+    "ScoringConfig",
+    "SVML1WrapperConfig",
+    "SplitConfig",
+    "TabularPreprocessor",
+    "XGBoostWrapperConfig",
+    "parse_split_ratio",
+    "train_test_split_frame",
+    "validate_locking_artifact_directory",
+    "run_genetic_rf",
+    "lock_representative_run",
+    "score_candidate_feature_sets",
+    "__version__",
+]

wrapevofs/_scoring.py

@@ -0,0 +1,35 @@
+"""Scoring helpers shared by wrapper and RFECV selectors."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import numpy as np
+
+
+def unique_classes(y: Any) -> np.ndarray:
+    """Return sorted unique class labels from a pandas or numpy target vector."""
+
+    values = y.to_numpy() if hasattr(y, "to_numpy") else y
+    return np.unique(np.asarray(values))
+
+
+def infer_problem_type(y: Any) -> str:
+    """Infer whether a classification target is binary or multiclass."""
+
+    classes = unique_classes(y)
+    return "binary" if len(classes) <= 2 else "multiclass"
+
+
+def resolve_auto_scoring(
+    scoring: str,
+    y: Any,
+    *,
+    binary: str,
+    multiclass: str,
+) -> str:
+    """Resolve ``scoring='auto'`` from the observed number of target classes."""
+
+    if scoring != "auto":
+        return scoring
+    return binary if infer_problem_type(y) == "binary" else multiclass

wrapevofs/_version.py

@@ -0,0 +1,5 @@
+"""Single-source package and artifact version constants."""
+
+__version__ = "0.2.0"
+ARTIFACT_SCHEMA_VERSION = "2.1"
+CONFIG_SCHEMA_VERSION = "1.0"

wrapevofs/artifacts.py

@@ -0,0 +1,193 @@
+"""Artifact writing helpers."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import asdict, is_dataclass
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+import pandas as pd
+
+from wrapevofs.pipeline import PipelineResult, PreparedData
+from wrapevofs._version import ARTIFACT_SCHEMA_VERSION, __version__
+
+
+def _json_default(value: Any) -> Any:
+    if is_dataclass(value):
+        return asdict(value)
+    if hasattr(value, "tolist"):
+        return value.tolist()
+    return str(value)
+
+
+def save_prepared_data(prepared: PreparedData, output_dir: str | Path) -> None:
+    output = Path(output_dir)
+    output.mkdir(parents=True, exist_ok=True)
+    prepared.X_train.to_csv(output / "X_train.csv", index=False)
+    prepared.X_test.to_csv(output / "X_test.csv", index=False)
+    prepared.y_train.to_frame("target").to_csv(output / "y_train.csv", index=False)
+    prepared.y_test.to_frame("target").to_csv(output / "y_test.csv", index=False)
+    with (output / "preprocessing_report.json").open("w", encoding="utf-8") as handle:
+        json.dump(asdict(prepared.preprocessor.report), handle, indent=2)
+
+
+def save_pipeline_result(result: PipelineResult, output_dir: str | Path) -> None:
+    output = Path(output_dir)
+    output.mkdir(parents=True, exist_ok=True)
+    with (output / "software_metadata.json").open("w", encoding="utf-8") as handle:
+        json.dump(
+            {
+                "software_name": "wrapevofs",
+                "software_version": __version__,
+                "artifact_schema_version": ARTIFACT_SCHEMA_VERSION,
+            },
+            handle,
+            indent=2,
+        )
+    save_prepared_data(result.prepared, output / "preprocessed")
+    for name, selection in result.first_stage.items():
+        method_dir = output / "first_stage" / name
+        method_dir.mkdir(parents=True, exist_ok=True)
+        selection.feature_table.to_csv(method_dir / "feature_table.csv", index=False)
+        pd.DataFrame({"feature": selection.selected_features}).to_csv(
+            method_dir / "selected_features.csv",
+            index=False,
+        )
+        np.save(
+            method_dir / "selected_features.npy",
+            np.asarray(selection.selected_features, dtype=str),
+        )
+        with (method_dir / "metadata.json").open("w", encoding="utf-8") as handle:
+            json.dump(selection.metadata, handle, indent=2, default=_json_default)
+
+    for name, target in result.rfecv_targets.items():
+        method_dir = output / "rfecv" / name
+        method_dir.mkdir(parents=True, exist_ok=True)
+        target.score_table.to_csv(method_dir / "score_table.csv", index=False)
+        summary = {
+            "target_k": target.target_k,
+            "target_score": target.target_score,
+            "global_best_k": target.global_best_k,
+            "global_best_score": target.global_best_score,
+            "selected_features_at_target": target.selected_features_at_target,
+            "metadata": target.metadata,
+        }
+        np.save(
+            method_dir / "target_features.npy",
+            np.asarray(target.selected_features_at_target, dtype=str),
+        )
+        np.save(
+            method_dir / "global_best_features.npy",
+            np.asarray(target.selected_features_at_global_best, dtype=str),
+        )
+        with (method_dir / "summary.json").open("w", encoding="utf-8") as handle:
+            json.dump(summary, handle, indent=2, default=_json_default)
+
+    final_feature_sets: dict[str, list[Any]] = {}
+    best_feature_sets: dict[str, list[str]] = {}
+    for name, ga_result in result.ga_results.items():
+        method_dir = output / "ga" / name
+        method_dir.mkdir(parents=True, exist_ok=True)
+        rows = []
+        for solution in ga_result.top_solutions:
+            rows.append(
+                {
+                    "rank": solution.rank,
+                    "run_id": solution.run_id,
+                    "score": solution.score,
+                    "base_score": solution.base_score,
+                    "n_features": solution.n_features,
+                    "selected_features": "|".join(solution.selected_features),
+                    "raw_objective": solution.raw_objective,
+                    "legacy_truncated_fitness": solution.legacy_truncated_fitness,
+                    "target_deviation": solution.target_deviation,
+                    "penalty_amount": solution.penalty_amount,
+                    "stable_mask_hash": solution.stable_mask_hash,
+                }
+            )
+        pd.DataFrame(rows).to_csv(method_dir / "top_solutions.csv", index=False)
+        if not ga_result.history.empty:
+            ga_result.history.to_csv(method_dir / "history.csv", index=False)
+        top_feature_sets = np.asarray(
+            [np.asarray(item.selected_features, dtype=str) for item in ga_result.top_solutions],
+            dtype=object,
+        )
+        top_masks = np.asarray([item.mask for item in ga_result.top_solutions], dtype=bool)
+        np.save(method_dir / "top_feature_sets.npy", top_feature_sets, allow_pickle=True)
+        np.save(method_dir / "top_masks.npy", top_masks)
+        np.save(
+            method_dir / "scores.npy",
+            np.asarray([item.score for item in ga_result.top_solutions], dtype=float),
+        )
+        if ga_result.top_solutions:
+            np.save(
+                method_dir / "best_feature_set.npy",
+                np.asarray(ga_result.best_solution.selected_features, dtype=str),
+            )
+            np.save(method_dir / "best_mask.npy", ga_result.best_solution.mask)
+            best_feature_sets[name] = ga_result.best_solution.selected_features
+            final_feature_sets[name] = [
+                solution.selected_features for solution in ga_result.top_solutions
+            ]
+        summary = {
+            "name": ga_result.name,
+            "target_k": ga_result.target_k,
+            "best_score": ga_result.best_solution.score if ga_result.top_solutions else None,
+            "best_n_features": (
+                ga_result.best_solution.n_features if ga_result.top_solutions else None
+            ),
+            "metadata": ga_result.metadata,
+            "warnings": ga_result.warnings,
+        }
+        with (method_dir / "summary.json").open("w", encoding="utf-8") as handle:
+            json.dump(summary, handle, indent=2, default=_json_default)
+
+    locked_feature_sets: dict[str, list[str]] = {}
+    for name, locking_result in result.locking_results.items():
+        method_dir = output / "locking" / name
+        method_dir.mkdir(parents=True, exist_ok=True)
+        locking_result.candidate_audit.to_csv(
+            method_dir / "locking_candidate_audit.csv",
+            index=False,
+        )
+        locking_result.pairwise_jaccard.to_csv(
+            method_dir / "pairwise_jaccard.csv",
+            index=False,
+        )
+        pd.DataFrame({"feature": locking_result.selected_features}).to_csv(
+            method_dir / "selected_features.csv",
+            index=False,
+        )
+        np.save(
+            method_dir / "selected_features.npy",
+            np.asarray(locking_result.selected_features, dtype=str),
+        )
+        with (method_dir / "summary.json").open("w", encoding="utf-8") as handle:
+            json.dump(locking_result.metadata, handle, indent=2, default=_json_default)
+        locked_feature_sets[name] = list(locking_result.selected_features)
+
+    if locked_feature_sets:
+        final_feature_sets = locked_feature_sets
+        np.save(output / "locked_feature_sets.npy", locked_feature_sets, allow_pickle=True)
+    elif not final_feature_sets:
+        if result.rfecv_targets:
+            final_feature_sets = {
+                name: target.selected_features_at_target
+                for name, target in result.rfecv_targets.items()
+            }
+        else:
+            final_feature_sets = {
+                name: selection.selected_features
+                for name, selection in result.first_stage.items()
+            }
+    if best_feature_sets:
+        np.save(output / "best_feature_sets.npy", best_feature_sets, allow_pickle=True)
+    np.save(output / "final_feature_sets.npy", final_feature_sets, allow_pickle=True)
+
+    exported_warnings = list(result.warnings)
+    for name, ga_result in result.ga_results.items():
+        exported_warnings.extend(f"{name}: {message}" for message in ga_result.warnings)
+    with (output / "warnings.json").open("w", encoding="utf-8") as handle:
+        json.dump(exported_warnings, handle, indent=2)

wrapevofs/cli.py

@@ -0,0 +1,158 @@
+"""Command-line entry point."""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+import pandas as pd
+
+from wrapevofs.artifacts import save_pipeline_result
+from wrapevofs.config import PipelineConfig
+from wrapevofs.pipeline import WrapEvoPipeline
+from wrapevofs._version import __version__
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="wrapevofs")
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    run = subparsers.add_parser("run", help="Run preprocessing through RFECV target discovery.")
+    run.add_argument("--csv", required=True, help="Input CSV containing features and target.")
+    run.add_argument("--target", required=True, help="Target column name.")
+    run.add_argument("--out", required=True, help="Output directory.")
+    run.add_argument("--config", help="YAML config path.")
+    run.add_argument("--ratio", help="Override split ratio, for example 7:3, 6:4, 8:2.")
+    run.add_argument("--impute", choices=["median", "mean", "zero"], help="Override imputation strategy.")
+    run.add_argument(
+        "--rfecv-max-features",
+        type=int,
+        help="Override RFECV compact cap for all wrapper branches.",
+    )
+    run.add_argument("--xgb-rfecv-max", type=int, help="RFECV compact cap for the xgboost branch.")
+    run.add_argument("--svm-rfecv-max", type=int, help="RFECV compact cap for the svm_l1 branch.")
+    run.add_argument("--boruta-rfecv-max", type=int, help="RFECV compact cap for the boruta_rf branch.")
+    run.add_argument("--methods", help="Comma-separated methods: svm_l1,xgboost,boruta_rf.")
+    run.add_argument("--drop-columns", help="Comma-separated non-feature columns to drop.")
+    run.add_argument(
+        "--ga-backend",
+        choices=["auto", "cpu", "gpu"],
+        help="Override GA Random Forest evaluator backend.",
+    )
+    run.add_argument(
+        "--ga-fitness-mode",
+        choices=["legacy_zero_truncated_linear", "untruncated_shifted_linear"],
+        help="GA ranking objective; archived configurations use the legacy mode.",
+    )
+    run.add_argument(
+        "--locking-strategy",
+        choices=["top_k_jaccard_medoid", "regret_constrained_medoid"],
+        help="Enable development-only representative-run locking with this strategy.",
+    )
+    run.add_argument(
+        "--locking-tolerance-mode",
+        choices=["absolute", "relative", "best_run_se_scaled", "one_se"],
+        help="Regret eligibility mode for regret-constrained locking.",
+    )
+    run.add_argument("--regret-tolerance", type=float, help="Development-CV regret tolerance.")
+    run.add_argument(
+        "--minimum-pool-size",
+        type=int,
+        help="Compatibility option; strict regret-constrained locking requires 1.",
+    )
+    run.add_argument(
+        "--unified-metric",
+        choices=["accuracy", "balanced_accuracy", "roc_auc", "macro_ovr_auroc"],
+        help="Apply one compatible metric across RFECV, GA, and locking.",
+    )
+    run.add_argument("--run-ga", action="store_true", help="Continue from RFECV target discovery into GA-RF.")
+    run.add_argument(
+        "--resume",
+        action="store_true",
+        help=(
+            "Resume GA state from each branch checkpoint directory. Fails on "
+            "missing, corrupt, version-, configuration-, feature-, or input-mismatched state."
+        ),
+    )
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    if args.command == "run":
+        config = PipelineConfig.from_yaml(args.config) if args.config else PipelineConfig()
+        if args.ratio:
+            config.split.ratio = args.ratio
+        if args.impute:
+            config.preprocessing.impute_strategy = args.impute
+        if args.rfecv_max_features is not None:
+            config.rfecv.max_features_to_consider = args.rfecv_max_features
+            for method in config.rfecv.method_max_features_to_consider:
+                config.rfecv.method_max_features_to_consider[method] = args.rfecv_max_features
+        if args.xgb_rfecv_max is not None:
+            config.rfecv.method_max_features_to_consider["xgboost"] = args.xgb_rfecv_max
+        if args.svm_rfecv_max is not None:
+            config.rfecv.method_max_features_to_consider["svm_l1"] = args.svm_rfecv_max
+        if args.boruta_rfecv_max is not None:
+            config.rfecv.method_max_features_to_consider["boruta_rf"] = args.boruta_rfecv_max
+        if args.ga_backend:
+            config.ga.backend = args.ga_backend
+        if args.ga_fitness_mode:
+            config.ga.fitness_mode = args.ga_fitness_mode
+        if args.locking_strategy:
+            config.locking.enabled = True
+            config.locking.strategy = args.locking_strategy
+        if args.locking_tolerance_mode:
+            config.locking.tolerance_mode = args.locking_tolerance_mode
+        if args.regret_tolerance is not None:
+            config.locking.regret_tolerance = args.regret_tolerance
+        if args.minimum_pool_size is not None:
+            config.locking.minimum_pool_size = args.minimum_pool_size
+        if args.unified_metric:
+            config.scoring.unified_metric = args.unified_metric
+        if args.resume:
+            if not args.run_ga:
+                raise SystemExit("--resume requires --run-ga.")
+            config.ga.resume_from_checkpoint = True
+        methods = args.methods.split(",") if args.methods else None
+        drop_columns = args.drop_columns.split(",") if args.drop_columns else None
+
+        df = pd.read_csv(args.csv)
+        output_dir = Path(args.out)
+        if args.run_ga:
+            config.ga.checkpoint_dir = str(output_dir)
+        pipeline = WrapEvoPipeline(config)
+        if args.run_ga:
+            result = pipeline.run_until_rfecv(
+                df=df,
+                target_column=args.target,
+                drop_columns=drop_columns,
+                methods=methods,
+            )
+            save_pipeline_result(result, output_dir)
+            result.ga_results = pipeline.run_ga(
+                result.prepared,
+                result.first_stage,
+                result.rfecv_targets,
+            )
+            result.locking_results = pipeline.run_locking(
+                result.prepared,
+                result.first_stage,
+                result.ga_results,
+            )
+            result.warnings = list(pipeline.warnings)
+        else:
+            result = pipeline.run_until_rfecv(
+                df=df,
+                target_column=args.target,
+                drop_columns=drop_columns,
+                methods=methods,
+            )
+        save_pipeline_result(result, output_dir)
+        return 0
+    return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())