Skip to content

Commit df8b5ca

Browse files
committed
Initial Commit of Simplifier NO_JIRA
1 parent 1d97bb2 commit df8b5ca

8 files changed

Lines changed: 1546 additions & 0 deletions

File tree

‎scripts/ReadMe.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,7 @@ Various scripts with no specific licence requirements that may be useful for a v
2424
| Refcodes With Properties | A script for generating refcode lists with specific properties from an easy-to-read control file. |
2525
| Show semiconductor properties | Displays semiconductor properties for the structure currently loaded in Mercury. |
2626
| Void Search | A script to search on pre-calculated Void properties. |
27+
| Simplifier | Simplify molecular complexity by creating skeletal frames. Works in Mercury and CLI. Information in the publication "Simplifying crystal structures: a new tool for visualising packing motifs in molecular crystals as skeletal frameworks" DOI: <https://doi.org/10.1039/d6ce00813e> |
2728

2829
## Discovery
2930

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
#
2+
# This script can be used for any purpose without limitation subject to the
3+
# conditions at http://www.ccdc.cam.ac.uk/Community/Pages/Licences/v2.aspx
4+
#
5+
# This permission notice and the following statement of attribution must be
6+
# included in all copies or substantial portions of this script.
7+
#
8+
# 2024-07-26 Created by Chris Kingsbury, the Cambridge Crystallographic Data Centre
9+
# ORCID 0000-0002-4694-5566
10+
# 2024-10-30 Modified by Alex Moldovan, the Cambridge Crystallographic Data Centre
11+
# flake8: noqa
12+
import sys
13+
from simplifier import MercuryInterface
14+
15+
import numpy as np
16+
17+
if __name__ == "__main__":
18+
if len(sys.argv) > 3 and sys.argv[3].endswith(".m2a"):
19+
mercury_interface = MercuryInterface()
20+
if not mercury_interface.write_readme_if_none_selected():
21+
atom_clicking_order = np.argsort(np.argsort(mercury_interface.interface.selected_indices))
22+
selected_atoms_in_order = [mercury_interface.interface.selected_atoms[x] for x in atom_clicking_order]
23+
mercury_interface.simplifier.define_simplification(crystal=mercury_interface.crystal,
24+
user_selected_atoms=selected_atoms_in_order)
25+
mercury_interface.simplifier.use_simplification(mercury_interface.crystal)
26+
mercury_interface.write_output()
27+
else:
28+
raise NotImplementedError("Implementation is for Mercury - CSD Python API menu only")

‎scripts/core/simplifier/readme.md‎

Lines changed: 113 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
# Simplifier
2+
3+
A molecular simplifier, akin to a "ribbon"-type protein representation, designed to run inside the Mercury CSD Python API menu or from the command line.
4+
5+
`Simplifier` takes a set of user-selected atoms in a molecule and creates a reusable SMARTS simplification rule and connectivity skeleton. This rule can then be applied to any crystal structure
6+
containing the same molecular substructure (such as polymorphs, solvates/hydrates, salts, or co-crystals) to replace the full molecule with a simplified skeletal representation.
7+
8+
Information in the publication along with a set of guidelines in the supporting information "Simplifying crystal structures: a new tool for visualising packing motifs in molecular crystals as skeletal frameworks" DOI: <https://doi.org/10.1039/d6ce00813e>
9+
10+
## Setup in Mercury
11+
12+
1. Place the `simplifier` folder in a location where you have read/write permissions.
13+
2. Open the latest version of **Mercury**, select **CSD Python API** in the top toolbar, and click **Options...**.
14+
3. Under **Additional Mercury Script Locations**, click **Add Location**, select the parent folder that contains the `simplifier` directory, and click **Save**.
15+
4. In the **CSD Python API** menu in Mercury, you will now see **simplifier** as a submenu containing `define_simplifier.py`, `use_simplifier.py`, and `use_simplifier_remove_unmatched.py`. We
16+
recommend starting with `define_simplifier.py`.
17+
18+
## Mercury Workflow
19+
20+
### 1. Defining a Simplification Rule (`define_simplifier.py`)
21+
22+
1. Load a crystal structure in Mercury.
23+
2. Select **between 2 and 10 atoms** belonging to the molecule you want to simplify:
24+
- **Important**: You must select **more than 1 atom** (at least 2 atoms, up to a maximum of 10 atoms). If 0 or 1 atom is selected when running `define_simplifier.py`, this README will be displayed
25+
in the Mercury HTML report instead.
26+
- For **2 selected atoms**, a single connecting edge (`0-1`) is created between them.
27+
- For **3 to 10 selected atoms**, connectivity is automatically determined using the shortest topological path distances across the molecule in the order the atoms were clicked.
28+
3. Run **CSD Python API > simplifier > define_simplifier.py**.
29+
4. Mercury will:
30+
- Generate an atom-mapped SMARTS string and connectivity string and store them in the cache (`simplifier_data.json`).
31+
- Replace the matched molecules in the current view with their simplified skeletal representation.
32+
- Open an HTML report displaying the SMARTS string, the connectivity pairs, a 2D chemical diagram highlighting the mapped atoms (`:0`, `:1`, ...), and the path to the cache file.
33+
34+
### 2. Using a Simplification Rule (`use_simplifier.py` / `use_simplifier_remove_unmatched.py`)
35+
36+
Once a molecule's simplification rule has been defined and cached, open another structure containing the same substructure (e.g., another polymorph, hydrate, salt, or co-crystal):
37+
38+
- **`use_simplifier.py`**: Replaces matched molecules with their simplified skeleton while **keeping unmatched components** (such as solvent molecules, counterions, or co-formers) intact.
39+
- **`use_simplifier_remove_unmatched.py`**: Replaces matched molecules with their simplified skeleton and **removes all unmatched components** from the output structure.
40+
41+
## Command-Line Interface (CLI) Usage
42+
43+
`simplifier.py` can also be run directly from the command line using the CSD Python API environment:
44+
45+
```bash
46+
python simplifier.py <idents...> [options]
47+
```
48+
49+
### CLI Arguments
50+
51+
| Argument | Description |
52+
|-----------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
53+
| `idents` | One or more CSD refcodes (e.g., `HXACAN28`), structure files (`.cif`, `.mol2`), a `.gcd` refcode list file, or `cwd` to process all `.cif`/`.mol2` files in the current working directory. |
54+
| `-s`, `--smarts` | Override the SMARTS simplification string (defaults to the first matching entry found in `simplifier_data.json`). |
55+
| `-c`, `--connectivity` | Override the connectivity string (e.g., `011223`). Defaults to the cached connectivity or sequential chain connectivity. |
56+
| `-od`, `--output_directory` | Directory to write simplified output structures (`<ident>_s.<ext>` and `combined.mol2`). Defaults to the current working directory. |
57+
| `-ff`, `--file_format` | Output file format for individual simplified structures (default: `mol2`). |
58+
| `-p`, `--parameters` | Path to a JSON file containing CLI parameter overrides. |
59+
| `-v`, `--verbose` | Print progress for each structure processed. |
60+
| `-rm`, `--remove_unmatched` | Remove unmatched molecular components from the simplified crystal structure. |
61+
| `-ma`, `--match_all` | Match each molecule independently rather than using the same SMARTS for all. |
62+
| `-as`, `--add_smarts` | Add a SMARTS rule (`ident` + `-s <smarts>` + optional `-c <connectivity>`) directly to `simplifier_data.json` and exit. |
63+
| `-sd`, `--simplifier_data` | Path to the `simplifier_data.json` cache file (defaults to `simplifier_data.json` in the `simplifier` script directory). |
64+
65+
### CLI Examples
66+
67+
Simplify a CSD entry using existing cached rules and write outputs to `./out`:
68+
69+
```bash
70+
python simplifier.py HXACAN28 -od ./out -v
71+
```
72+
73+
Simplify all `.cif` and `.mol2` files in the current directory and remove unmatched solvent molecules:
74+
75+
```bash
76+
python simplifier.py cwd -rm
77+
```
78+
79+
Add a custom SMARTS simplification rule and connectivity to the cache file:
80+
81+
```bash
82+
python simplifier.py HYQUIN08 -as -s "[#8H:0]c1ccc([#8H:1])cc1" -c "01"
83+
```
84+
85+
## Cache Storage (`simplifier_data.json`)
86+
87+
- **In Mercury**: `MercuryInterface` stores the cache at `<Mercury working directory>/../../simplifier_cache/simplifier_data.json` so that rules defined in one Mercury session remain accessible across
88+
different structures and runs.
89+
- **In the CLI**: Defaults to `scripts/simplifier/simplifier_data.json` unless overridden with `-sd` / `--simplifier_data`.
90+
- **Privacy Note**: `simplifier_data.json` contains SMARTS/SMILES strings for structures you have defined. Do not share this file between organisations if it contains proprietary chemical structures.
91+
92+
## Files
93+
94+
- `simplifier.py`: Core library (`Simplifier`, `SimplifierData`, `MercuryInterface`) and command-line interface.
95+
- `define_simplifier.py`: Mercury entry point to define a new simplification rule from selected atoms (2 to 10 atoms).
96+
- `use_simplifier.py`: Mercury entry point to apply a cached simplification rule while retaining unmatched molecules.
97+
- `use_simplifier_remove_unmatched.py`: Mercury entry point to apply a cached simplification rule and delete unmatched molecules.
98+
- `simplifier_data.json`: JSON cache storing `smiles` (SMARTS) and `connectivity` mappings keyed by structure identifier.
99+
- `tests/test_simplifier.py`: Unit test suite covering `SimplifierData`, `Simplifier`, CLI options, and `MercuryInterface`.
100+
101+
## Running Unit Tests
102+
103+
Run the unit test suite using the CSD Python API Python environment:
104+
105+
```bash
106+
python -m unittest discover -s scripts/simplifier/tests -v
107+
```
108+
109+
## Author
110+
111+
Chris Kingsbury and Alex Moldovan, CCDC (2024)
112+
113+
For feedback or to report any issues please contact [support@ccdc.cam.ac.uk](mailto:support@ccdc.cam.ac.uk)

0 commit comments

Comments
 (0)