G2PInsight 1.0.2__tar.gz → 1.0.4__tar.gz

{g2pinsight-1.0.2 → g2pinsight-1.0.4}/G2PInsight/__init__.py

@@ -1,3 +1,3 @@
-__version__ = '1.0.2'
+__version__ = '1.0.4'
 __author__ = 'chenrf'
 __email__ = '12024128035@stu.ynu.edu.cn'

{g2pinsight-1.0.2 → g2pinsight-1.0.4}/G2PInsight/bin/modeltraining.py

@@ -124,7 +124,6 @@ SHAP_DEPENDENCE_MAX_FEATURES = 0
 TRAIN_SNP_WARN_THRESHOLD = 500_000
 TRAIN_SNP_STRONG_WARN_THRESHOLD = 1_000_000
 TRAIN_SVM_IMPRACTICAL_THRESHOLD = 10_000
-TRAIN_PARALLEL_BLOCK_THRESHOLD = 500_000
 
 def _resolve_shap_dependence_max_features(value: Optional[int]) -> int:
     if value is None:
@@ -303,7 +302,7 @@ def _verify_compressed_train_file(train_file: str, expected_n_samples: Optional[
         if data_rows != expected_n_samples:
             raise ValueError(f'Training matrix row count mismatch: file has {data_rows} data row(s), metadata expects {expected_n_samples} ({train_file}).\nRe-run preprocess to regenerate a complete training matrix.')
 
-def check_training_metadata_guardrails(metadata: Optional[Dict], *, model_type: Optional[str]=None, task_type: Optional[str]=None, parallel_models: Optional[int]=None, enable_hyperparameter_search: bool=True, n_folds: int=5, threads: Optional[int]=None) -> None:
+def check_training_metadata_guardrails(metadata: Optional[Dict], *, model_type: Optional[str]=None, task_type: Optional[str]=None, parallel_models: Optional[int]=None, enable_hyperparameter_search: bool=False, n_folds: int=5, threads: Optional[int]=None) -> None:
     n_features, n_samples = _training_dimensions_from_metadata(metadata)
     file_format = (metadata or {}).get('train_file_format') or {}
     is_gzip = file_format.get('compression') == 'gzip' or str((metadata or {}).get('output_train_file', '')).endswith('.gz')
@@ -326,16 +325,14 @@ def check_training_metadata_guardrails(metadata: Optional[Dict], *, model_type:
     if is_gzip:
         logger.warning('[TRAIN] Training matrix is gzip-compressed; load is slower than uncompressed .txt. Re-run preprocess without compression if you train repeatedly.')
     parallel_count = 1 if parallel_models is None else max(1, int(parallel_models))
-    if parallel_count > 1 and n_features >= TRAIN_PARALLEL_BLOCK_THRESHOLD:
-        raise ValueError(f'train-all with --parallel_models {parallel_count} is not supported when n_feature_columns={n_features:,} (>= {TRAIN_PARALLEL_BLOCK_THRESHOLD:,}).\nEach worker materializes a full copy of the matrix and commonly OOMs.\nUse --parallel_models 1 and train models serially, or reduce SNPs in preprocess (-f 2 / -f 4).')
     if parallel_count > 1 and n_features >= HIGH_DIM_FEATURE_RF_THRESHOLD:
-        logger.warning(f'[TRAIN] parallel_models={parallel_count} with {n_features:,} features: use --parallel_models 1 unless job memory is very large.')
+        logger.warning(f'[TRAIN] parallel_models={parallel_count} with {n_features:,} features: each worker holds a full matrix copy; ensure job memory is large enough or use --parallel_models 1.')
     if model_type == 'SVM' and n_features > TRAIN_SVM_IMPRACTICAL_THRESHOLD:
         logger.warning(f'[TRAIN] SVM on {n_features:,} features is usually impractical (time/memory). Prefer LightGBM for high-dimensional GWAS matrices.')
     if model_type == 'RandomForest' and n_features > HIGH_DIM_FEATURE_RF_THRESHOLD:
         logger.warning(f'[TRAIN] RandomForest on {n_features:,} features is slow at this scale; LightGBM/XGBoost are usually faster.')
     if enable_hyperparameter_search and n_features >= TRAIN_SNP_WARN_THRESHOLD:
-        logger.warning('[TRAIN] Hyperparameter search on a very wide matrix is expensive. Consider --no_hyperparameter_search for a first run.')
+        logger.warning('[TRAIN] Hyperparameter search on a very wide matrix is expensive; omit --hyperparameter_search for a faster first run.')
     if n_folds > 3 and n_features >= TRAIN_SNP_WARN_THRESHOLD:
         logger.warning(f'[TRAIN] n_folds={n_folds} multiplies full-matrix fits. Consider --n_folds 3 on high-dimensional data.')
     if threads is not None and int(threads) > 4 and n_features >= TRAIN_SNP_WARN_THRESHOLD:
@@ -1643,7 +1640,7 @@ def save_training_results(model: Any, metrics: Dict, selected_snps: List[str], o
             logger.warning(f'  Failed to save plotting metadata JSON (ignored): {e}')
     logger.info(f'  Results saved successfully: {model_dir}')
 
-def run_single_model(input_path: str, model_type: str, output_dir: str, task_type: Optional[str]=None, n_folds: int=5, random_state: int=42, preloaded_data: Optional[Dict[str, Any]]=None, cpu_cores: Optional[int]=None, enable_hyperparameter_search: bool=True, group_file: Optional[str]=None, train_ids_file: Optional[str]=None, test_ids_file: Optional[str]=None, shap_dependence_max_features: Optional[int]=None, ignore_warnings: bool=False) -> int:
+def run_single_model(input_path: str, model_type: str, output_dir: str, task_type: Optional[str]=None, n_folds: int=5, random_state: int=42, preloaded_data: Optional[Dict[str, Any]]=None, cpu_cores: Optional[int]=None, enable_hyperparameter_search: bool=False, group_file: Optional[str]=None, train_ids_file: Optional[str]=None, test_ids_file: Optional[str]=None, shap_dependence_max_features: Optional[int]=None, ignore_warnings: bool=False) -> int:
     if not str(input_path).endswith('_metadata.json'):
         raise ValueError(f'Training input must be the preprocess-generated metadata file (*_metadata.json).Current input: {input_path}')
     if preloaded_data is not None and preloaded_data.get('ignore_warnings'):
@@ -1654,7 +1651,7 @@ def run_single_model(input_path: str, model_type: str, output_dir: str, task_typ
     finally:
         _exit_train_ignore_warnings(warn_state)
 
-def _run_single_model_body(input_path: str, model_type: str, output_dir: str, task_type: Optional[str]=None, n_folds: int=5, random_state: int=42, preloaded_data: Optional[Dict[str, Any]]=None, cpu_cores: Optional[int]=None, enable_hyperparameter_search: bool=True, group_file: Optional[str]=None, train_ids_file: Optional[str]=None, test_ids_file: Optional[str]=None, shap_dependence_max_features: Optional[int]=None) -> int:
+def _run_single_model_body(input_path: str, model_type: str, output_dir: str, task_type: Optional[str]=None, n_folds: int=5, random_state: int=42, preloaded_data: Optional[Dict[str, Any]]=None, cpu_cores: Optional[int]=None, enable_hyperparameter_search: bool=False, group_file: Optional[str]=None, train_ids_file: Optional[str]=None, test_ids_file: Optional[str]=None, shap_dependence_max_features: Optional[int]=None) -> int:
     if not str(input_path).endswith('_metadata.json'):
         raise ValueError(f'Training input must be the preprocess-generated metadata file (*_metadata.json).Current input: {input_path}')
     cpu_cores_value = DEFAULT_N_JOBS if cpu_cores is None else max(1, int(cpu_cores))
@@ -1816,7 +1813,10 @@ def _run_single_model_body(input_path: str, model_type: str, output_dir: str, ta
             cv_fold_metrics, cv_oof_data, avg_metrics = _run_kfold_cv_evaluation(model_type=model_type, task_type=task_type, X_train_cv=X_train_cv, y_train_cv=y_train_cv, best_params=best_params, n_folds=n_folds, random_state=random_state, cpu_cores=cpu_cores)
             logger.info(f'{n_folds}-fold cross-validation average results (training set only):')
             logger.info(f'   {avg_metrics}')
-            logger.info('Training final model on training set with tuned hyperparameters...')
+            if enable_hyperparameter_search:
+                logger.info('Training final model on training set with tuned hyperparameters...')
+            else:
+                logger.info('Training final model on training set with default hyperparameters...')
             final_model = _fit_model_with_params(model_type=model_type, task_type=task_type, X_train=X_train_cv, y_train=y_train_cv, best_params=best_params, random_state=random_state, cpu_cores=cpu_cores)
             logger.info('Final model training completed; evaluating on held-out test set...')
             y_pred_test, y_prob_test = _predict_with_optional_proba(final_model, X_test_holdout, task_type)
@@ -1993,14 +1993,14 @@ def _run_train_all_models_serial(supported_models: List[str], input_path: str, o
         logger.warning(f'[TRAIN_ALL] {len(failed_models)} model(s) failed and were skipped: {", ".join(failed_models)}')
     return results
 
-def run_all_models(input_path: str, output_dir: str, task_type: Optional[str]=None, n_folds: int=5, random_state: int=42, parallel_models: Optional[int]=None, threads: Optional[int]=None, enable_hyperparameter_search: bool=True, group_file: Optional[str]=None, train_ids_file: Optional[str]=None, test_ids_file: Optional[str]=None, shap_dependence_max_features: Optional[int]=None, ignore_warnings: bool=False) -> int:
+def run_all_models(input_path: str, output_dir: str, task_type: Optional[str]=None, n_folds: int=5, random_state: int=42, parallel_models: Optional[int]=None, threads: Optional[int]=None, enable_hyperparameter_search: bool=False, group_file: Optional[str]=None, train_ids_file: Optional[str]=None, test_ids_file: Optional[str]=None, shap_dependence_max_features: Optional[int]=None, ignore_warnings: bool=False) -> int:
     warn_state = _enter_train_ignore_warnings(ignore_warnings)
     try:
         return _run_all_models_body(input_path=input_path, output_dir=output_dir, task_type=task_type, n_folds=n_folds, random_state=random_state, parallel_models=parallel_models, threads=threads, enable_hyperparameter_search=enable_hyperparameter_search, group_file=group_file, train_ids_file=train_ids_file, test_ids_file=test_ids_file, shap_dependence_max_features=shap_dependence_max_features, ignore_warnings=ignore_warnings)
     finally:
         _exit_train_ignore_warnings(warn_state)
 
-def _run_all_models_body(input_path: str, output_dir: str, task_type: Optional[str]=None, n_folds: int=5, random_state: int=42, parallel_models: Optional[int]=None, threads: Optional[int]=None, enable_hyperparameter_search: bool=True, group_file: Optional[str]=None, train_ids_file: Optional[str]=None, test_ids_file: Optional[str]=None, shap_dependence_max_features: Optional[int]=None, ignore_warnings: bool=False) -> int:
+def _run_all_models_body(input_path: str, output_dir: str, task_type: Optional[str]=None, n_folds: int=5, random_state: int=42, parallel_models: Optional[int]=None, threads: Optional[int]=None, enable_hyperparameter_search: bool=False, group_file: Optional[str]=None, train_ids_file: Optional[str]=None, test_ids_file: Optional[str]=None, shap_dependence_max_features: Optional[int]=None, ignore_warnings: bool=False) -> int:
     if not str(input_path).endswith('_metadata.json'):
         raise ValueError(f'Training input must be the preprocess-generated metadata file (*_metadata.json).Current input: {input_path}')
     input_info = parse_train_input_path(input_path)

{g2pinsight-1.0.2 → g2pinsight-1.0.4}/G2PInsight/main.py

@@ -209,9 +209,9 @@ def setup_argparse() -> argparse.ArgumentParser:
     train_parser.add_argument('--test-ids-file', dest='test_ids_file', default=None, help='Optional one-column sample ID file for the test set (must be used with --train-ids-file; mutually exclusive with --group-file)')
     train_parser.add_argument('--threads', type=int, default=None, help='CPU threads per model (n_jobs/thread_count and BLAS backends; default: 1)')
     train_parser.add_argument('--shap_dependence_top', type=int, default=None, help='Max SNPs saved in *_shap_dependence.tsv when feature count > 1000 (default: 0 = save all features; set e.g. 50 to cap for disk use; should be >= visualize --top_snps when capped)')
-    train_parser.add_argument('--no_hyperparameter_search', dest='hyperparameter_search', action='store_false', help='Disable RandomizedSearchCV hyperparameter grid search (default: enabled)')
+    train_parser.add_argument('--hyperparameter_search', dest='hyperparameter_search', action='store_true', help='Enable RandomizedSearchCV hyperparameter grid search (default: disabled; uses model defaults)')
     train_parser.add_argument('--ignore-warnings', dest='ignore_warnings', action='store_true', help='Suppress Python warnings and [WARNING] log messages during training (errors still shown)')
-    train_parser.set_defaults(hyperparameter_search=True, ignore_warnings=False, func=run_training)
+    train_parser.set_defaults(hyperparameter_search=False, ignore_warnings=False, func=run_training)
     train_all_parser = subparsers.add_parser('train-all', help='Train all models and compare performance (GWAS/LD filtering should be done in preprocess stage)')
     train_all_parser.add_argument('-j', '--json', required=True, help='Preprocess metadata JSON file (*_metadata.json). Training is metadata-driven; direct .txt input is not supported.')
     train_all_parser.add_argument('--task_type', required=False, choices=['classification', 'regression'], help="Task type (classification/regression). If not specified, will be automatically read from metadata or default to 'regression'")
@@ -224,9 +224,9 @@ def setup_argparse() -> argparse.ArgumentParser:
     train_all_parser.add_argument('--parallel_models', type=int, default=1, help='Number of models to train in parallel (default: 1, serial). Increase only when sufficient memory/CPU is available')
     train_all_parser.add_argument('--threads', type=int, default=None, help='CPU threads per model process (default: 1; use with care when --parallel_models > 1)')
     train_all_parser.add_argument('--shap_dependence_top', type=int, default=None, help='Max SNPs saved in *_shap_dependence.tsv when feature count > 1000 (default: 0 = save all features; set e.g. 50 to cap for disk use; should be >= visualize --top_snps when capped)')
-    train_all_parser.add_argument('--no_hyperparameter_search', dest='hyperparameter_search', action='store_false', help='Disable RandomizedSearchCV hyperparameter grid search (default: enabled)')
+    train_all_parser.add_argument('--hyperparameter_search', dest='hyperparameter_search', action='store_true', help='Enable RandomizedSearchCV hyperparameter grid search (default: disabled; uses model defaults)')
     train_all_parser.add_argument('--ignore-warnings', dest='ignore_warnings', action='store_true', help='Suppress Python warnings and [WARNING] log messages during training (errors still shown)')
-    train_all_parser.set_defaults(hyperparameter_search=True, ignore_warnings=False, func=run_train_all)
+    train_all_parser.set_defaults(hyperparameter_search=False, ignore_warnings=False, func=run_train_all)
     predict_parser = subparsers.add_parser('predict', help='Predict using trained model')
     predict_parser.add_argument('-i', '--input', required=True, help='Input data for prediction')
     predict_parser.add_argument('-m', '--model', required=True, help='Path to trained model file (.pkl), e.g. /path/to/LightGBM_model.pkl')

{g2pinsight-1.0.2 → g2pinsight-1.0.4}/G2PInsight.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: G2PInsight
-Version: 1.0.2
+Version: 1.0.4
 Summary: Genome-wide association analysis toolkit
 Author-email: chenrf <12024128035@stu.ynu.edu.cn>
 License: MIT
@@ -27,6 +27,7 @@ Requires-Dist: scikit-learn>=1.0
 Requires-Dist: scipy<2.0,>=1.7
 Requires-Dist: joblib>=1.0
 Requires-Dist: matplotlib>=3.5
+Requires-Dist: Pillow<12.3,>=8
 Requires-Dist: numba>=0.57
 Requires-Dist: lightgbm<4.0.0,>=3.3
 Requires-Dist: xgboost<2.1,>=1.6
@@ -95,7 +96,7 @@ Supports **classification** and **regression**, optional **GWAS/LD** SNP filteri
 - **train** / **train-all** need preprocess `*_metadata.json` (`-j`) — not a raw matrix path alone.
 - GWAS/LD runs in **preprocess only**; training does not re-filter SNPs.
 - Wait for preprocess to finish (`Metadata file generated successfully`) before training. In batch jobs, use `set -e`.
-- **Large SNP counts:** use preprocess `-f 2`–`4`, **train-all** with `--parallel_models 1`; metadata guardrails **block `--parallel_models > 1` when ≥ 500k SNPs**.
+- **Large SNP counts:** use preprocess `-f 2`–`4`; for **train-all**, prefer `--parallel_models 1` unless job memory is very large (each parallel worker copies the full matrix).
 
 ---
 
@@ -121,7 +122,7 @@ G2PInsight visualize \
 ```bash
 G2PInsight preprocess --bfile genotype -p pheno.txt -o results/ -f 4
 G2PInsight train-all -j results/preprocess/results_metadata.json -o results/ \
-  --parallel_models 1 --threads 4 --no_hyperparameter_search --n_folds 3
+  --parallel_models 1 --threads 4 --n_folds 3
 ```
 
 ---
@@ -226,7 +227,7 @@ G2PInsight preprocess --bfile genotype -p pheno.txt -o results/ -f 4 --no-cache
 
 #### What it is
 
-Trains **one** ML model from `*_metadata.json`: load matrix → split samples → tune hyperparameters (optional) → K-fold CV on training split → final fit → test metrics → SHAP.
+Trains **one** ML model from `*_metadata.json`: load matrix → split samples → optional hyperparameter search → K-fold CV on training split → final fit → test metrics → SHAP.
 
 #### What you get
 
@@ -246,17 +247,21 @@ G2PInsight train -j <metadata.json> -m <model> -o <output_dir> [options]
 ```
 
 ```bash
-# Default
+# Default (no hyperparameter search)
 G2PInsight train -j results/preprocess/results_metadata.json -m LightGBM -o results/
 
 # Large SNP set
 G2PInsight train -j results/preprocess/results_metadata.json -m LightGBM -o results/ \
-  --no_hyperparameter_search --n_folds 3 --threads 4
+  --n_folds 3 --threads 4
+
+# Enable hyperparameter search
+G2PInsight train -j results/preprocess/results_metadata.json -m LightGBM -o results/ \
+  --hyperparameter_search
 ```
 
-**Evaluation (default):** 80% train / 20% test. Tuning and K-fold CV use the 80% only; `{Model}_metrics.json` reports the 20% test set.
+**Evaluation (default):** 80% train / 20% test. Optional tuning and K-fold CV use the 80% only; `{Model}_metrics.json` reports the 20% test set.
 
-**Flow:** hyperparameter search (internal 80/20 of train) → K-fold CV on full train split → final fit → SHAP.
+**Flow (default):** K-fold CV on train split (model defaults) → final fit → SHAP. With `--hyperparameter_search`: hold-out tuning on the train split → CV → final fit → SHAP.
 
 #### Key options
 
@@ -264,7 +269,7 @@ G2PInsight train -j results/preprocess/results_metadata.json -m LightGBM -o resu
 |--------|---------|-------|
 | `-m` | — | `LightGBM`, `RandomForest`, `XGBoost`, `SVM`, `CatBoost`, `Logistic` |
 | `--n_folds` | `5` | CV folds on training split |
-| `--no_hyperparameter_search` | off | Faster; recommended for huge matrices |
+| `--hyperparameter_search` | off | Opt-in RandomizedSearchCV; off by default for speed |
 | `--threads` | `1` | Per-model CPU threads |
 | `--shap_dependence_top` | `0` | Cap SNPs in dependence file (`0` = all) |
 | `--ignore-warnings` | off | Hide `[WARNING]` logs and Python warnings (errors still shown) |
@@ -305,10 +310,14 @@ G2PInsight train-all -j results/preprocess/results_metadata.json -o results/ \
 
 # Millions of SNPs
 G2PInsight train-all -j results/preprocess/results_metadata.json -o results/ \
-  --parallel_models 1 --threads 4 --no_hyperparameter_search --n_folds 3
+  --parallel_models 1 --threads 4 --n_folds 3
+
+# Opt-in hyperparameter search
+G2PInsight train-all -j results/preprocess/results_metadata.json -o results/ \
+  --hyperparameter_search --parallel_models 1 --threads 4
 ```
 
-Shares **train** options except `-m`. Extra: `--parallel_models` (default `1`), `--ignore-warnings`. **≥ 500k SNPs + `parallel_models > 1` is rejected** before load.
+Shares **train** options except `-m`. Extra: `--parallel_models` (default `1`), `--ignore-warnings`. On very wide matrices, high `--parallel_models` needs substantial RAM (each worker copies the full matrix).
 
 ---
 
@@ -421,20 +430,20 @@ By design: best model by **test set** metrics. See `best_model_info.json` and `a
 
 ### train-all fails or workers crash
 
-**Symptom:** `Worker process crashed`, all models `failed`, or error about `--parallel_models` and SNP count.
+**Symptom:** `Worker process crashed`, all models `failed`, or OOM under high `--parallel_models`.
 
 **What to do:**
 
-1. **≥ 500k SNPs:** use `--parallel_models 1` only (higher values are blocked).
+1. **≥ 500k SNPs:** prefer `--parallel_models 1` unless memory is abundant.
 2. Re-run preprocess with **`-f 2` or `-f 4`** if too many SNPs were kept.
-3. Use `--parallel_models 1 --no_hyperparameter_search --n_folds 3 --threads 4`.
+3. Use `--parallel_models 1 --n_folds 3 --threads 4` (omit `--hyperparameter_search`).
 4. Increase job memory; or test one model: `G2PInsight train -m LightGBM ...`.
 
 ### Training or load is very slow
 
 1. Fewer SNPs in preprocess (`-f 2`–`4`).
 2. Uncompressed `*_train_data.txt` loads faster than `.gz`.
-3. `--no_hyperparameter_search`, lower `--n_folds`.
+3. Keep default (no `--hyperparameter_search`), lower `--n_folds`.
 
 ### SHAP dependence file is huge
 

{g2pinsight-1.0.2 → g2pinsight-1.0.4}/G2PInsight.egg-info/requires.txt

@@ -4,6 +4,7 @@ scikit-learn>=1.0
 scipy<2.0,>=1.7
 joblib>=1.0
 matplotlib>=3.5
+Pillow<12.3,>=8
 numba>=0.57
 lightgbm<4.0.0,>=3.3
 xgboost<2.1,>=1.6

{g2pinsight-1.0.2 → g2pinsight-1.0.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: G2PInsight
-Version: 1.0.2
+Version: 1.0.4
 Summary: Genome-wide association analysis toolkit
 Author-email: chenrf <12024128035@stu.ynu.edu.cn>
 License: MIT
@@ -27,6 +27,7 @@ Requires-Dist: scikit-learn>=1.0
 Requires-Dist: scipy<2.0,>=1.7
 Requires-Dist: joblib>=1.0
 Requires-Dist: matplotlib>=3.5
+Requires-Dist: Pillow<12.3,>=8
 Requires-Dist: numba>=0.57
 Requires-Dist: lightgbm<4.0.0,>=3.3
 Requires-Dist: xgboost<2.1,>=1.6
@@ -95,7 +96,7 @@ Supports **classification** and **regression**, optional **GWAS/LD** SNP filteri
 - **train** / **train-all** need preprocess `*_metadata.json` (`-j`) — not a raw matrix path alone.
 - GWAS/LD runs in **preprocess only**; training does not re-filter SNPs.
 - Wait for preprocess to finish (`Metadata file generated successfully`) before training. In batch jobs, use `set -e`.
-- **Large SNP counts:** use preprocess `-f 2`–`4`, **train-all** with `--parallel_models 1`; metadata guardrails **block `--parallel_models > 1` when ≥ 500k SNPs**.
+- **Large SNP counts:** use preprocess `-f 2`–`4`; for **train-all**, prefer `--parallel_models 1` unless job memory is very large (each parallel worker copies the full matrix).
 
 ---
 
@@ -121,7 +122,7 @@ G2PInsight visualize \
 ```bash
 G2PInsight preprocess --bfile genotype -p pheno.txt -o results/ -f 4
 G2PInsight train-all -j results/preprocess/results_metadata.json -o results/ \
-  --parallel_models 1 --threads 4 --no_hyperparameter_search --n_folds 3
+  --parallel_models 1 --threads 4 --n_folds 3
 ```
 
 ---
@@ -226,7 +227,7 @@ G2PInsight preprocess --bfile genotype -p pheno.txt -o results/ -f 4 --no-cache
 
 #### What it is
 
-Trains **one** ML model from `*_metadata.json`: load matrix → split samples → tune hyperparameters (optional) → K-fold CV on training split → final fit → test metrics → SHAP.
+Trains **one** ML model from `*_metadata.json`: load matrix → split samples → optional hyperparameter search → K-fold CV on training split → final fit → test metrics → SHAP.
 
 #### What you get
 
@@ -246,17 +247,21 @@ G2PInsight train -j <metadata.json> -m <model> -o <output_dir> [options]
 ```
 
 ```bash
-# Default
+# Default (no hyperparameter search)
 G2PInsight train -j results/preprocess/results_metadata.json -m LightGBM -o results/
 
 # Large SNP set
 G2PInsight train -j results/preprocess/results_metadata.json -m LightGBM -o results/ \
-  --no_hyperparameter_search --n_folds 3 --threads 4
+  --n_folds 3 --threads 4
+
+# Enable hyperparameter search
+G2PInsight train -j results/preprocess/results_metadata.json -m LightGBM -o results/ \
+  --hyperparameter_search
 ```
 
-**Evaluation (default):** 80% train / 20% test. Tuning and K-fold CV use the 80% only; `{Model}_metrics.json` reports the 20% test set.
+**Evaluation (default):** 80% train / 20% test. Optional tuning and K-fold CV use the 80% only; `{Model}_metrics.json` reports the 20% test set.
 
-**Flow:** hyperparameter search (internal 80/20 of train) → K-fold CV on full train split → final fit → SHAP.
+**Flow (default):** K-fold CV on train split (model defaults) → final fit → SHAP. With `--hyperparameter_search`: hold-out tuning on the train split → CV → final fit → SHAP.
 
 #### Key options
 
@@ -264,7 +269,7 @@ G2PInsight train -j results/preprocess/results_metadata.json -m LightGBM -o resu
 |--------|---------|-------|
 | `-m` | — | `LightGBM`, `RandomForest`, `XGBoost`, `SVM`, `CatBoost`, `Logistic` |
 | `--n_folds` | `5` | CV folds on training split |
-| `--no_hyperparameter_search` | off | Faster; recommended for huge matrices |
+| `--hyperparameter_search` | off | Opt-in RandomizedSearchCV; off by default for speed |
 | `--threads` | `1` | Per-model CPU threads |
 | `--shap_dependence_top` | `0` | Cap SNPs in dependence file (`0` = all) |
 | `--ignore-warnings` | off | Hide `[WARNING]` logs and Python warnings (errors still shown) |
@@ -305,10 +310,14 @@ G2PInsight train-all -j results/preprocess/results_metadata.json -o results/ \
 
 # Millions of SNPs
 G2PInsight train-all -j results/preprocess/results_metadata.json -o results/ \
-  --parallel_models 1 --threads 4 --no_hyperparameter_search --n_folds 3
+  --parallel_models 1 --threads 4 --n_folds 3
+
+# Opt-in hyperparameter search
+G2PInsight train-all -j results/preprocess/results_metadata.json -o results/ \
+  --hyperparameter_search --parallel_models 1 --threads 4
 ```
 
-Shares **train** options except `-m`. Extra: `--parallel_models` (default `1`), `--ignore-warnings`. **≥ 500k SNPs + `parallel_models > 1` is rejected** before load.
+Shares **train** options except `-m`. Extra: `--parallel_models` (default `1`), `--ignore-warnings`. On very wide matrices, high `--parallel_models` needs substantial RAM (each worker copies the full matrix).
 
 ---
 
@@ -421,20 +430,20 @@ By design: best model by **test set** metrics. See `best_model_info.json` and `a
 
 ### train-all fails or workers crash
 
-**Symptom:** `Worker process crashed`, all models `failed`, or error about `--parallel_models` and SNP count.
+**Symptom:** `Worker process crashed`, all models `failed`, or OOM under high `--parallel_models`.
 
 **What to do:**
 
-1. **≥ 500k SNPs:** use `--parallel_models 1` only (higher values are blocked).
+1. **≥ 500k SNPs:** prefer `--parallel_models 1` unless memory is abundant.
 2. Re-run preprocess with **`-f 2` or `-f 4`** if too many SNPs were kept.
-3. Use `--parallel_models 1 --no_hyperparameter_search --n_folds 3 --threads 4`.
+3. Use `--parallel_models 1 --n_folds 3 --threads 4` (omit `--hyperparameter_search`).
 4. Increase job memory; or test one model: `G2PInsight train -m LightGBM ...`.
 
 ### Training or load is very slow
 
 1. Fewer SNPs in preprocess (`-f 2`–`4`).
 2. Uncompressed `*_train_data.txt` loads faster than `.gz`.
-3. `--no_hyperparameter_search`, lower `--n_folds`.
+3. Keep default (no `--hyperparameter_search`), lower `--n_folds`.
 
 ### SHAP dependence file is huge
 

{g2pinsight-1.0.2 → g2pinsight-1.0.4}/README.md

@@ -50,7 +50,7 @@ Supports **classification** and **regression**, optional **GWAS/LD** SNP filteri
 - **train** / **train-all** need preprocess `*_metadata.json` (`-j`) — not a raw matrix path alone.
 - GWAS/LD runs in **preprocess only**; training does not re-filter SNPs.
 - Wait for preprocess to finish (`Metadata file generated successfully`) before training. In batch jobs, use `set -e`.
-- **Large SNP counts:** use preprocess `-f 2`–`4`, **train-all** with `--parallel_models 1`; metadata guardrails **block `--parallel_models > 1` when ≥ 500k SNPs**.
+- **Large SNP counts:** use preprocess `-f 2`–`4`; for **train-all**, prefer `--parallel_models 1` unless job memory is very large (each parallel worker copies the full matrix).
 
 ---
 
@@ -76,7 +76,7 @@ G2PInsight visualize \
 ```bash
 G2PInsight preprocess --bfile genotype -p pheno.txt -o results/ -f 4
 G2PInsight train-all -j results/preprocess/results_metadata.json -o results/ \
-  --parallel_models 1 --threads 4 --no_hyperparameter_search --n_folds 3
+  --parallel_models 1 --threads 4 --n_folds 3
 ```
 
 ---
@@ -181,7 +181,7 @@ G2PInsight preprocess --bfile genotype -p pheno.txt -o results/ -f 4 --no-cache
 
 #### What it is
 
-Trains **one** ML model from `*_metadata.json`: load matrix → split samples → tune hyperparameters (optional) → K-fold CV on training split → final fit → test metrics → SHAP.
+Trains **one** ML model from `*_metadata.json`: load matrix → split samples → optional hyperparameter search → K-fold CV on training split → final fit → test metrics → SHAP.
 
 #### What you get
 
@@ -201,17 +201,21 @@ G2PInsight train -j <metadata.json> -m <model> -o <output_dir> [options]
 ```
 
 ```bash
-# Default
+# Default (no hyperparameter search)
 G2PInsight train -j results/preprocess/results_metadata.json -m LightGBM -o results/
 
 # Large SNP set
 G2PInsight train -j results/preprocess/results_metadata.json -m LightGBM -o results/ \
-  --no_hyperparameter_search --n_folds 3 --threads 4
+  --n_folds 3 --threads 4
+
+# Enable hyperparameter search
+G2PInsight train -j results/preprocess/results_metadata.json -m LightGBM -o results/ \
+  --hyperparameter_search
 ```
 
-**Evaluation (default):** 80% train / 20% test. Tuning and K-fold CV use the 80% only; `{Model}_metrics.json` reports the 20% test set.
+**Evaluation (default):** 80% train / 20% test. Optional tuning and K-fold CV use the 80% only; `{Model}_metrics.json` reports the 20% test set.
 
-**Flow:** hyperparameter search (internal 80/20 of train) → K-fold CV on full train split → final fit → SHAP.
+**Flow (default):** K-fold CV on train split (model defaults) → final fit → SHAP. With `--hyperparameter_search`: hold-out tuning on the train split → CV → final fit → SHAP.
 
 #### Key options
 
@@ -219,7 +223,7 @@ G2PInsight train -j results/preprocess/results_metadata.json -m LightGBM -o resu
 |--------|---------|-------|
 | `-m` | — | `LightGBM`, `RandomForest`, `XGBoost`, `SVM`, `CatBoost`, `Logistic` |
 | `--n_folds` | `5` | CV folds on training split |
-| `--no_hyperparameter_search` | off | Faster; recommended for huge matrices |
+| `--hyperparameter_search` | off | Opt-in RandomizedSearchCV; off by default for speed |
 | `--threads` | `1` | Per-model CPU threads |
 | `--shap_dependence_top` | `0` | Cap SNPs in dependence file (`0` = all) |
 | `--ignore-warnings` | off | Hide `[WARNING]` logs and Python warnings (errors still shown) |
@@ -260,10 +264,14 @@ G2PInsight train-all -j results/preprocess/results_metadata.json -o results/ \
 
 # Millions of SNPs
 G2PInsight train-all -j results/preprocess/results_metadata.json -o results/ \
-  --parallel_models 1 --threads 4 --no_hyperparameter_search --n_folds 3
+  --parallel_models 1 --threads 4 --n_folds 3
+
+# Opt-in hyperparameter search
+G2PInsight train-all -j results/preprocess/results_metadata.json -o results/ \
+  --hyperparameter_search --parallel_models 1 --threads 4
 ```
 
-Shares **train** options except `-m`. Extra: `--parallel_models` (default `1`), `--ignore-warnings`. **≥ 500k SNPs + `parallel_models > 1` is rejected** before load.
+Shares **train** options except `-m`. Extra: `--parallel_models` (default `1`), `--ignore-warnings`. On very wide matrices, high `--parallel_models` needs substantial RAM (each worker copies the full matrix).
 
 ---
 
@@ -376,20 +384,20 @@ By design: best model by **test set** metrics. See `best_model_info.json` and `a
 
 ### train-all fails or workers crash
 
-**Symptom:** `Worker process crashed`, all models `failed`, or error about `--parallel_models` and SNP count.
+**Symptom:** `Worker process crashed`, all models `failed`, or OOM under high `--parallel_models`.
 
 **What to do:**
 
-1. **≥ 500k SNPs:** use `--parallel_models 1` only (higher values are blocked).
+1. **≥ 500k SNPs:** prefer `--parallel_models 1` unless memory is abundant.
 2. Re-run preprocess with **`-f 2` or `-f 4`** if too many SNPs were kept.
-3. Use `--parallel_models 1 --no_hyperparameter_search --n_folds 3 --threads 4`.
+3. Use `--parallel_models 1 --n_folds 3 --threads 4` (omit `--hyperparameter_search`).
 4. Increase job memory; or test one model: `G2PInsight train -m LightGBM ...`.
 
 ### Training or load is very slow
 
 1. Fewer SNPs in preprocess (`-f 2`–`4`).
 2. Uncompressed `*_train_data.txt` loads faster than `.gz`.
-3. `--no_hyperparameter_search`, lower `--n_folds`.
+3. Keep default (no `--hyperparameter_search`), lower `--n_folds`.
 
 ### SHAP dependence file is huge
 

{g2pinsight-1.0.2 → g2pinsight-1.0.4}/pyproject.toml

@@ -7,7 +7,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "G2PInsight"
-version = "1.0.2"
+version = "1.0.4"
 description = "Genome-wide association analysis toolkit"
 readme = "README.md"
 requires-python = ">=3.8,<3.13"
@@ -43,6 +43,9 @@ dependencies = [
     "scipy>=1.7,<2.0",  # scipy 2.0+ 可能需要更新的编译器
     "joblib>=1.0",
     "matplotlib>=3.5",
+    # Pillow 12.3+ only ships manylinux_2_28 wheels; CentOS7/glibc2.17 falls back to
+    # source builds and fails on old GCC (C99 for-loop error).
+    "Pillow>=8,<12.3",
     "numba>=0.57",  # 通常有预编译 wheel，不需要从源码编译
     "lightgbm>=3.3,<4.0.0",
     "xgboost>=1.6,<2.1",  # xgboost 2.1+ 可能需要更新的编译器