crystract provides a suite of functions to parse Crystallographic Information Files (.cif), extracting essential data such as chemical formulas, unit cell parameters, atomic coordinates, and symmetry operations. It also includes tools to calculate interatomic distances, identify bonded pairs using various algorithms (Minimum Distance, Brunner’s, Hoppe’s, Voronoi, CrystalNN), determine nearest neighbor counts, and calculate bond angles. All data is extracted into nested data.tables, which can then be exported as an R Data Structure (RDS) or folders of .csv files. The package is designed to facilitate the preparation of crystallographic data for further analysis, including machine learning applications in materials science.

Note on Repository Structure

The crystract package is located within the packages/crystract/ subdirectory of the PrabhuLab/ml-crystals GitHub repository. You must use the subdir argument during installation, as shown below.

Key Features

• Efficient CIF Parsing: Utilizes data.table for fast and robust extraction of metadata, unit cell parameters, atomic coordinates, and symmetry operations.
• Symmetry and Supercell Generation: Applies symmetry operations to generate a full unit cell from the asymmetric unit and expands coordinates into a 3x3x3 supercell for neighbor searching.
• Geometric Calculations: Computes interatomic distances using the metric tensor (correct for all crystal systems) and calculates bond angles.
• Multiple Bonding Algorithms: Implements several algorithms to identify bonded atoms, including the minimum_distance (default), brunner, econ (Hoppe’s), voronoi, and crystal_nn methods.
• Rigorous Error Propagation: Calculates and propagates experimental uncertainties from the CIF file into the final calculated bond lengths and angles.
• Powerful Post-Processing Tools: Includes functions to filter results by chemical element, Wyckoff site, or to remove non-physical “ghost” distances caused by site disorder using a customizable atomic radii table.
• Batch Processing & Export: The main analyze_cif_files() function is designed to process hundreds of files in a single run, and results can be easily exported to a structured directory of CSV files with export_analysis_to_csv().

Workflow Overview

The following diagram illustrates the primary data pipeline in crystract, from raw CIF input to final CSV export.

Best Practices & Decision Logic

To assist researchers in configuring crystract for their specific datasets, we provide the following decision trees for selecting atomic radii and choosing the most appropriate bonding algorithm.

1. Choosing a Bonding Algorithm

When invoking analyze_cif_files(..., bonding_algorithms = c(...)), we recommend choosing your target algorithm based on the chemical makeup of your structure and the electronegativity differences (