Model description

MLStructureMining is a tree-based machine learning classifier designed to rapidly match X-ray pair distribution function (PDF) data to prototype patterns from a large database of crystal structures, providing real-time structure characterization by screening vast quantities of data in seconds.

The code used to train the model can be found HERE, and the Python implementation can be found HERE or the wheel file ´mlstructuremining-4.1.0-py3-none-any.whl´.

Evaluation Results

MLstructureMining has been trained PDFs from on 10,833 crystal structures obtained from Crystallography Open Database (COD). The Pearson Correlation Coefficient (PCC) was used to cluster structures with similar PDF, resulting in a total of 6,062 labels. 100 PDFs were simluated per structures, and the data were split into training, validation and testing set with a 80/10/10 ratio.

We evaluate this model based an accuracy and to test the robustness of MLstructureMining, we deploy zeroth-order optimization (ZOO) from the Adversarial Robustness Toolbox (ART) library to perform adversarial attacks.

Metric	Value
Accuracy	91%
Top-3 Accuracy	99%
ZOO Accuracy	89%
ZOO Top-3 Accuracy	97%

How to Get Started with the Model

Use the code below to get started with the model.

import xgboost as xgb
import pandas as pd

def show_best(pred: np.ndarray, 
              best_list: np.ndarray, 
              df_stru_catalog: pd.DataFrame, 
              num_show: int) -> None:
    """
    Display the best predictions based on the model output.

    Parameters
    ----------
    pred : np.ndarray
        Predictions from the model.
    best_list : np.ndarray
        List of best predictions.
    df_stru_catalog : pd.DataFrame
        The structure catalog associated with the model.
    num_show : int
        Number of top predictions to show.

    Returns
    -------
    None
    """
    for count, idx in enumerate(reversed(best_list[-num_show:])):
        print(f"\n{count}) Probability: {pred[idx]*100:3.1f}%")

        compo = clean_string(df_stru_catalog.iloc[idx]["composition"])
        sgs = clean_string(df_stru_catalog.iloc[idx]["space_group_symmetry"])

        print(f'    COD-IDs: {df_stru_catalog.iloc[idx]["Label"].rsplit(".",1)[0]}, composition: {compo[0]}, space group: {sgs[0]}')
        if not pd.isna(df_stru_catalog.at[idx, "Similar"]):
            similar_files = extract_filenames(df_stru_catalog.at[idx, "Similar"])
            compo = clean_string(df_stru_catalog.iloc[idx]["composition"])
            sgs = clean_string(df_stru_catalog.iloc[idx]["space_group_symmetry"])
            for jdx in range(len(similar_files)):
                print(f'    COD-IDs: {similar_files[jdx]}, composition: {compo[jdx]}, space group: {sgs[jdx]}')


N_CPU = 8  # Number of CPUs used
NUM_SHOW = 5  # Show to X best predictions 

# Load model
bst = xgb.Booster({'nthread': N_CPU})
bst.load_model("MLstructureMining_model.bin")

# Load your data
# data = pd.read_csv("your_data.csv")
# data_xgb = xgb.DMatrix(data)

# Load labels
labels = pd.read_csv("labels.csv", index_col=0)

# Do inference
pred = bst.predict(data_xgb)

# Show 
best_list = np.argsort(pred)
show_best(pred[0], best_list[0], df_stru_catalog, NUM_SHOW)

Model Card Authors

Emil T. S. Kjær

Model Card Contact

emil.thyge.kjaer@gmail.com

Citation

In review.

BibTeX:

@Article{D4DD00001C,
author ="Kjær, Emil T. S. and Anker, Andy S. and Kirsch, Andrea and Lajer, Joakim and Aalling-Frederiksen, Olivia and Billinge, Simon J. L. and Jensen, Kirsten M. Ø.",
title  ="MLstructureMining: a machine learning tool for structure identification from X-ray pair distribution functions",
journal  ="Digital Discovery",
year  ="2024",
pages  ="-",
publisher  ="RSC",
doi  ="10.1039/D4DD00001C",
url  ="http://dx.doi.org/10.1039/D4DD00001C",
abstract  ="Synchrotron X-ray techniques are essential for studies of the intrinsic relationship between synthesis{,} structure{,} and properties of materials. Modern synchrotrons can produce up to 1 petabyte of data per day. Such amounts of data can speed up materials development{,} but also comes with a staggering growth in workload{,} as the data generated must be stored and analyzed. We present an approach for quickly identifying an atomic structure model from pair distribution function (PDF) data from (nano)crystalline materials. Our model{,} MLstructureMining{,} uses a tree-based machine learning (ML) classifier. MLstructureMining has been trained to classify chemical structures from a PDF and gives a top-3 accuracy of 99% on simulated PDFs not seen during training{,} with a total of 6062 possible classes. We also demonstrate that MLstructureMining can identify the chemical structure from experimental PDFs from nanoparticles of CoFe2O4 and CeO2{,} and we show how it can be used to treat an in situ PDF series collected during Bi2Fe4O9 formation. Additionally{,} we show how MLstructureMining can be used in combination with the well-known methods{,} principal component analysis (PCA) and non-negative matrix factorization (NMF) to analyze data from in situ experiments. MLstructureMining thus allows for real-time structure characterization by screening vast quantities of crystallographic information files in seconds."}