Repository navigation
Initial Commit of Simplifier NO_JIRA #103
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Open
Alex-AMC
wants to merge
1
commit into
main
Choose a base branch
from
simplifier_code_addition
base: main
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
Open
Changes from all commits
Commits
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,28 @@ | ||
| # | ||
| # This script can be used for any purpose without limitation subject to the | ||
| # conditions at http://www.ccdc.cam.ac.uk/Community/Pages/Licences/v2.aspx | ||
| # | ||
| # This permission notice and the following statement of attribution must be | ||
| # included in all copies or substantial portions of this script. | ||
| # | ||
| # 2024-07-26 Created by Chris Kingsbury, the Cambridge Crystallographic Data Centre | ||
| # ORCID 0000-0002-4694-5566 | ||
| # 2024-10-30 Modified by Alex Moldovan, the Cambridge Crystallographic Data Centre | ||
| # flake8: noqa | ||
| import sys | ||
| from simplifier import MercuryInterface | ||
|
|
||
| import numpy as np | ||
|
|
||
| if __name__ == "__main__": | ||
| if len(sys.argv) > 3 and sys.argv[3].endswith(".m2a"): | ||
| mercury_interface = MercuryInterface() | ||
| if not mercury_interface.write_readme_if_none_selected(): | ||
| atom_clicking_order = np.argsort(np.argsort(mercury_interface.interface.selected_indices)) | ||
| selected_atoms_in_order = [mercury_interface.interface.selected_atoms[x] for x in atom_clicking_order] | ||
| mercury_interface.simplifier.define_simplification(crystal=mercury_interface.crystal, | ||
| user_selected_atoms=selected_atoms_in_order) | ||
| mercury_interface.simplifier.use_simplification(mercury_interface.crystal) | ||
| mercury_interface.write_output() | ||
| else: | ||
| raise NotImplementedError("Implementation is for Mercury - CSD Python API menu only") |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,113 @@ | ||
| # Simplifier | ||
|
|
||
| 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. | ||
|
|
||
| `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 | ||
| containing the same molecular substructure (such as polymorphs, solvates/hydrates, salts, or co-crystals) to replace the full molecule with a simplified skeletal representation. | ||
|
|
||
| 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> | ||
|
|
||
| ## Setup in Mercury | ||
|
|
||
| 1. Place the `simplifier` folder in a location where you have read/write permissions. | ||
| 2. Open the latest version of **Mercury**, select **CSD Python API** in the top toolbar, and click **Options...**. | ||
| 3. Under **Additional Mercury Script Locations**, click **Add Location**, select the parent folder that contains the `simplifier` directory, and click **Save**. | ||
| 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 | ||
| recommend starting with `define_simplifier.py`. | ||
|
|
||
| ## Mercury Workflow | ||
|
|
||
| ### 1. Defining a Simplification Rule (`define_simplifier.py`) | ||
|
|
||
| 1. Load a crystal structure in Mercury. | ||
| 2. Select **between 2 and 10 atoms** belonging to the molecule you want to simplify: | ||
| - **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 | ||
| in the Mercury HTML report instead. | ||
| - For **2 selected atoms**, a single connecting edge (`0-1`) is created between them. | ||
| - 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. | ||
| 3. Run **CSD Python API > simplifier > define_simplifier.py**. | ||
| 4. Mercury will: | ||
| - Generate an atom-mapped SMARTS string and connectivity string and store them in the cache (`simplifier_data.json`). | ||
| - Replace the matched molecules in the current view with their simplified skeletal representation. | ||
| - 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. | ||
|
|
||
| ### 2. Using a Simplification Rule (`use_simplifier.py` / `use_simplifier_remove_unmatched.py`) | ||
|
|
||
| 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): | ||
|
|
||
| - **`use_simplifier.py`**: Replaces matched molecules with their simplified skeleton while **keeping unmatched components** (such as solvent molecules, counterions, or co-formers) intact. | ||
| - **`use_simplifier_remove_unmatched.py`**: Replaces matched molecules with their simplified skeleton and **removes all unmatched components** from the output structure. | ||
|
|
||
| ## Command-Line Interface (CLI) Usage | ||
|
|
||
| `simplifier.py` can also be run directly from the command line using the CSD Python API environment: | ||
|
|
||
| ```bash | ||
| python simplifier.py <idents...> [options] | ||
| ``` | ||
|
|
||
| ### CLI Arguments | ||
|
|
||
| | Argument | Description | | ||
|
Alex-AMC marked this conversation as resolved.
Resolved
|
||
| |-----------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | ||
| | `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. | | ||
|
Alex-AMC marked this conversation as resolved.
Resolved
|
||
| | `-s`, `--smarts` | Override the SMARTS simplification string (defaults to the first matching entry found in `simplifier_data.json`). | | ||
|
Alex-AMC marked this conversation as resolved.
Resolved
|
||
| | `-c`, `--connectivity` | Override the connectivity string (e.g., `011223`). Defaults to the cached connectivity or sequential chain connectivity. | | ||
|
Alex-AMC marked this conversation as resolved.
Resolved
|
||
| | `-od`, `--output_directory` | Directory to write simplified output structures (`<ident>_s.<ext>` and `combined.mol2`). Defaults to the current working directory. | | ||
|
Alex-AMC marked this conversation as resolved.
Resolved
|
||
| | `-ff`, `--file_format` | Output file format for individual simplified structures (default: `mol2`). | | ||
|
Alex-AMC marked this conversation as resolved.
Resolved
|
||
| | `-p`, `--parameters` | Path to a JSON file containing CLI parameter overrides. | | ||
|
Alex-AMC marked this conversation as resolved.
Resolved
|
||
| | `-v`, `--verbose` | Print progress for each structure processed. | | ||
|
Alex-AMC marked this conversation as resolved.
Resolved
|
||
| | `-rm`, `--remove_unmatched` | Remove unmatched molecular components from the simplified crystal structure. | | ||
|
Alex-AMC marked this conversation as resolved.
Resolved
|
||
| | `-ma`, `--match_all` | Match each molecule independently rather than using the same SMARTS for all. | | ||
|
Alex-AMC marked this conversation as resolved.
Resolved
|
||
| | `-as`, `--add_smarts` | Add a SMARTS rule (`ident` + `-s <smarts>` + optional `-c <connectivity>`) directly to `simplifier_data.json` and exit. | | ||
|
Alex-AMC marked this conversation as resolved.
Resolved
|
||
| | `-sd`, `--simplifier_data` | Path to the `simplifier_data.json` cache file (defaults to `simplifier_data.json` in the `simplifier` script directory). | | ||
|
Alex-AMC marked this conversation as resolved.
Resolved
|
||
|
|
||
| ### CLI Examples | ||
|
|
||
| Simplify a CSD entry using existing cached rules and write outputs to `./out`: | ||
|
|
||
| ```bash | ||
| python simplifier.py HXACAN28 -od ./out -v | ||
| ``` | ||
|
|
||
| Simplify all `.cif` and `.mol2` files in the current directory and remove unmatched solvent molecules: | ||
|
|
||
| ```bash | ||
| python simplifier.py cwd -rm | ||
| ``` | ||
|
|
||
| Add a custom SMARTS simplification rule and connectivity to the cache file: | ||
|
|
||
| ```bash | ||
| python simplifier.py HYQUIN08 -as -s "[#8H:0]c1ccc([#8H:1])cc1" -c "01" | ||
| ``` | ||
|
|
||
| ## Cache Storage (`simplifier_data.json`) | ||
|
|
||
| - **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 | ||
| different structures and runs. | ||
| - **In the CLI**: Defaults to `scripts/simplifier/simplifier_data.json` unless overridden with `-sd` / `--simplifier_data`. | ||
| - **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. | ||
|
|
||
| ## Files | ||
|
|
||
| - `simplifier.py`: Core library (`Simplifier`, `SimplifierData`, `MercuryInterface`) and command-line interface. | ||
| - `define_simplifier.py`: Mercury entry point to define a new simplification rule from selected atoms (2 to 10 atoms). | ||
| - `use_simplifier.py`: Mercury entry point to apply a cached simplification rule while retaining unmatched molecules. | ||
| - `use_simplifier_remove_unmatched.py`: Mercury entry point to apply a cached simplification rule and delete unmatched molecules. | ||
| - `simplifier_data.json`: JSON cache storing `smiles` (SMARTS) and `connectivity` mappings keyed by structure identifier. | ||
| - `tests/test_simplifier.py`: Unit test suite covering `SimplifierData`, `Simplifier`, CLI options, and `MercuryInterface`. | ||
|
|
||
| ## Running Unit Tests | ||
|
|
||
| Run the unit test suite using the CSD Python API Python environment: | ||
|
|
||
| ```bash | ||
| python -m unittest discover -s scripts/simplifier/tests -v | ||
| ``` | ||
|
|
||
| ## Author | ||
|
|
||
| Chris Kingsbury and Alex Moldovan, CCDC (2024) | ||
|
|
||
| For feedback or to report any issues please contact [support@ccdc.cam.ac.uk](mailto:support@ccdc.cam.ac.uk) | ||
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.