{"id":37671572,"url":"https://github.com/bobleesj/cif-bond-analyzer","last_synced_at":"2026-01-16T12:05:00.024Z","repository":{"id":292757395,"uuid":"981233994","full_name":"bobleesj/cif-bond-analyzer","owner":"bobleesj","description":"An interactive Python script that computes the minimum atomic bonding distances from sites, generating histograms and pair counts.","archived":false,"fork":false,"pushed_at":"2025-06-24T15:22:45.000Z","size":213,"stargazers_count":6,"open_issues_count":2,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-09-09T21:43:00.048Z","etag":null,"topics":["crystal-structure","data-analysis","high-throughput","materials-infomatics","solid-state"],"latest_commit_sha":null,"homepage":"https://doi.org/10.1016/j.jallcom.2023.173241","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bobleesj.png","metadata":{"files":{"readme":"README.md","changelog":"news/TEMPLATE.rst","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-05-10T16:33:38.000Z","updated_at":"2025-07-02T06:18:32.000Z","dependencies_parsed_at":null,"dependency_job_id":"a75f2302-227a-43a0-9fa8-10452ee5d0af","html_url":"https://github.com/bobleesj/cif-bond-analyzer","commit_stats":null,"previous_names":["bobleesj/cif-bond-analyzer"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/bobleesj/cif-bond-analyzer","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bobleesj%2Fcif-bond-analyzer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bobleesj%2Fcif-bond-analyzer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bobleesj%2Fcif-bond-analyzer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bobleesj%2Fcif-bond-analyzer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bobleesj","download_url":"https://codeload.github.com/bobleesj/cif-bond-analyzer/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bobleesj%2Fcif-bond-analyzer/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28478431,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-16T11:59:17.896Z","status":"ssl_error","status_checked_at":"2026-01-16T11:55:55.838Z","response_time":107,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["crystal-structure","data-analysis","high-throughput","materials-infomatics","solid-state"],"created_at":"2026-01-16T12:04:59.942Z","updated_at":"2026-01-16T12:05:00.016Z","avatar_url":"https://github.com/bobleesj.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# CIF Bond Analyzer (CBA)\n\n![Header](https://s9.gifyu.com/images/SViLp.png)\n\n![Python 3.10](https://img.shields.io/badge/python-3.10-blue.svg)\n![Python 3.11](https://img.shields.io/badge/python-3.11-blue.svg)\n![Python 3.12](https://img.shields.io/badge/python-3.12-blue.svg)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/bobleesj/cifkit/blob/main/LICENSE)\n\nThe CIF Bond Analyzer (CBA) is an interactive, command-line-based application\ndesigned for high-throughput extraction of bonding information from CIF\n(Crystallographic Information File) files. CBA offers Site Analysis, System\nAnalysis for binary/ternary systems, and Coordination Analysis. The outputs are\nsaved in `.json`, `.xlsx`, and `.png`formats.\n\n\u003e The current README.md serves as a tutorial and documentation\n\nThe code is designed for interactive use without the need to write any code.\n\n## Scope\n\nAny `.cif` files.\n\n## Value\n\n`CBA` simplifies crystal structure analysis by automating the extraction of\nminimum bond lengths, which are crucial for understanding geometric\nconfigurations and identifying irregularities. Histograms and figures assist in\nidentifying distinct bond lengths and structural patterns.\n\n## Getting started\n\nCopy each line into your command-line applications:\n\n```bash\n$ git clone https://github.com/bobleesj/cif-bond-analyzer.git\n$ cd cif-bond-analyzer\n$ pip install -r requirements.txt\n$ python main.py\n```\n\nOnce the code is executed using `python main.py`, the following prompt will\nappear, asking you to choose one of the three analysis options:\n\n```text\nWelcome! Please choose an option to proceed:\n[1] Conduct site analysis.\n[2] Conduct system analysis.\n[3] Conduct coordination analysis.\nEnter your choice (1-3): 1\n```\n\nFor any option, CBA will ask you to choose folders containing `.cif` files:\n\n```text\n\nFolders with .cif files:\n1. 20240623_ErCoIn_nested, 16 files, 136 nested files\n2. 20240612_ternary_only, 2 files\n3. 20240611_ternary_binary_combined, 5 files\n4. 20240623_teranry_3_unique_elements, 3 files\n5. 20240611_binary_2_unique_elements, 4 files\n\nWould you like to process each folder above sequentially?\n(Default: Y) [Y/n]:\n```\n\nYou may then choose to process folders either sequentially or select specific\nfolders by entering numbers associated with the folders prompted. For each\nfolder, CBA generates site pair data saved in `site_pairs.json` or\n`site_pairs.xlsx`.\n\n## Preprocess\n\nThe following discusses formatting, supercell generation, and atomic mixing\ninformation.\n\n### 1. Format files\n\nCBA uses the `CifEnsemble` object from `cifkit` (https://github.com/bobleesj/cifkit) to conduct preprocessing\nautomatically.\n\n- CBA standardizes the site labels in `atom_site_label`. Some site labels may\n  contain a comma or a symbol such as `M` due to atomic mixing. CBA reformats\n  each `atom_site_label` so it can be parsed into an element type that matches\n  `atom_site_type_symbol`.\n\n- CBA removes the content of `publ_author_address`. This section often has an\n  incorrect format that otherwise requires manual modifications.\n\n- CBA relocates any ill-formatted files, such as those with duplicate labels in\n  `atom_site_label`, missing fractional coordinates, or files that require\n  supercell generation.\n\n### 2. Supercell generation\n\nFor each `.cif` file, a unit cell is generated by applying the symmetry\noperations. A supercell is generated by applying ±1 shifts from the unit cell.\n\n### 3. Atomic mixing info\n\nEach bonding pair is defined with one of four atomic mixing categories:\n\n- **Full occupancy** is assigned when a single atomic site occupies the\n  fractional coordinate with an occupancy value of 1.\n- **Full occupancy with mixing** is assigned when multiple atomic sites\n  collectively occupy the fractional coordinate to a sum of 1.\n- **Deficiency without mixing** is assigned when a single atomic site occupying\n  the fractional coordinate with a sum less than 1.\n- **Deficiency with atomic mixing** is assigned when multiple atomic sites\n  occupy the fractional coordinate with a sum less than 1.\n\n## Analysis Options\n\nCBA provides three options for analysis.\n\n### Option 1. Site Analysis\n\n- **Purpose:** Site Analysis determines the shortest distance and its nearest\n  neighbor for each label in `atom_site_label`.\n\n- **Process:** For each atom in the unit cell, Euclidean distances are\n  calculated from the atom to all atoms in the supercell. The position of the\n  atom in the unit cell for each site label is determined based on the atom with\n  the greatest number of shortest distances to its neighbors.\n\n- **Example:** If a `.cif` file under `atom_site_label` contains four site\n  labels: `Er1`, `Er2`, `Er3`, and `Er4`. The bonding pair from the site label\n  `Er4` and its nearest neighbor `Er2` is unique and recorded. The bonding pair\n  from `Er3` to `Er2` is also considered unique. However, the pairs `Er4-Er2`\n  and `Er2-Er4` are considered identical. Out of the two pairs, the pair with\n  the shorter distance is recorded below.\n\n#### Output 1.1 Excel and JSON\n\nData for each folder is saved in `site_pairs.json` or `site_pairs.xlsx`. Below\nis an example of the JSON structure for bond pairs:\n\n```json\n{\n  \"Co-Co\": {\n    \"250361\": [\n      {\n        \"dist\": 2.529,\n        \"mixing\": \"full_occupancy\",\n        \"formula\": \"ErCo2\",\n        \"tag\": \"rt\",\n        \"structure\": \"MgCu2\"\n      }\n    ],\n    \"1955204\": [\n      {\n        \"dist\": 2.46,\n        \"mixing\": \"full_occupancy\",\n        \"formula\": \"Er2Co17\",\n        \"tag\": \"hex\",\n        \"structure\": \"Th2Ni17\"\n      },\n      {\n        \"dist\": 2.274,\n        \"mixing\": \"full_occupancy\",\n        \"formula\": \"Er2Co17\",\n        \"tag\": \"hex\",\n        \"structure\": \"Th2Ni17\"\n      }\n    ]\n  }\n}\n```\n\nThe minimum bond pair for each file is saved in `element_pairs.json` and\n`element_pairs.xlsx`.\n\n```json\n{\n  \"Co-Co\": {\n    \"250361\": [\n      {\n        \"dist\": 2.529,\n        \"mixing\": \"full_occupancy\",\n        \"formula\": \"ErCo2\",\n        \"tag\": \"rt\",\n        \"structure\": \"MgCu2\"\n      }\n    ],\n    \"1955204\": [\n      {\n        \"dist\": 2.274,\n        \"mixing\": \"full_occupancy\",\n        \"formula\": \"Er2Co17\",\n        \"tag\": \"hex\",\n        \"structure\": \"Th2Ni17\"\n      }\n    ]\n  }\n}\n```\n\nHere is a screenshot of `element_pairs.xlsx`.\n\n\u003cimg width=\"824\" alt=\"site-image\" src=\"https://github.com/user-attachments/assets/a86c0087-4188-49fd-970c-0f872bfb59de\" /\u003e\n\n#### Output 1.2 text summary\n\nA summary text file, `summary_element.txt`, lists the shortest bonding pairs and\nidentifies missing pairs across selected folders:\n\n```txt\nSummary:\nPair: In-In, Count: 4, Distances: 2.736, 2.782, 2.785, 2.793\nPair: Pd-Ge, Count: 4, Distances: 2.449, 2.455, 2.489, 2.672\nPair: Pd-Sb, Count: 4, Distances: 2.505, 2.700, 2.737, 2.793\nPair: Si-Si, Count: 4, Distances: 1.975, 2.289, 2.325, 2.533\nPair: Rh-Ge, Count: 2, Distances: 2.484, 2.495\nPair: Ru-Si, Count: 2, Distances: 2.394, 2.519\nPair: Sb-Sb, Count: 2, Distances: 2.573, 2.793\nPair: Co-Ga, Count: 1, Distances: 2.485\nPair: Co-Sb, Count: 1, Distances: 2.594\nPair: Co-Sn, Count: 1, Distances: 2.737\n\nMissing pairs:\nCo-In\nCo-Ir\nCo-Ni\nCo-Pd\nCo-Pt\nCo-Rh\nCo-Si\nFe-Co\n```\n\n#### Output 1.3 histograms\n\n`histogram_element_pair.png` and `histogram_site_pair.png` are used visualize\ndata, with colors indicating atomic mixing types.\n\n- To modify the x-axis, run `python plot-histogram.py`. This script allows you\n  to interactively specify parameters such as the bin width and x-axis range:\n\n![Histograms for label pair](https://s9.gifyu.com/images/SViMv.png)\n\n### Option 2. System Analysis\n\n- **Purpose:** System Analysis provides an overview of bond fractions acquired\n  from Option 1: Site Analysis, or bond fractions in coordination number\n  geometries.\n\n- **Scope:** System Analysis is applicable for folders containing either 2 or 3\n  unique elements.\n\n4 types of folders are applicable for System Analysis.\n\n- Type 1. Binary files, 2 unique elements\n- Type 2. Binary files, 3 unique elements\n- Type 3. Ternary files, 3 unique elements\n- Type 4. Ternary and binary combined, 3 unique elements\n\nHere is an example of CBA detecting folders containing 2 or 3 unique elements.\n\n`````\nAvailable folders containing 2 or 3 unique elements:\n1. 20240623_ErCoIn_nested, 3 elements (In, Er, Co), 152 files\n2. 20240612_ternary_only, 3 elements (In, Er, Co), 2 files\n3. 20240611_ternary_binary_combined, 3 elements (In, Er, Co), 5 files\n4. 20240623_teranry_3_unique_elements, 2 elements (Er, Co), 3 files\n5. 20240611_binary_2_unique_elements, 2 elements (Er, Co), 4 files````\n`````\n\n#### Output 2.1 Binary/ternary figures\n\nFor Types 2, 3, and 4:\n\n![ternary](https://github.com/user-attachments/assets/ee959118-093b-4086-ad34-5ec3a2f84a06)\n\n**Customize legend position:**\n\nTo adjust the legend position in the ternary diagram, modify the values of `X_SHIFT = 0.0` and `Y_SHIFT = 0.0` in `core/configs/ternary.py`.\n\n**Customize extra lines:**\n\nTo add extra lines to the ternary diagram based on tags, edit `TAGS_IN_FIRST_EXTRA_LINE = [\"lt\", \"ht\", \"hp\", \"hp1\", \"hp2\", \"hp3\"]` and `TAGS_IN_SECOND_EXTRA_LINE = [\"lt\", \"ht\", \"hp\", \"hp1\", \"hp2\", \"hp3\"]` in `core/configs/ternary.py`.\n\nFor Type 1:\n\n![binary_single](https://github.com/user-attachments/assets/c4695840-6b7f-42a6-9640-d1154e8dc18d)\n\nAll of the individual hexagon figures also saved in order.\n\n![composite_binary_1](https://github.com/user-attachments/assets/badeebaa-7c7f-4bee-baae-9f3e3858a1eb)\n\n#### Output 2.2 Color map\n\nFor Types 2, 3, and 4, color maps for each bond type and overall are generated.\n\n![color_map_overall](https://github.com/user-attachments/assets/061443eb-ed97-4606-a99d-a9fc920faecd)\n\n#### Output 2.3 Excel\n\nBond count per each `cif` file is recorded in `system_analysis_files.xlsx`.\n\n\u003cimg width=\"1088\" alt=\"Screenshot 2025-05-10 at 2 20 27 PM\" src=\"https://github.com/user-attachments/assets/3df73932-0e9f-48e0-b40e-ab9ce22ef770\" /\u003e\n\nAverage bond lengths, count, and statistical values are recorded in\n`system_analysis_main.xlsx`.\n\n\u003cimg width=\"470\" alt=\"Screenshot 2025-05-10 at 2 20 51 PM\" src=\"https://github.com/user-attachments/assets/697aba32-b0fc-4876-a4c7-dff1f179492f\" /\u003e\n\n### Option 3. Coordination Analysis\n\n- **Purpose:** This option determines the best coordination geometry using four\n  methods provided in `cifkit`. Excel files and JSON are saved with nearest\n  neighbor information.\n\n- **Customization:** The Excel contains `Δ`, which is defined as the interatomic\n  distance subtracted by the sum of atomic radii. You may provide your radii\n  values by modifying the `radii.xlsx` file.\n\n#### Output 3.1 JSON\n\nFor each site, the nearest neighbors within the coordination number geometry are\nrecorded in `CN_connections.json`.\n\n```python\n{\n    \"250361\": {\n        \"Co\": [\n            {\n                \"connected_label\": \"Co\",\n                \"distance\": 2.529,\n                \"delta\": 1.16,\n                \"mixing\": \"full_occupancy\",\n                \"neighbor\": 1\n            },\n            {\n                \"connected_label\": \"Co\",\n                \"distance\": 2.529,\n                \"delta\": 1.16,\n                \"mixing\": \"full_occupancy\",\n                \"neighbor\": 2\n            },\n            ...\n            {\n                \"connected_label\": \"Er\",\n                \"distance\": 2.966,\n                \"delta\": -0.603,\n                \"mixing\": \"full_occupancy\",\n                \"neighbor\": 11\n            },\n            {\n                \"connected_label\": \"Er\",\n                \"distance\": 2.966,\n                \"delta\": -0.603,\n                \"mixing\": \"full_occupancy\",\n                \"neighbor\": 12\n            }\n        ]\n    }\n}\n```\n\n#### Output 3.2 Excel\n\nFor each `.cif` file, the nearest neighbor information is wrriten in each sheet\nwithin `CN_connections.xlsx`.\n\n\u003cimg width=\"1318\" alt=\"Screenshot 2025-05-10 at 2 22 06 PM\" src=\"https://github.com/user-attachments/assets/e043e10f-bce4-4abe-870c-d6557ab6def5\" /\u003e\n\n## Installation\n\n```text\ngit clone https://github.com/bobleesj/cif-bond-analyzer.git\ncd cif-bond-analyzer\npip install -r requirements.txt\npython main.py\n```\n\nIf you are interested in using `Conda` with a new environment run the following:\n\n```text\ngit clone https://github.com/bobleesj/cif-bond-analyzer.git\ncd cif-bond-analyzer\nconda create -n cif python=3.12\nconda activate cif\npip install -r requirements.txt\npython main.py\n```\n\n## Contributors\n\n- Anton Oliynyk\n- Emil Jaffal\n- Sangjoon Bob Lee\n\n## How to ask for help\n\n`CBA` is also designed for experimental materials scientists and chemists.\n\n- If you have any issues or questions, please feel free to reach out or\n  [leave an issue](https://github.com/bobleesj/cif-bond-analyzer/issues).\n\n## How to contribute\n\nHere is how you can contribute to the `CBA` project if you found it helpful:\n\n- Star the repository on GitHub and recommend it to your colleagues who might\n  find `CBA` helpful as well.\n  [![Star GitHub repository](https://img.shields.io/github/stars/bobleesj/cif-bond-analyzer.svg?style=social)](https://github.com/bobleesj/cif-bond-analyzer/stargazers)\n- Fork the repository and consider contributing changes via a pull request.\n  [![Fork GitHub repository](https://img.shields.io/github/forks/bobleesj/cif-bond-analyzer?style=social)](https://github.com/bobleesj/cif-bond-analyzer/network/members)\n- If you have any suggestions or need further clarification on how to use\n  `CBA`, please feel free to reach out to Sangjoon Bob Lee\n  ([@bobleesj](https://github.com/bobleesj)).\n\n## Changelog\n\n- 20240623 - Implement CN bond fractions, add GitHub CI. See\n  [Pull #22](https://github.com/bobleesj/cif-bond-analyzer/pull/22).\n- 20240330 - Add sequential folder processing and customizable histogram\n  generation. See\n  [Pull #16](https://github.com/bobleesj/cif-bond-analyzer/pull/16).\n- 20240311 - Integrate PEP8 linting with `black`. See\n  [Pull #12](https://github.com/bobleesj/cif-bond-analyzer/pull/12).\n- 20240310 - Enhance output options to include both element-based and\n  label-based data for Excel, JSON, and histograms. See\n  [Pull #11](https://github.com/bobleesj/cif-bond-analyzer/pull/11).\n- 20240301 - Display atom counts and execution time per file in Terminal; adds\n  CSV logging.\n- 20240229 - Expand file support to include all CIF files.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbobleesj%2Fcif-bond-analyzer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbobleesj%2Fcif-bond-analyzer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbobleesj%2Fcif-bond-analyzer/lists"}