README.md

metadata

title: 'PoreGCN: Pore-Aware MOF Property Prediction'
emoji: 🔬
colorFrom: indigo
colorTo: blue
sdk: gradio
sdk_version: 5.25.2
app_file: app.py
pinned: false
license: mit

PoreGCN: Pore-Aware MOF Property Predictor

PoreGCN is a heterogeneous graph neural network that predicts geometric, gas adsorption, and thermal properties of metal-organic frameworks (MOFs) directly from CIF files. Its key architectural innovation is the integration of Voronoi pore nodes into the graph alongside atomic nodes, enabling explicit message passing between atoms and pore channels. Per-atom and per-pore XAI attributions identify which structural components drive each prediction, and results can be exported as B-factor-annotated CIFs for rendering in iRASPA, Mercury, VESTA, ChimeraX, or OVITO.

The model was developed as part of a research programme on explainable GNNs for porous-material screening at the Institute for Molecular Bioscience, The University of Queensland. A preprint describing the architecture, training procedure, and benchmark results is forthcoming on ChemRxiv.

How to use

1. Upload a MOF CIF file (drag-and-drop or browse). Standard CIFs from the Cambridge Structural Database, CoRE MOF, or hMOF databases work directly.
2. Select the ensemble that matches your material. CoRE MOF is trained on 2,737 experimental structures; hMOF Geometric and hMOF Gas are trained on 51,163 hypothetical structures.
3. Select the target property for XAI attribution. This controls which property is used to color atoms in the 3D viewer and to compute the substructure breakdown.
4. Click Run Prediction. Results appear across four tabs: Predictions (table with scenario badges), 3D Attribution Viewer (interactive Plotly), Trustworthiness (Scenario A/B/C/D grid), and Download (iRASPA CIF).

Voronoi tessellation requires the Zeo++ binary (bundled in bin/). If it is unavailable, the app falls back to atom-only mode and displays a warning above the predictions table. Predictions for pore-geometry properties (void fraction, surface area, pore diameters) will be less accurate in atom-only mode.

Ensembles

Three trained ensembles are bundled in models/ (not in the GitHub repository). Each ensemble is a 5-fold cross-validation top-k selection, trained with multi-task learning and inverse-std loss weighting.

Ensemble	Training set	Properties
CoRE MOF	2,737 experimental MOFs	ASA, GSA, VF, LCD, PLD, thermal stability, density
hMOF Geometric	51,163 hypothetical MOFs	VF, GSA, ASA, LCD, PLD
hMOF Gas	51,163 hypothetical MOFs	5 geometric + 14 gas adsorption + log10(CO2/N2 selectivity)

Trustworthiness framework

Each prediction is assigned to one of four scenarios based on ensemble coefficient of variation (CV) and XAI directional agreement:

Scenario	CV	Agreement	Meaning
A	Low	Yes	Trustworthy
B	Low	No	Overconfident
C	High	Yes	Underconfident
D	High	No	Unreliable

Only Scenario A predictions should be used in downstream screening without further validation.

iRASPA attribution export

The Download tab provides a CIF with per-atom attributions encoded in the _atom_site_B_iso_or_equiv column. The value range is 1 (most negative attribution) to 50 (neutral) to 99 (most positive attribution). In iRASPA: Appearance > Atoms > Color by > Temperature Factor, blue-white-red colormap.

Acknowledgements

Training data from CoRE MOF 2019 (Chung et al.) and hMOF (Wilmer et al.). Voronoi tessellation via Zeo++ (Willems et al.). Graph construction with PyTorch Geometric. Gradio interface.