Grouper.group_graph_set module
Result-set wrapper for exhaustive_generate / random_generate / exhaustive_fragment.
The C++ bindings return a Python set[GroupGraph]. This module wraps that set in a GroupGraphSet subclass so common downstream operations read as method calls instead of one-line boilerplate that gets copy-pasted across every notebook:
results = exhaustive_generate(3, groups)
results.to_dataframe() # one row per graph results.to_dataframe(properties=[“joback”]) # + Joback predictions results.to_smiles_list() # [“CCO”, …] results.to_sdf(“out.sdf”) # multi-mol SDF results.filter(lambda g: len(g.nodes) > 2) # GroupGraphSet subset
GroupGraphSet is a set subclass: every existing pattern (iter, len, membership tests, comprehensions) keeps working unchanged.
- class Grouper.group_graph_set.GroupGraphSet
Bases:
setA set[GroupGraph] with batch-conversion methods.
Returned by exhaustive_generate, random_generate, and exhaustive_fragment (instead of a plain set). Subclasses set so every existing pattern — iteration, len, in, set algebra — works unchanged. The added methods are pure conveniences.
Note that set operations like .union(other) from the base class return a plain set, not a GroupGraphSet. Wrap explicitly if you need the methods on the union result.
- filter(predicate)
Return a new GroupGraphSet containing only graphs for which predicate(graph) is True. Standard list/set comprehensions return a plain set; this returns the wrapper so chained calls keep the convenience methods.
- Return type:
- sample(n, seed=None)
Return a uniformly-random subset of n graphs.
seed makes the sample reproducible — useful when you want the same subset across re-runs of a screening notebook. Sets are unordered in Python, so the sample’s “starting position” is whatever the hash table dictates; combined with a seeded RNG the result is deterministic for a given Python build.
Raises ValueError if n > len(self) (matching random.sample semantics so the failure mode is recognizable).
- Return type:
- to_csv(path, properties=None, sort_by='smiles', **df_kwargs)
Write to CSV via to_dataframe(…).to_csv(…).
Defaults to sort_by=”smiles” so the on-disk file is deterministic across runs (sets are unordered). Pass sort_by=None to skip sorting if order doesn’t matter or if you’ve already sorted upstream.
Returns the path that was written, so calls can chain into further file operations.
- Return type:
- to_dataframe(properties=None, include_groupgraph=False, skip_failures=False, sort_by=None)
Flatten the set into a pandas DataFrame, one row per graph.
Always-present columns: smiles, n_nodes.
properties=[“joback”] (or a list of estimator classes) adds prefixed columns for each estimator’s output — e.g. joback.Tb, joback.Tc, … so multiple estimators don’t collide on common field names like MW or n_atoms.
include_groupgraph=True adds a graph column with the underlying GroupGraph objects (handy for further processing from the DataFrame, at the cost of not being JSON/CSV serializable).
skip_failures=True catches exceptions from the property estimators (e.g. JobackUnsupportedAtomError on a graph containing Si) and writes None into the affected columns. Default is to raise so silent garbage doesn’t leak through.
sort_by=”smiles” (or any column name) returns a sorted DataFrame for reproducibility — sets have no inherent order.
- to_jsonl(path, properties=None, sort_by='smiles', **df_kwargs)
Write to JSON Lines (one JSON object per row) via to_dataframe(…).to_json(orient=’records’, lines=True).
JSONL is the de-facto interchange format for ML training pipelines (HuggingFace datasets, JAX/Flax dataloaders) and is a more honest serialization of mixed-type data than CSV.
- Return type:
- to_sdf(path, properties=None, embed_3d=True, skip_failures=True, **embed_kwargs)
Write every graph to a multi-molecule SDF.
Delegates to Grouper.exports.to_sdf with the set as the iterable target. If properties is given, each molecule’s SDF entry carries the predicted property values as > <KEY> blocks — feeds straight into KNIME, RDKit’s PandasTools.LoadSDF, or any tool that reads SD properties.
Returns the number of molecules successfully written.
- Return type: