RDKit: Subset.h Source File

| RDKit Open-source cheminformatics and machine learning.

Loading...
Searching...
No Matches
Subset.h
Go to the documentation of this file.
1//
2// Copyright (C) 2025 Hussein Faara, Brian Kelley and other RDKit contributors
3//
4// @@ All Rights Reserved @@
5// This file is part of the RDKit.
6// The contents are covered by the terms of the BSD license
7// which is included in the file license.txt, found at the root
8// of the RDKit source tree.
9//
10#ifndef RD_SUBSET_H
11#define RD_SUBSET_H
12
13#include <RDGeneral/export.h>
14#include <boost/dynamic_bitset.hpp>
15
16#include <memory>
17#include <vector>
18
19namespace RDKit {
20class RWMol;
21
22//! Subsetting Methods for copyMolSubset
23/*
24 * These control what the path structures mean in copyMolSubset
25 *
26 * NOTE: when the atoms and bonds are fully specified, the subset method is
27 * ignored.
28 */
29 enum class SubsetMethod {
30 BONDS_BETWEEN_ATOMS =
31 0, //<! extract the specified atoms and the bonds between them
32 BONDS = 1 //<! extract the specified bonds and their attached atoms
33};
34
35//! Subsetting Options for copyMolSubset
36/*
37 * These control what is copied over from the original molecule
38 *
39 * NOTE: when the atoms and bonds are fully specified, the subset method is
40 * ignored.
41 */
42 struct RDKIT_GRAPHMOL_EXPORT SubsetOptions {
43 bool sanitize =
44 false; /**< perform sanitization automatically on the subset */
45 bool clearComputedProps =
46 false; /**< clear all computed props on the subsetted molecule */
47 bool copyAsQuery = false; /**< Return the subset as a query */
48 bool copyCoordinates =
49 true; /**< *Copy the active coordinates from the molecule */
50 unsigned int conformerIdx =
51 -1u; /**< What conformer idx to use for the coordinates default is -1 */
52
53 SubsetMethod method =
54 SubsetMethod::BONDS_BETWEEN_ATOMS; /**< Subsetting method to use. *Note*
55 * if atoms and bonds are fully
56 * specified the method is ignored.*/
57};
58
59 struct RDKIT_GRAPHMOL_EXPORT SubsetInfo {
60 boost::dynamic_bitset<> selectedAtoms; /**< atoms selected in the subset */
61 boost::dynamic_bitset<> selectedBonds; /**< bonds selected in the subset */
62 std::map<unsigned int, unsigned int>
63 atomMapping; /**< mapping of original atom indices to new ones */
64 std::map<unsigned int, unsigned int>
65 bondMapping; /**< mapping of original bond indices to new ones */
66};
67
68//!
69/*
70 * Extract a subgraph from an ROMol. Bonds, atoms, substance groups and
71 * stereo groups are only extracted to the subgraph if all participant entities
72 * are contained within the given atoms and bonds.
73 *
74 * \param mol - starting mol
75 * \param atoms - atoms to extract
76 * \param bonds - bonds to extract
77 * \param subsetInfo - optional subsetInfo to record the atoms and bonds used
78 * \param options - subset options, note the method is ignored since all the
79 * atoms and bonds are specified
80 *
81 *
82 * NOTE: Bookmarks are currently copied, StereoGroups that are not entirely
83 * included in the subset are not copied.
84 *
85 * NOTE: when using this method the SubsetOptions.method is ignored
86 * for resolving the atoms and bonds to use to subset
87 */
88
89 RDKIT_GRAPHMOL_EXPORT
90std::unique_ptr<RDKit::RWMol> copyMolSubset(
91 const RDKit::ROMol &mol, const std::vector<unsigned int> &atoms,
92 const std::vector<unsigned int> &bonds,
93 const SubsetOptions &options = SubsetOptions());
94
95 RDKIT_GRAPHMOL_EXPORT
96std::unique_ptr<RDKit::RWMol> copyMolSubset(
97 const RDKit::ROMol &mol, const std::vector<unsigned int> &atoms,
98 const std::vector<unsigned int> &bonds, SubsetInfo &subsetInfo,
99 const SubsetOptions &options = SubsetOptions());
100
101//!
102/*
103 * Extract a subgraph from an ROMol. Bonds, substance groups and
104 * stereo groups are only extracted to the subgraph if all participant entities
105 * are selected by the `path` parameter.
106 *
107 * \param mol - starting mol
108 * \param path - the indices of atoms or bonds to extract. If an index falls
109 * outside of the acceptable indices, it is ignored.
110 * use SubsetMethod::BONDS to indicate a bond path and
111 * SubsetMethod::BONDS_BETWEEN_ATOMS to indicate an atom path
112 * and any bond that includes both atoms in the path
113 * \param subsetInfo - optional subsetInfo to record the atoms and bonds used
114 * \param option - optional SubsetOptions to control how the subset is created
115 *
116 * NOTE: Bookmarks are currently copied, StereoGroups that are not entirely
117 * included in the subset are not copied.
118 *
119 */
120 RDKIT_GRAPHMOL_EXPORT std::unique_ptr<RDKit::RWMol> copyMolSubset(
121 const RDKit::ROMol &mol, const std::vector<unsigned int> &path,
122 const SubsetOptions &options = SubsetOptions());
123
124 RDKIT_GRAPHMOL_EXPORT std::unique_ptr<RDKit::RWMol> copyMolSubset(
125 const RDKit::ROMol &mol, const std::vector<unsigned int> &path,
126 SubsetInfo &subsetInfo, const SubsetOptions &options = SubsetOptions());
127
128} // namespace RDKit
129#endif
RDKit::ROMol
Definition ROMol.h:199
RDKit::RWMol
RWMol is a molecule class that is intended to be edited.
Definition RWMol.h:32
export.h
RDKIT_GRAPHMOL_EXPORT
#define RDKIT_GRAPHMOL_EXPORT
Definition export.h:249
RDKit
Std stuff.
Definition Abbreviations.h:19
RDKit::copyMolSubset
RDKIT_GRAPHMOL_EXPORT std::unique_ptr< RDKit::RWMol > copyMolSubset(const RDKit::ROMol &mol, const std::vector< unsigned int > &atoms, const std::vector< unsigned int > &bonds, const SubsetOptions &options=SubsetOptions())
RDKit::SubsetMethod
SubsetMethod
Subsetting Methods for copyMolSubset.
Definition Subset.h:29
RDKit::SubsetMethod::BONDS
@ BONDS
Definition Subset.h:32
RDKit::SubsetMethod::BONDS_BETWEEN_ATOMS
@ BONDS_BETWEEN_ATOMS
Definition Subset.h:30
RDKit::SubsetInfo
Definition Subset.h:59
RDKit::SubsetInfo::bondMapping
std::map< unsigned int, unsigned int > bondMapping
Definition Subset.h:65
RDKit::SubsetInfo::selectedBonds
boost::dynamic_bitset selectedBonds
Definition Subset.h:61
RDKit::SubsetInfo::selectedAtoms
boost::dynamic_bitset selectedAtoms
Definition Subset.h:60
RDKit::SubsetInfo::atomMapping
std::map< unsigned int, unsigned int > atomMapping
Definition Subset.h:63
RDKit::SubsetOptions
Subsetting Options for copyMolSubset.
Definition Subset.h:42
RDKit::SubsetOptions::copyAsQuery
bool copyAsQuery
Definition Subset.h:47
RDKit::SubsetOptions::method
SubsetMethod method
Definition Subset.h:53
RDKit::SubsetOptions::sanitize
bool sanitize
Definition Subset.h:43
RDKit::SubsetOptions::copyCoordinates
bool copyCoordinates
Definition Subset.h:48
RDKit::SubsetOptions::conformerIdx
unsigned int conformerIdx
Definition Subset.h:50
RDKit::SubsetOptions::clearComputedProps
bool clearComputedProps
Definition Subset.h:45