trialbench 0.3.2
A multimodal AI-Ready Dataset. Updated Regularly. More details from TrialBench: Multi-Modal AI-Ready Datasets for Clinical Trial Prediction.
License: MIT
Requires Python: >=3.7.0


        # TrialBench: Multi-modal AI-ready Clinical Trial Datasets
        
        [![PyPI version](https://pypi-camo.freetls.fastly.net/1084b9f2f9dfb3ed603718f4160bbbce019cb759/68747470733a2f2f696d672e736869656c64732e696f2f707970692f762f747269616c62656e63682e7376673f636f6c6f723d627269676874677265656e)](https://pypi.org/project/trialbench/)
        [![License](https://pypi-camo.freetls.fastly.net/8645b002dd7ec1b54275a80574942e7a318e03c6/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d4d49542d79656c6c6f772e737667)](https://opensource.org/licenses/MIT)
        
        ## 1. Installation
        
        ```bash
        pip install trialbench
        ```
        
        ## 2. Tasks & Phases
        
        | Supported Tasks              | Task Name                                            | Phase Name |
        | ---------------------------- | ---------------------------------------------------- | ---------- |
        | Mortality Prediction         | `mortality_rate`/`mortality_rate_yn`             | 1-4        |
        | Adverse Event Prediction     | `serious_adverse_rate`/`serious_adverse_rate_yn` | 1-4        |
        | Patient Retention Prediction | `patient_dropout_rate`/`patient_dropout_rate_yn` | 1-4        |
        | Trial Duration Prediction    | `duration`                                         | 1-4        |
        | Trial Outcome Prediction     | `outcome`                                          | 1-4        |
        | Trial Failure Analysis       | `failure_reason`                                   | 1-4        |
        | Dosage Prediction            | `dose`/`dose_cls`                                | All        |
        
        ### Clinical Trial Phases
        
        ```
        Phase 1: Safety Evaluation
        Phase 2: Efficacy Assessment
        Phase 3: Large-scale Testing
        Phase 4: Post-marketing Surveillance
        ```
        
        ## 3. Quick Start
        
        ### 3.1 Usage of `trialbench`
        
        ```python
        import trialbench
        
        # Download all datasets at once (optional)
        save_path = 'data/'
        trialbench.function.download_all_data(save_path)
        
        # Load dataset
        task = 'dose'
        phase = 'All'
        
        # Load dataloader.Dataloader 
        train_loader, valid_loader, test_loader, num_classes, tabular_input_dim = trialbench.function.load_data(task, phase, data_format='dl')
        # or Load pd.Dataframe
        train_df, valid_df, test_df, num_classes, tabular_input_dim = trialbench.function.load_data(task, phase, data_format='df')
        ```
        
        ### 3.2 Attributes of Each Task
        
        Each task provides different feature sets. The Dosage Prediction task returns `nctid_lst`, `smiles_lst`, and `mesh_lst`, while all other tasks provide `nctid_lst`, `icdcode_lst`, `smiles_lst`, `criteria_lst`, `tabular_lst`, `text_lst`, and `mesh_lst`.
        
        All tasks use `label_lst` as the label variable. Please refer to the guide documentation for detailed feature as well as label descriptions.
        
        ```python
        # Demo for accessing data elements
        task = 'dose'
        phase = 'All'
        
        # When using DataLoader objects:
        # Features
        nctid_list = train_loader.dataset.nctid_lst
        smiles_list = train_loader.dataset.smiles_lst
        mesh_list = train_loader.dataset.mesh_lst
        # Labels
        # return [datatset_name, label_max, label_min, label_avg], e.g. ['NCT03422510', 2, 2, 2]
        label_list = train_loader.dataset.label_lst 
        
        # When using DataFrames:
        # Features
        nctid_list = train_df.nctid_lst
        smiles_list = train_df.smiles_lst
        mesh_list = train_df.mesh_lst
        # Labels
        label_list = train_df.label_lst
        ```
        
        ## 4. Data Loading
        
        ### `load_data` Parameters
        
        | Parameter       | Type | Description                                              |
        | --------------- | ---- | -------------------------------------------------------- |
        | `task`        | str  | Target prediction task (e.g., 'mortality_rate_yn')       |
        | `phase`       | int  | Clinical trial phase (1-4)                               |
        | `data_format` | str  | Data format ('dl' for Dataloader, 'df' for pd.DataFrame) |
        
        ## 5. Citation
        
        If you use TrialBench in your research, please cite:
        
        ```bibtex
        @article{chen2024trialbench,
          title={Trialbench: Multi-modal artificial intelligence-ready clinical trial datasets},
          author={Chen, Jintai and Hu, Yaojun and Wang, Yue and Lu, Yingzhou and Cao, Xu and Lin, Miao and Xu, Hongxia and Wu, Jian and Xiao, Cao and Sun, Jimeng and others},
          journal={arXiv preprint arXiv:2407.00631},
          year={2024}
        }
        ```