Crystallographic Information File (CIF) Data Processing Tools

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_nn_reciprocal, econ_nn, crystal_nn), determine nearest neighbor counts, and calculate bond angles. The package is designed to facilitate the preparation of crystallographic data for further analysis, including machine learning applications in materials science. Methods are described in: Brunner (1977) ; Hoppe (1979) ; O'Keeffe (1979) ; Shannon (1976) ; Pan et al. (2021) ; Pauling (1960, ISBN:978-0801403330).

crystract

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 ($\Delta EN$) of the expected bonds.

2. Atomic Radii Selection

When utilizing functions like filter_ghost_distances() or algorithms that rely on distance cutoffs, crystract employs an internal logic to select the most appropriate atomic radius. You can also override this by injecting your own custom radii dictionary via set_radii_data().

Quickstart: A Complete Workflow & Real Outputs

The analyze_single_cif() (and its batch counterpart analyze_cif_files()) provides a complete, one-step workflow. Here we run it on an example crystal structure included inside the package itself, demonstrating the exact data outputs you can expect.

library(crystract)
library(data.table)

# 1. Load the built-in demo CIF file (Strontium Silicide)
cif_path <- system.file("extdata", "1590946.cif", package = "crystract")

# 2. Analyze the file
# This single function handles parsing, supercell expansion, geometric calculations, 
# bonding detection, and error propagation.
analysis_results <- analyze_single_cif(
  cif_path,
  bonding_algorithms = c("minimum_distance", "crystal_nn")
)

1. Extracted Metadata

The returned object is a single row data.table containing both high-level metadata and list-columns storing the detailed extracted measurements.

High-Level Crystal Information

2. Unit Cell Metrics

The parameters defining the size and shape of the unit cell are securely parsed along with their experimental uncertainties (if available in the CIF).

Extracted Unit Cell Parameters (Å and Degrees)

3. Detected Bonded Pairs

crystract identifies bonded pairs using your chosen algorithms. Below is the output from the Minimum Distance algorithm. Notice the rigorous propagation of experimental error (DistanceError).

Predicted Bonded Pairs (Minimum Distance Method)

4. Calculated Bond Angles

Using the metric tensor, all connected triplets are evaluated to calculate the exact internal bond angles across the repeating periodic boundaries.

Calculated Interatomic Angles

Data Dictionary

Here is a comprehensive overview of the columns generated in the Master Analysis Object and its nested tables.

1. Master Analysis Object

2. Atomic Coordinates (Nested)

3. Bonded Pairs (Nested)

Licensing

crystract is offered under a dual-license model to accommodate a variety of use cases:

• For Open-Source Projects: The package is licensed under the GNU General Public License v3.0 (GPL-3.0). If you are developing other open-source software, you are free to use, modify, and distribute crystract under the terms of the GPL-3.0.

• For Commercial Use: If you wish to use crystract in a commercial product, for commercial services, or for any other commercial purpose, you must obtain a separate commercial license. Please contact the package maintainer to arrange the terms.

Installation

You can install crystract either from CRAN (recommended for most users) or directly from GitHub (for the latest development version).

Prerequisites

• Install the latest version of R from CRAN
• (Optional but recommended) Install RStudio Desktop IDE

Option 1: Install from CRAN (Stable Version)

If crystract is available on CRAN, this is the simplest and most stable method:

install.packages("crystract")

Option 2: Install from GitHub (Latest Development Version)

To get the most recent updates and features:

# Install remotes if not already installed
install.packages("remotes")

# Install crystract from GitHub
remotes::install_github(
  "PrabhuLab/ml-crystals",
  subdir = "packages/crystract",
  build_vignettes = TRUE
)

Verifying the Installation

After installation, load the package:

library(crystract)

If no errors appear, the installation was successful.

Notes

• Use the CRAN version for stability and reproducibility.
• Use the GitHub version if you need the latest features or bug fixes that haven’t been released yet.

Learning More

For a detailed, step-by-step guide explaining each function, the crystallographic principles, and the formulas used for calculations, please see the package vignette.

You can access it with the following command after you have successfully installed the package:

# This command opens the detailed package guide
vignette("crystract")

Community Guidelines

We welcome and appreciate all forms of community engagement. To ensure a smooth and productive collaboration, we have established guidelines for contributing, reporting issues, and seeking support.

All participants in this project are expected to abide by our Code of Conduct. Please read it to understand the standards of behavior we expect.

For detailed instructions on how to contribute to the software, report bugs, or suggest new features, please review our Contributing Guidelines.

Authors

Authors and Maintainers: Don Ngo ([email protected]) & Anirudh Prabhu ([email protected])