{"id":48817273,"url":"https://github.com/boseokhong/pcs-analyzer","last_synced_at":"2026-04-14T12:02:28.874Z","repository":{"id":310517392,"uuid":"840757449","full_name":"boseokhong/PCS-analyzer","owner":"boseokhong","description":"A GUI application designed to facilitate PCS analysis from NMR and molecular structure data","archived":false,"fork":false,"pushed_at":"2026-03-31T22:15:39.000Z","size":251,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-04-01T01:22:57.004Z","etag":null,"topics":["analysis","gui","nmr","nmr-data","pcs","plot","viewer","visualization","xyz"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/boseokhong.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-08-10T15:38:16.000Z","updated_at":"2026-03-31T22:15:42.000Z","dependencies_parsed_at":"2025-08-18T17:36:50.903Z","dependency_job_id":null,"html_url":"https://github.com/boseokhong/PCS-analyzer","commit_stats":null,"previous_names":["boseokhong/pcs-analyzer"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/boseokhong/PCS-analyzer","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/boseokhong%2FPCS-analyzer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/boseokhong%2FPCS-analyzer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/boseokhong%2FPCS-analyzer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/boseokhong%2FPCS-analyzer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/boseokhong","download_url":"https://codeload.github.com/boseokhong/PCS-analyzer/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/boseokhong%2FPCS-analyzer/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31795334,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-14T11:13:53.975Z","status":"ssl_error","status_checked_at":"2026-04-14T11:13:53.299Z","response_time":153,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: 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":["analysis","gui","nmr","nmr-data","pcs","plot","viewer","visualization","xyz"],"created_at":"2026-04-14T12:02:27.074Z","updated_at":"2026-04-14T12:02:28.860Z","avatar_url":"https://github.com/boseokhong.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Pseudocontact Chemical Shift (PCS) Analyzer\n![version](https://img.shields.io/badge/version-1.3.2-blue) ![license](https://img.shields.io/badge/license-BSD%203--Clause-green) [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.18752129.svg)](https://doi.org/10.5281/zenodo.18752129)\n\n\u003cimg width=\"1409\" height=\"919\" alt=\"PCS Analyzer main interface\" src=\"https://github.com/user-attachments/assets/e4a0b469-4a98-4552-803d-6cb8a3fbfdab\" /\u003e\n\u003cimg width=\"2420\" height=\"882\" alt=\"PCS Analyzer additional views\" src=\"https://github.com/user-attachments/assets/7981899a-5cc4-46a6-9462-152e7a0f38bb\" /\u003e\n\n**PCS Analyzer** is a Python-based desktop application for the analysis, visualization, and fitting of pseudocontact chemical shifts (PCS) in paramagnetic molecular systems. The program is designed for interactive structure-based PCS interpretation and is particularly suited to small and medium-sized coordination complexes for which tensor-frame analysis, geometrical inspection, and rapid model comparison are essential.\n\nThe software integrates molecular structure import, 2D and 3D PCS visualization, tensor utilities, regression-based diagnostics, rhombicity analysis, fitting workflows, NMR-oriented data inspection, and conformer-based refinement in a unified graphical interface.\n\n\u003e [!NOTE]\n\u003e Required Python packages: `numpy`, `scipy`, `matplotlib`, `pandas`, and `openpyxl`  \n\u003e Optional / additional packages: `ttkbootstrap`, `pyvista`, `vtk`, `pyfftw`, and `imageio`\n\u003e - `pyvista` for 3D PCS field / molecular visualization, and `ttkbootstrap` for enhanced GUI styling\n\u003e - `pyfftw` is optional. The code falls back to `numpy.fft` if it is not installed.\n\u003e - `imageio` is required for GIF export [PyVista's `Plotter.open_gif()`].\n---\n## Overview\n\nPCS Analyzer provides an interactive workflow that connects molecular coordinates, PCS geometry factors, experimental shift data, and tensor-based fitting procedures. Rather than treating plotting, table inspection, fitting, and diagnostics as separate tasks, the program links them directly in the GUI to support iterative analysis.\n\nCore use cases include:\n- inspection of tensor-frame molecular geometry\n- comparison of calculated and experimental PCS values\n- axial and rhombic PCS diagnostics\n- donor-axis and Euler-based fitting strategies\n- advanced fitting and conformer-assisted refinement\n\n## Recent Changes\n\nRelease **v1.3.2**\n- added **PCS Workbench**, a standalone workspace for FFT-based PDE PCS analysis from ORCA magnetic susceptibility tensors and spin-density grids `.3d`\n  - direct import of ORCA `.out` / `.log` files together with ORCA `.3d` spin-density files for PDE workflows\n  - temperature-resolved tensor selection, ORCA tensor conversion, and rank-2 traceless tensor handling\n  - configurable PDE options including zero-padding, density normalization, and contour auto-scaling\n  - PyVista-based PDE field visualization with multi-level PCS isosurfaces, spin-density surfaces, and slice display\n  - quantitative comparison between distributed PDE PCS and point-dipole PCS\n  - export of computed PDE results to `.png`, `.csv`, compressed **NumPy (`.npz`)**, and temperature-dependent `.gif`\n  - **oblique PCS slice plotting** for user-defined planes through the metal centre\n  - a **traceless tensor spheroid viewer**\n  - PDE field calculation follows the distributed PCS formalism of Charnock and Kuprov: *Phys. Chem. Chem. Phys.*, **2014**, DOI: `10.1039/C4CP03106G`\n\nRelease **v1.3.1**\n- added a PyVista-based 3D viewer for PCS fields and molecular structures.\n- fixed coordinate reference used in the Rhombicity analysis table\n- added residual-based text color highlighting for PCS tables\n- added export function to save the current visible structure as an `.xyz` file\n\nRelease **v1.3.0** introduces several workflow and interface upgrades:\n- separated the **2D PCS polar plot** from the main window into a dedicated viewer\n- improved the **G_i vs δ plot** with better point interaction and an expanded result/report box\n- added **bidirectional table ↔ plot selection/highlighting**\n- updated the **3D molecular viewer** and **projection viewer**\n- added **Mode C** 8-parameter fitting to the main fitting workflow\n- added a dedicated **Advanced Fitting** tab\n- added an integrated **Conformer Search and Fitting** workflow\n---\n## Main capabilities\n\n### 1. Structure import and coordinate handling\n- import molecular structures from `.xyz`\n- extract coordinates from ORCA `.out` and `.log` files\n- inspect and rotate coordinates in the current tensor frame\n- visualize molecular structures and PCS fields in interactive 3D viewers\n- inspect angular distributions in a projection viewer (`φ / cos(θ)` and Mollweide modes)\n\n### 2. PCS visualization\n- display axial PCS contour maps in a dedicated **2D polar plot** window\n- overlay atomic positions directly onto PCS plots\n- support symmetry-averaged pseudo-points for methyl and CF3 groups\n- visualize PCS fields in a PyVista-based 3D viewer\n- support interactive 3D inspection of isosurfaces / slices for PCS field analysis\n- export PCS-related data and figures\n\n### 3. Table-driven analysis and linked interaction\n- interactive main table containing `Ref`, atom labels, rotated coordinates, `G_i`, `δ_PCS`, and `δ_Exp`\n- import, paste, clear, undo, and export workflows for experimental `δ_Exp`\n- linked highlighting between the table and graphical views\n- synchronized inspection across PCS plots, cartesian plots, and structure viewers\n\n### 4. Rhombicity check and analysis\n- linear analysis of `G_i` versus experimental shift data\n- residual-based rhombicity inspection\n- rhombicity table with `G_ax`, `G_rh`, `δ_PCS(ax)`, `δ_PCS(ax+rh)`, and residual comparison\n- optional use of `Δχ_rh` and tensor-component reconstruction utilities\n\n### 5. Fitting workflows\n- **Mode A**: donor-axis-based fitting\n- **Mode B**: global Euler-angle rigid-body fitting\n- **Mode C**: 8-parameter fitting including tensor, metal position, and orientation terms\n- optional global search for selected fitting modes\n- fit summaries and graphical correlation analysis\n\n### 6. Extended analysis modules\n- **Advanced Fitting** tab for extended PCS-related workflows\n- NMR spectrum viewer with layered `PCS`, `OBS`, `DIA`, and `PARA` displays\n- NMR analysis window for non-PCS-oriented inspection\n- integrated **Conformer Search and Fitting** with preview, apply, revert, and discard workflows\n\n### 7. PCS Workbench (distributed PCS / PDE)\n- standalone FFT-based distributed PCS workflow using ORCA susceptibility tensors and spin-density grids\n- comparison between distributed PDE PCS and point-dipole PCS\n- interactive 3D visualization of PDE fields with signed PCS isosurfaces and spin-density overlays\n- oblique PCS slice plotting for user-defined planes through the metal centre\n- tensor spheroid visualization with temperature-dependent `GIF` export\n- export of PDE fields, atom-wise comparison tables\n\nThe PDE implementation follows the distributed PCS / Kuprov-equation framework (*PCCP*, 2014, DOI: `10.1039/C4CP03106G`).\n\n---\n## Installation\n\nClone the repository and install the required dependencies:\n\n```bash\ngit clone https://github.com/boseokhong/PCS-analyzer.git\ncd PCS-analyzer\npip install numpy scipy matplotlib pandas openpyxl\n```\n\nOptional packages for 3D visualization, FFT acceleration, and GIF export:\n\n```bash\npip install ttkbootstrap pyvista vtk pyfftw imageio\n```\n\nRun the program with:\n\n```bash\npython main.py\n```\n---\n## Suggested workflow\n\nA typical analysis sequence is:\n\n1. load a molecular structure (`.xyz` or supported ORCA output)\n2. define the metal center and tensor input values\n3. inspect rotated coordinates and the main PCS table\n4. open the **2D PCS polar plot** for contour-based visualization\n5. import or paste experimental `δ_Exp` values\n6. inspect the **G_i vs δ** analysis and regression summary\n7. evaluate residual patterns using **Rhombicity Check** and **Rhombicity Table**\n8. apply fitting in the main **Fitting** tab\n9. extend the analysis using **Advanced Fitting** or **Conformer Search** where appropriate\n\n## Fitting modes\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eClick to expand fitting mode descriptions\u003c/b\u003e\u003c/summary\u003e\n\n### Mode A — donor-axis fit\nThis mode defines the fitting axis from one or more donor atoms and is useful when tensor orientation should follow a chemically intuitive ligand-based reference direction.\n\nAvailable donor-axis definitions include:\n- `bisector`\n- `normal`\n- `pca`\n- `centroid`\n- `average`\n- `first`\n\n### Mode B — Euler fit\nThis mode performs rigid-body fitting in the global frame using Euler rotations. It is useful when no donor-based axis definition should be imposed a priori.\n\n### Mode C — 8-parameter fit\nThis mode provides a more complete fitting model and may include:\n- `Δχ_ax`\n- optional `Δχ_rh`\n- metal position `(x, y, z)`\n- Euler angles `(α, β, γ)`\n\nIt is appropriate when simultaneous refinement of tensor magnitude, anisotropy, orientation, and metal position is required.\n\n\u003c/details\u003e\n\n## Export\n\nPCS Analyzer supports export of:\n- PCS tables / current visible structure (`.xyz`)\n- cartesian and PCS plots\n- fitting summaries\n- CSV / Excel tables\n- graphical outputs (`PNG`, `PDF`, `SVG`, depending on the module)\n---\n## Version history\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eClick to expand version history\u003c/b\u003e\u003c/summary\u003e\n\n**v0.1**\n- initial release\n- `.xlsx` export with cartesian coordinate output\n\n**v0.2**\n- tensor values, PCS range, and interval input\n- molar susceptibility tensor calculation\n\n**v0.3**\n- XYZ file import and plotting\n- coordinate rotation\n- atom coordinate table\n- geometrical parameter analysis plot\n\n**v0.3.1**\n- clicking an atom point on the PCS plot highlights the corresponding table entry\n\n**v0.4**\n- added 3D molecular scatter plot\n\n**v0.5**\n- reorganized GUI\n- added Mollweide projection plot\n\n**v0.6**\n- added half / quarter PCS plot view toggle\n\n**v0.7**\n- bug fixes\n\n**v1.0.0**\n- code refactoring\n- PCS fitting\n\n**v1.0.1**\n- added `δ_exp` table export / import\n\n**v1.0.2**\n- fixed CSV export encoding\n\n**v1.1.0**\n- diagnostics\n- rhombicity utilities\n- fitting function updates\n\n**v1.2.0**\n- added NMR spectrum viewer\n- added automatic methyl / CF3 symmetry averaging\n- improved XYZ loader with ORCA `.out` / `.log` support\n- bug fixes and refactoring\n\n**v1.3.0**\n- separated 2D PCS polar plot from the main window\n- improved `G_i` vs `δ` plot interaction and result reporting\n- added linked table ↔ plot highlighting / selection\n- updated 3D molecular and projection plots\n- added **Mode C** 8-parameter fitting\n- added **Advanced Fitting** tab\n- added integrated **Conformer Search and Fitting** workflow\n\n**v1.3.1**\n- added a PyVista-based 3D viewer for PCS fields and molecular structures.\n- fixed coordinate reference used in the Rhombicity analysis table\n- added residual-based text color highlighting for PCS tables\n- added export function to save the current visible structure as an `.xyz` file\n\n**v1.3.2**\n- added **PCS Workbench** for FFT-based distributed PCS / PDE analysis\n  - direct import of ORCA `.out` / `.log` files together with ORCA `.3d` spin-density files for PDE workflows\n  - temperature-resolved tensor selection, ORCA tensor conversion, and rank-2 traceless tensor handling\n  - configurable PDE options including zero-padding, density normalization, and contour auto-scaling\n  - PyVista-based PDE field visualization with multi-level PCS isosurfaces, spin-density surfaces, and slice display\n  - quantitative comparison between distributed PDE PCS and point-dipole PCS\n  - export of computed PDE results to `.png`, `.csv`, compressed **NumPy (`.npz`)**, and temperature-dependent `.gif`\n  - **oblique PCS slice plotting** for user-defined planes through the metal centre\n  - a **traceless tensor spheroid viewer**\n  - PDE field calculation follows the distributed PCS formalism of Charnock and Kuprov: *Phys. Chem. Chem. Phys.*, **2014**, DOI: `10.1039/C4CP03106G`\n\n\u003c/details\u003e\n\n---\n## Citation\n\nIf you use PCS Analyzer in academic work, please cite the Zenodo record associated with this project.\n\n- DOI (all versions): **10.5281/zenodo.18752129**\n\nA dedicated paper describing **PCS Analyzer**, including its methodology, implementation, and representative applications in paramagnetic NMR analysis, is currently in preparation.\n\n## Author\n\n**Boseok Hong**  \nDepartment of Chemistry of the f-elements, Institute of Resource Ecology, HZDR\n\nContact: [bshong66@gmail.com](mailto:bshong66@gmail.com)\n\nGitHub: [boseokhong/PCS-analyzer](https://github.com/boseokhong/PCS-analyzer)\n\n## Acknowledgements\n\nThis project includes code or implementation ideas derived in part from the work of **Sebastian Dechert** for aspects of the 3D molecular scatter-plot functionality, distributed under the BSD 3-Clause License. The original project is available at:\n\n- https://github.com/radi0sus/xyz2tab\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fboseokhong%2Fpcs-analyzer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fboseokhong%2Fpcs-analyzer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fboseokhong%2Fpcs-analyzer/lists"}