@bgicli/bgicli 2.1.1 → 2.2.0

package/data/skills/bio-machine-learning-biomarker-discovery/SKILL.md

@@ -0,0 +1,157 @@
+<!--
+# COPYRIGHT NOTICE
+# This file is part of the "Universal Biomedical Skills" project.
+# Copyright (c) 2026 MD BABU MIA, PhD <md.babu.mia@mssm.edu>
+# All Rights Reserved.
+#
+# This code is proprietary and confidential.
+# Unauthorized copying of this file, via any medium is strictly prohibited.
+#
+# Provenance: Authenticated by MD BABU MIA
+
+-->
+
+---
+name: bio-machine-learning-biomarker-discovery
+description: Selects informative features for biomarker discovery using Boruta all-relevant selection, mRMR minimum redundancy, and LASSO regularization. Use when identifying biomarkers from high-dimensional omics data.
+tool_type: python
+primary_tool: boruta
+measurable_outcome: Execute skill workflow successfully with valid output within 15 minutes.
+allowed-tools:
+  - read_file
+  - run_shell_command
+---
+
+# Feature Selection for Biomarker Discovery
+
+## Boruta All-Relevant Selection
+
+Identifies all features that are significantly better than random (shadow features).
+
+```python
+from boruta import BorutaPy
+from sklearn.ensemble import RandomForestClassifier
+import pandas as pd
+import numpy as np
+
+rf = RandomForestClassifier(n_estimators=100, n_jobs=-1, random_state=42)
+
+# max_iter=100: Typically sufficient; increase to 200 if many features remain tentative
+# perc=100: Use max of shadow features (default); lower for stricter selection
+boruta = BorutaPy(rf, n_estimators='auto', max_iter=100, random_state=42, verbose=0)
+boruta.fit(X.values, y)
+
+selected = X.columns[boruta.support_]
+tentative = X.columns[boruta.support_weak_]
+print(f'Selected: {len(selected)}, Tentative: {len(tentative)}')
+
+feature_ranks = pd.DataFrame({
+    'feature': X.columns,
+    'rank': boruta.ranking_,
+    'selected': boruta.support_
+}).sort_values('rank')
+```
+
+## mRMR (Minimum Redundancy Maximum Relevance)
+
+Selects features that are individually relevant but minimally redundant with each other.
+
+```python
+from mrmr import mrmr_classif
+
+# K: Number of features to select; start with 50-100 for omics
+selected_features = mrmr_classif(X=X, y=pd.Series(y), K=50)
+X_selected = X[selected_features]
+```
+
+## LASSO Feature Selection
+
+L1 regularization drives irrelevant coefficients to zero.
+
+```python
+from sklearn.linear_model import LassoCV
+from sklearn.preprocessing import StandardScaler
+
+scaler = StandardScaler()
+X_scaled = scaler.fit_transform(X)
+
+# cv=5: Standard for selection; eps and n_alphas control alpha grid
+lasso = LassoCV(cv=5, random_state=42)
+lasso.fit(X_scaled, y)
+
+selected_mask = lasso.coef_ != 0
+selected = X.columns[selected_mask]
+print(f'LASSO selected {len(selected)} features at alpha={lasso.alpha_:.4f}')
+
+coefs = pd.Series(lasso.coef_, index=X.columns)
+nonzero = coefs[coefs != 0].sort_values(key=abs, ascending=False)
+```
+
+## Univariate Filtering (Pre-filter)
+
+Reduce dimensionality before more expensive methods.
+
+```python
+from sklearn.feature_selection import SelectKBest, f_classif, mutual_info_classif
+
+# f_classif: Fast, assumes normality; good for log-counts
+# mutual_info_classif: Nonlinear relationships but slower
+# k=1000: Reasonable pre-filter; increase for larger omics datasets (>10k features)
+selector = SelectKBest(f_classif, k=1000)
+X_filtered = selector.fit_transform(X, y)
+selected_idx = selector.get_support(indices=True)
+```
+
+## Combined Pipeline
+
+```python
+from sklearn.pipeline import Pipeline
+from sklearn.ensemble import RandomForestClassifier
+
+# Pre-filter then Boruta for efficiency
+pipe = Pipeline([
+    ('prefilter', SelectKBest(f_classif, k=5000)),
+    ('boruta', BorutaPy(RandomForestClassifier(n_jobs=-1), max_iter=100, random_state=42))
+])
+# Note: BorutaPy doesn't follow sklearn API perfectly; manual fit may be needed
+```
+
+## Method Comparison
+
+| Method | Strengths | Weaknesses | Use When |
+|--------|-----------|------------|----------|
+| Boruta | Finds all relevant features | Slow on large data | Want complete biomarker panel |
+| mRMR | Reduces redundancy | Fixed K | Want compact signature |
+| LASSO | Sparse, interpretable | Picks one of correlated | Want minimal predictive set |
+| Univariate | Fast | Ignores interactions | Pre-filtering |
+
+## Stability Selection
+
+```python
+from sklearn.linear_model import LogisticRegression
+from sklearn.feature_selection import SelectFromModel
+import numpy as np
+
+n_bootstrap = 100
+selection_counts = np.zeros(X.shape[1])
+
+for i in range(n_bootstrap):
+    idx = np.random.choice(len(X), size=len(X), replace=True)
+    X_boot, y_boot = X.iloc[idx], y[idx]
+
+    lasso = LogisticRegression(penalty='l1', solver='saga', C=0.1, max_iter=1000)
+    lasso.fit(X_boot, y_boot)
+    selection_counts += (lasso.coef_[0] != 0)
+
+# stability_threshold=0.6: Features selected in >60% of bootstrap samples
+stable_features = X.columns[selection_counts / n_bootstrap > 0.6]
+```
+
+## Related Skills
+
+- differential-expression/de-results - Pre-filter with DE genes
+- pathway-analysis/go-enrichment - Functional enrichment of selected features
+- machine-learning/omics-classifiers - Use selected features for prediction
+
+
+<!-- AUTHOR_SIGNATURE: 9a7f3c2e-MD-BABU-MIA-2026-MSSM-SECURE -->

package/data/skills/bio-machine-learning-model-validation/SKILL.md

@@ -0,0 +1,148 @@
+<!--
+# COPYRIGHT NOTICE
+# This file is part of the "Universal Biomedical Skills" project.
+# Copyright (c) 2026 MD BABU MIA, PhD <md.babu.mia@mssm.edu>
+# All Rights Reserved.
+#
+# This code is proprietary and confidential.
+# Unauthorized copying of this file, via any medium is strictly prohibited.
+#
+# Provenance: Authenticated by MD BABU MIA
+
+-->
+
+---
+name: bio-machine-learning-model-validation
+description: Implements nested cross-validation and stratified splits for unbiased model evaluation on biomedical datasets. Prevents data leakage and overfitting in biomarker discovery. Use when validating classifiers or optimizing hyperparameters on omics data.
+tool_type: python
+primary_tool: sklearn
+measurable_outcome: Execute skill workflow successfully with valid output within 15 minutes.
+allowed-tools:
+  - read_file
+  - run_shell_command
+---
+
+# Cross-Validation for Biomedical Data
+
+## Why Nested CV Matters
+
+Simple train/test splits overestimate performance on small omics datasets. Nested CV provides unbiased estimates by separating hyperparameter tuning from performance evaluation.
+
+## Nested Cross-Validation
+
+```python
+from sklearn.model_selection import cross_val_score, StratifiedKFold, GridSearchCV
+from sklearn.ensemble import RandomForestClassifier
+from sklearn.preprocessing import StandardScaler
+from sklearn.pipeline import Pipeline
+import numpy as np
+
+pipe = Pipeline([
+    ('scaler', StandardScaler()),
+    ('clf', RandomForestClassifier(random_state=42))
+])
+
+param_grid = {
+    'clf__n_estimators': [50, 100, 200],
+    'clf__max_depth': [5, 10, None]
+}
+
+# Outer CV: performance estimation (5 folds)
+# Inner CV: hyperparameter tuning (3 folds)
+outer_cv = StratifiedKFold(n_splits=5, shuffle=True, random_state=42)
+inner_cv = StratifiedKFold(n_splits=3, shuffle=True, random_state=42)
+
+nested_scores = []
+for train_idx, test_idx in outer_cv.split(X, y):
+    X_train, X_test = X.iloc[train_idx], X.iloc[test_idx]
+    y_train, y_test = y[train_idx], y[test_idx]
+
+    grid = GridSearchCV(pipe, param_grid, cv=inner_cv, scoring='roc_auc', n_jobs=-1)
+    grid.fit(X_train, y_train)
+    score = grid.score(X_test, y_test)
+    nested_scores.append(score)
+
+print(f'Nested CV AUC: {np.mean(nested_scores):.3f} +/- {np.std(nested_scores):.3f}')
+```
+
+## Stratified K-Fold
+
+```python
+from sklearn.model_selection import StratifiedKFold, cross_val_score
+
+# Always stratify for class imbalance
+cv = StratifiedKFold(n_splits=5, shuffle=True, random_state=42)
+scores = cross_val_score(pipe, X, y, cv=cv, scoring='roc_auc')
+print(f'CV AUC: {scores.mean():.3f} +/- {scores.std():.3f}')
+```
+
+## Repeated Stratified K-Fold
+
+```python
+from sklearn.model_selection import RepeatedStratifiedKFold
+
+# More robust estimate with multiple repeats
+cv = RepeatedStratifiedKFold(n_splits=5, n_repeats=10, random_state=42)
+scores = cross_val_score(pipe, X, y, cv=cv, scoring='roc_auc')
+print(f'Repeated CV AUC: {scores.mean():.3f} +/- {scores.std():.3f}')
+```
+
+## Leave-One-Out (Small Datasets)
+
+```python
+from sklearn.model_selection import LeaveOneOut, cross_val_predict
+
+# Use for very small datasets (n < 30)
+loo = LeaveOneOut()
+y_pred = cross_val_predict(pipe, X, y, cv=loo, method='predict_proba')[:, 1]
+auc = roc_auc_score(y, y_pred)
+print(f'LOO AUC: {auc:.3f}')
+```
+
+## Group-Aware Splits
+
+```python
+from sklearn.model_selection import GroupKFold, LeaveOneGroupOut
+
+# When samples from same patient/batch must stay together
+groups = meta['patient_id'].values
+group_cv = GroupKFold(n_splits=5)
+scores = cross_val_score(pipe, X, y, cv=group_cv, groups=groups, scoring='roc_auc')
+```
+
+## CV Strategy Selection
+
+| Dataset Size | Strategy | Notes |
+|--------------|----------|-------|
+| n > 100 | StratifiedKFold(5) | Standard choice |
+| n = 50-100 | StratifiedKFold(10) | More train data per fold |
+| n < 30 | LeaveOneOut | Maximum train data |
+| Repeated measures | GroupKFold | Keep patients together |
+| High variance | RepeatedStratifiedKFold | More stable estimates |
+
+## Avoiding Data Leakage
+
+```python
+# WRONG: Feature selection before CV
+# selected = SelectKBest(k=100).fit_transform(X, y)  # Leaks info!
+# scores = cross_val_score(clf, selected, y, cv=cv)
+
+# CORRECT: Feature selection inside CV
+from sklearn.feature_selection import SelectKBest
+
+pipe = Pipeline([
+    ('scaler', StandardScaler()),
+    ('select', SelectKBest(k=100)),  # Done per fold
+    ('clf', RandomForestClassifier())
+])
+scores = cross_val_score(pipe, X, y, cv=cv, scoring='roc_auc')
+```
+
+## Related Skills
+
+- machine-learning/omics-classifiers - Model training
+- experimental-design/multiple-testing - Multiple hypothesis correction
+- machine-learning/biomarker-discovery - Feature selection within CV
+
+
+<!-- AUTHOR_SIGNATURE: 9a7f3c2e-MD-BABU-MIA-2026-MSSM-SECURE -->

package/data/skills/bio-machine-learning-omics-classifiers/SKILL.md

@@ -0,0 +1,146 @@
+<!--
+# COPYRIGHT NOTICE
+# This file is part of the "Universal Biomedical Skills" project.
+# Copyright (c) 2026 MD BABU MIA, PhD <md.babu.mia@mssm.edu>
+# All Rights Reserved.
+#
+# This code is proprietary and confidential.
+# Unauthorized copying of this file, via any medium is strictly prohibited.
+#
+# Provenance: Authenticated by MD BABU MIA
+
+-->
+
+---
+name: bio-machine-learning-omics-classifiers
+description: Builds classification models for omics data using RandomForest, XGBoost, and logistic regression with sklearn-compatible APIs. Includes proper preprocessing and evaluation metrics for biomarker classifiers. Use when building diagnostic or prognostic classifiers from expression or variant data.
+tool_type: python
+primary_tool: sklearn
+measurable_outcome: Execute skill workflow successfully with valid output within 15 minutes.
+allowed-tools:
+  - read_file
+  - run_shell_command
+---
+
+# Classification Models for Omics Data
+
+## Core Workflow
+
+```python
+from sklearn.model_selection import train_test_split
+from sklearn.preprocessing import StandardScaler
+from sklearn.pipeline import Pipeline
+from sklearn.ensemble import RandomForestClassifier
+from sklearn.metrics import classification_report, roc_auc_score, roc_curve
+import matplotlib.pyplot as plt
+
+X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.2, stratify=y, random_state=42)
+
+pipe = Pipeline([
+    ('scaler', StandardScaler()),
+    ('clf', RandomForestClassifier(n_estimators=100, random_state=42, n_jobs=-1))
+])
+pipe.fit(X_train, y_train)
+
+y_pred = pipe.predict(X_test)
+y_prob = pipe.predict_proba(X_test)[:, 1]
+print(classification_report(y_test, y_pred))
+print(f'ROC-AUC: {roc_auc_score(y_test, y_prob):.3f}')
+```
+
+## XGBoost Classifier
+
+```python
+from xgboost import XGBClassifier
+
+# Use sklearn-compatible API with proper parameters (avoid deprecated seed, nthread)
+xgb = XGBClassifier(
+    n_estimators=100,
+    max_depth=6,
+    learning_rate=0.1,
+    random_state=42,  # NOT seed
+    n_jobs=-1,        # NOT nthread
+    eval_metric='logloss'
+)
+
+pipe = Pipeline([('scaler', StandardScaler()), ('clf', xgb)])
+pipe.fit(X_train, y_train)
+```
+
+## Logistic Regression with Regularization
+
+```python
+from sklearn.linear_model import LogisticRegressionCV
+
+# L1 for sparse biomarkers, L2 for correlated features, elasticnet for mixed
+logit = LogisticRegressionCV(
+    Cs=10,
+    cv=5,
+    penalty='l1',
+    solver='saga',
+    max_iter=1000,
+    random_state=42
+)
+pipe = Pipeline([('scaler', StandardScaler()), ('clf', logit)])
+pipe.fit(X_train, y_train)
+
+# Get selected features (nonzero coefficients)
+feature_mask = logit.coef_[0] != 0
+selected = X.columns[feature_mask]
+```
+
+## ROC Curve Visualization
+
+```python
+fpr, tpr, _ = roc_curve(y_test, y_prob)
+auc = roc_auc_score(y_test, y_prob)
+
+plt.figure(figsize=(6, 6))
+plt.plot(fpr, tpr, label=f'ROC (AUC = {auc:.3f})')
+plt.plot([0, 1], [0, 1], 'k--')
+plt.xlabel('False Positive Rate')
+plt.ylabel('True Positive Rate')
+plt.legend()
+plt.savefig('roc_curve.png', dpi=150)
+```
+
+## Multi-class Classification
+
+```python
+from sklearn.metrics import classification_report
+from sklearn.preprocessing import LabelEncoder
+
+le = LabelEncoder()
+y_encoded = le.fit_transform(y)
+
+# Use class_weight for imbalanced data
+rf = RandomForestClassifier(n_estimators=100, class_weight='balanced', random_state=42)
+```
+
+## Feature Importance from Trees
+
+```python
+import pandas as pd
+
+importances = pipe.named_steps['clf'].feature_importances_
+feature_imp = pd.DataFrame({'feature': X.columns, 'importance': importances})
+feature_imp = feature_imp.sort_values('importance', ascending=False).head(20)
+```
+
+## Preprocessing Guidelines
+
+| Data Type | Scaler | Notes |
+|-----------|--------|-------|
+| Log-counts (RNA-seq) | StandardScaler | Assumes ~normal after log |
+| TPM/FPKM | StandardScaler | Gene-wise centering |
+| Raw counts | None | Tree models handle counts |
+| Mixed features | ColumnTransformer | Different scalers per type |
+
+## Related Skills
+
+- machine-learning/model-validation - Proper model evaluation
+- machine-learning/prediction-explanation - Explain predictions with SHAP
+- machine-learning/biomarker-discovery - Reduce features before modeling
+
+
+<!-- AUTHOR_SIGNATURE: 9a7f3c2e-MD-BABU-MIA-2026-MSSM-SECURE -->

package/data/skills/bio-machine-learning-prediction-explanation/SKILL.md

@@ -0,0 +1,162 @@
+<!--
+# COPYRIGHT NOTICE
+# This file is part of the "Universal Biomedical Skills" project.
+# Copyright (c) 2026 MD BABU MIA, PhD <md.babu.mia@mssm.edu>
+# All Rights Reserved.
+#
+# This code is proprietary and confidential.
+# Unauthorized copying of this file, via any medium is strictly prohibited.
+#
+# Provenance: Authenticated by MD BABU MIA
+
+-->
+
+---
+name: bio-machine-learning-prediction-explanation
+description: Explains machine learning predictions on omics data using SHAP values and LIME for feature attribution. Identifies which genes or features drive classifier decisions. Use when interpreting biomarker classifiers or understanding model predictions.
+tool_type: python
+primary_tool: shap
+measurable_outcome: Execute skill workflow successfully with valid output within 15 minutes.
+allowed-tools:
+  - read_file
+  - run_shell_command
+---
+
+# Model Interpretation for Omics Classifiers
+
+## SHAP TreeExplainer (v0.47+ API)
+
+```python
+import shap
+from sklearn.ensemble import RandomForestClassifier
+
+model = RandomForestClassifier(n_estimators=100, random_state=42)
+model.fit(X_train, y_train)
+
+explainer = shap.TreeExplainer(model)
+# CORRECT (v0.47+): Call explainer directly, NOT .shap_values()
+shap_values = explainer(X_test)
+
+# shap_values is an Explanation object
+# .values has shape (n_samples, n_features) for binary
+# .base_values has expected value
+print(f'SHAP values shape: {shap_values.values.shape}')
+```
+
+## Summary Plot (Global Feature Importance)
+
+```python
+import shap
+import matplotlib.pyplot as plt
+
+# Beeswarm plot: shows impact direction and magnitude
+shap.plots.beeswarm(shap_values, max_display=20, show=False)
+plt.tight_layout()
+plt.savefig('shap_summary.png', dpi=150, bbox_inches='tight')
+plt.close()
+
+# Bar plot: mean absolute SHAP values
+shap.plots.bar(shap_values, max_display=20, show=False)
+plt.savefig('shap_bar.png', dpi=150, bbox_inches='tight')
+```
+
+## Force Plot (Individual Prediction)
+
+```python
+# Explain single prediction
+sample_idx = 0
+shap.plots.force(shap_values[sample_idx], matplotlib=True, show=False)
+plt.savefig('shap_force_single.png', dpi=150, bbox_inches='tight')
+
+# Waterfall plot (cleaner alternative)
+shap.plots.waterfall(shap_values[sample_idx], max_display=15, show=False)
+plt.savefig('shap_waterfall.png', dpi=150, bbox_inches='tight')
+```
+
+## SHAP for XGBoost
+
+```python
+from xgboost import XGBClassifier
+import shap
+
+xgb = XGBClassifier(n_estimators=100, random_state=42, eval_metric='logloss')
+xgb.fit(X_train, y_train)
+
+explainer = shap.TreeExplainer(xgb)
+shap_values = explainer(X_test)
+
+# For XGBoost, shap_values contains log-odds contributions
+shap.plots.beeswarm(shap_values, max_display=20)
+```
+
+## LIME (Local Interpretable Model-agnostic Explanations)
+
+```python
+from lime.lime_tabular import LimeTabularExplainer
+import numpy as np
+
+explainer = LimeTabularExplainer(
+    X_train.values,
+    feature_names=X_train.columns.tolist(),
+    class_names=['control', 'disease'],
+    mode='classification'
+)
+
+# Explain single instance
+sample_idx = 0
+exp = explainer.explain_instance(
+    X_test.iloc[sample_idx].values,
+    model.predict_proba,
+    num_features=20
+)
+
+exp.save_to_file('lime_explanation.html')
+# Or get as list: exp.as_list()
+```
+
+## Extract Top Features from SHAP
+
+```python
+import pandas as pd
+import numpy as np
+
+# Mean absolute SHAP value per feature
+mean_shap = np.abs(shap_values.values).mean(axis=0)
+feature_importance = pd.DataFrame({
+    'feature': X_test.columns,
+    'mean_shap': mean_shap
+}).sort_values('mean_shap', ascending=False)
+
+top_features = feature_importance.head(20)
+top_features.to_csv('shap_top_features.csv', index=False)
+```
+
+## Dependence Plot (Feature Interactions)
+
+```python
+# Shows how SHAP value varies with feature value
+# Automatically colors by interacting feature
+shap.plots.scatter(shap_values[:, 'GENE1'], color=shap_values, show=False)
+plt.savefig('shap_dependence.png', dpi=150, bbox_inches='tight')
+```
+
+## Multi-class SHAP
+
+```python
+explainer = shap.TreeExplainer(model)
+shap_values = explainer(X_test)
+
+# For multi-class, shap_values.values has shape (n_samples, n_features, n_classes)
+# Access class-specific values:
+class_idx = 1
+shap.plots.beeswarm(shap_values[:, :, class_idx], max_display=20)
+```
+
+## Related Skills
+
+- machine-learning/omics-classifiers - Train models to interpret
+- machine-learning/biomarker-discovery - Compare with selection-based importance
+- data-visualization/heatmaps-clustering - Visualize SHAP values as heatmap
+
+
+<!-- AUTHOR_SIGNATURE: 9a7f3c2e-MD-BABU-MIA-2026-MSSM-SECURE -->