heropso 0.1.1

A multi-objective particle swarm optimization framework for feature selection in bioinformatics.

HERO-PSO

Hybrid Ensemble-driven Robust Orchestration Particle Swarm Optimization

Introduction

HERO-PSO is a stability-driven ensemble feature selection framework designed for complex and noisy biological data.

By synergizing complementary stability selection, nested cross-validation, and an advanced multi-objective binary particle swarm optimization algorithm (MO-BPSO), this framework systematically identifies robust feature subsets within noisy transcriptomic landscapes. HERO-PSO enforces the identification of "consensus solutions" robust to data perturbations.

Benchmarking across 12 independent datasets demonstrates that HERO-PSO significantly improves the Jaccard Index (JI) while maintaining leading predictive accuracy (Bal-ACC and AUC), underscoring its potential for clinical translation.

Beyond mere biomarker discovery, HERO-PSO enables a translational pipeline for drug repurposing. Integrating resistance signatures with Connectivity Map (CMap), we identified and experimentally validated potential sensitizers for cisplatin-resistant bladder cancer. In conclusion, by combining advanced computational intelligence with strict stability constraints, HERO-PSO offers a robust paradigm for tumor drug response prediction and biomarker discovery.

Installation

You can easily install heropso and its dependencies directly from the Python Package Index (PyPI):

pip install heropso

You can also install heropso locally in editable mode for development with source code(github). Clone or download the repository, navigate to the project root directory (where setup.py is located), and run:

pip install -e .

This will install the package in editable mode, allowing you to make changes to the code and see them reflected immediately without reinstalling.

Quick Start / Usage

import heropso

# Define your input dataset path (CSV format)
# Note: The CSV should contain features as columns and samples as rows, with a label column.
input_data_path = "path/to/your/expression_data.csv"

# Define where you want to save the results
output_directory = "./hero_pso_results"

# Run the core HERO-PSO pipeline
# This will perform nested cross-validation and output stable core consensus clusters
heropso.run_heropso(
    input_csv_path=input_data_path,
    output_dir_path=output_directory,
    outer_cv_folds=5,          # Number of outer cross-validation folds
    inner_cv_folds=5,          # Number of inner CV folds for fitness evaluation (Optional)
    parallel_workers=4         # Number of CPU cores to use for parallel processing (Optional)
)

Output Interpretation

• 00_Spearman_matrix.csv: Contains the Spearman correlation coefficients between all features. Used to identify and filter out highly redundant features.
• 01_Feature_stability_redundancy_ranking.csv: Results from the Complementary Stability Selection (CSS) phase. It lists features ranked by their selection frequency across bootstrap samples using ElasticNet.
• 02_prior_knowledge_ranking.csv: Feature ranking based on Mutual Information (MI) scores between features and the target label. This serves as prior knowledge to guide the PSO initialization.
• XX_foldX_global_archive.csv (e.g., 03_fold1_global_archive.csv): (Note: The prefix number XX increments for each fold, typically starting from 03) The final Pareto archive (non-dominated solutions) found by the ensemble PSO for a specific outer cross-validation fold. It includes selected feature indices, names, and test performance.
• XX_cluster_result.csv All stable solutions (Average JI Rank Top 50%) found across all folds, grouped into clusters based on Jaccard index. It shows which solutions belong to which "phenotype" of biomarkers.
• XX_core_cluster_result.csv The "Gold Standard" clusters. These are the refined subsets of biomarkers that appeared consistently across all cross-validation folds, representing the most robust signatures.
• XX_summary_clusters_core.txt A comprehensive text report summarizing the algorithm's performance. It includes the Overall average JI of all cluster as well as the average JI of each cluster. Additionally, it provides generalization performance metrics (Bal-ACC/AUC) along with other detailed metrics (Number of Features/Log Loss) for the representative solution of each discovered core cluster.

License

This project is licensed under the MIT License.