|
| 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