A reproducible computational workflow for data-driven Ir(III) emitter design
Overview | Concept | Reproduce | Environment | Outputs | Repository Map | License
PhosIrDesign is the companion code repository for a machine-learning-guided study of Ir(III) emitter molecular design. It provides the executable computational workflow behind the manually curated molecular dataset, ligand-level representation, predictive modelling, virtual screening, post-screening experimental follow-up, and candidate prioritization used in the study.
The repository is intended to make the computational reasoning transparent. A researcher should be able to inspect the curated molecular tables, rerun the workflow, examine the model-derived outputs, and reproduce the exported computational artifacts.
The central idea is a closed-loop molecular design workflow. Literature-derived Ir(III) emitter records are manually curated into ligand-level molecular tables. These records are converted into molecular representations, used to learn structure-property relationships, and then applied to a virtual library to prioritize new candidates.
The screening results are not treated as an endpoint. They are part of a design loop: selected candidates can be synthesized and measured, and the resulting experimental observations can be returned to the dataset to refine subsequent rounds of prediction.
This repository captures the computational part of that loop:
| Stage | Purpose |
|---|---|
| Curated data | Standardized ligand-level records for Ir(III) emitters |
| Molecular representation | Feature construction from L1, L2, and L3 ligand structures |
| Model comparison | Evaluating predictive models for emission wavelength and PLQY |
| Post-screening validation | Prediction on experimentally measured emitters synthesized after virtual screening |
| Virtual screening | Ranking candidate emitters from a combinatorial library |
| Result inspection | Tables, figures, logs, and explainability summaries generated by the workflow |
| Component | Description |
|---|---|
data/PhosIrDB.csv |
Main manually curated Ir(III) emitter dataset |
data/ours.csv |
Experimentally measured emitters synthesized after virtual screening, used for post-screening prediction exports |
data/ir_assemble.csv |
Virtual-screening input library |
phosirdesign/ |
Reusable Python code for the computational workflow |
scripts/ |
Entry points for reproduction, analysis, prediction, and export |
environment/ |
Python environment bootstrap and dependency files |
The main prediction targets are:
| Target | Meaning |
|---|---|
Max_wavelength(nm) |
Emission wavelength |
PLQY |
Photoluminescence quantum yield |
The repository root is intentionally minimal. The complete workflow is launched with:
bash run.shBy default, the workflow writes to a fixed output directory:
Project_Output/
When run.sh is executed outside a checked-out project directory, it can clone the repository first and then run the same workflow entry point. The default clone URL points to:
https://github.com/agi-wang/PhosIrDesign.git
The executable environment is managed by environment/uv.sh and environment/requirements.txt. Running bash run.sh bootstraps the Python environment before launching the workflow.
The workflow is designed to run on macOS and Linux. Public release artifacts use relative timing fields and omit local machine identifiers and local filesystem paths.
Release artifacts intended for publication comparison should be generated on the local reference workstation by running:
bash run.shMaintainers can then package a sanitized copy of the resulting Project_Output directory and upload it to GitHub Releases. The public release asset set includes:
- the sanitized
Project_Outputarchive - final trained model binaries as sanitized
.joblibfiles inside the workflow archive - workflow summary and model-comparison tables
- sanitized release metadata
- SHA-256 checksums for release assets
Auxiliary experiment pickle files, fold-level NumPy archives, and Excel exports are omitted from public release assets.
Workflow outputs are generated outside the tracked source tree. Local runs write to:
Project_Output/
The default Project_Output directory is reset at the start of each automatic local workflow run. In CodeOcean, workflow artifacts are written directly under /results.
| Output | What it represents |
|---|---|
workflow_summary.json |
Run-level summary and generated artifact map |
model_comparison_detailed.csv |
Aggregated model comparison table |
best_models_summary.csv |
Best-performing models by target and metric |
test_predictions/ |
Post-screening synthesized-emitter prediction exports |
virtual_predictions_all.csv |
Full virtual-screening prediction table |
virtual_predictions_all_sorted_by_plqy.csv |
Candidate ranking by predicted PLQY |
figures/ |
Computational figures generated by the workflow |
shap_analysis/shap_report.html |
Model-interpretability report for selected model families |
PhosIrDesign/
├── README.md
├── run.sh
├── data/
├── phosirdesign/
├── scripts/
└── environment/
The root directory is kept intentionally small. The executable workflow starts from run.sh; implementation details live under scripts/, and reusable Python code lives under phosirdesign/.
Several safeguards are included to make reruns traceable:
- default execution resets and writes to the fixed
Project_Outputdirectory - manually specified output directories are rejected if they already contain workflow artifacts
- saved model checkpoints preserve the transformations needed for consistent local inference
- public release packaging omits local paths, machine identifiers, and auxiliary intermediate binary archives
This repository covers the computational workflow. It does not include synthetic procedures, raw spectroscopy files, microscopy or imaging raw data, device fabrication workflows, or in vivo hardware acquisition pipelines.
Some publication-layout figures may be downstream formatted versions of repository outputs. The files here should be read as the executable computational companion to the study, not as a complete archive of every experimental data product.
If you use this repository in academic work, please cite the associated article using the final bibliographic details.
This repository, including the code, curated datasets, documentation, and computational release artifacts, is made available under the Creative Commons Attribution 4.0 International license (CC BY 4.0), unless otherwise noted. See LICENSE for details.