MHCXGraph.utils.preprocessing

class MHCXGraph.utils.preprocessing.GraphSpec(orig_path, base_name, graph_config, settings, output_path, selection_params)

Bases: object

A deferred subgraph build.

Carries everything needed to materialize one filtered subgraph, but builds nothing until .build() is called. Exposes .path/.name so callers can identify a protein without paying its construction cost.

Indexing mirrors the old (subgraph, path, base_name) tuple after build, so clean_graph_name(spec) and spec[1] keep working unchanged.

build() → Graph

exception MHCXGraph.utils.preprocessing.LogicError

Bases: Exception

Raised when a logical selection expression cannot be evaluated.

MHCXGraph.utils.preprocessing.collect_selected_files_from_manifest(manifest)

Collect structure files defined in the manifest input rules.

Parameters:

manifest (dict) – Manifest configuration dictionary.

Returns:

selected_files – List of dictionaries describing selected input files.

Return type:

list[dict]

MHCXGraph.utils.preprocessing.create_graphs(manifest: dict) → list[GraphSpec]

Construct deferred subgraph builders from the manifest input structures.

Rather than building every subgraph up front (which makes resident memory grow linearly with the number of proteins), this returns one GraphSpec per file. Callers decide when to materialize: ‘multiple’ builds all of them, ‘pairwise’/’screening’ build one or two at a time.

Returns:

One deferred builder per selected input structure.

Return type:

list[GraphSpec]

MHCXGraph.utils.preprocessing.get_exposed_residues(graph: Graph, rsa_filter: float, asa_filter: float, selection_params=None) → Graph

Generate a filtered subgraph containing exposed residues.

The function creates a residue subgraph based on solvent exposure criteria and optional structural or logical filters defined in the manifest.

Parameters:

• graph (Graph) – Graph representation of the protein structure.

• rsa_filter (float) – Relative solvent accessibility threshold.

• asa_filter (float) – Absolute solvent accessibility threshold.

• selection_params (dict[str, Any], optional) – Additional selection constraints such as chains, residues, secondary structure elements, or logical expressions.

Returns:

subgraph – Filtered graph containing the selected residues.

Return type:

networkx.Graph

Raises:

Exception – If no residues satisfy the filtering conditions.

MHCXGraph.utils.preprocessing.list_struct_files(folder: Path, extensions: list[str]) → list[Path]

Recursively list structure files inside a directory.

Parameters:

• folder (pathlib.Path) – Root directory to search.

• extensions (list[str]) – Allowed file extensions.

Returns:

files – Sorted list of structure file paths.

Return type:

list[pathlib.Path]

MHCXGraph.utils.preprocessing.resolve_selection_params_for_file(file_path: Path, manifest: dict[str, Any]) → dict[str, Any]

Resolve selection parameters for a specific input file.

Parameters:

• file_path (pathlib.Path) – Path to the structure file.

• manifest (dict[str, Any]) – Manifest configuration.

Returns:

params – Combined selector parameters applied to the file.

Return type:

dict[str, Any]

Classes

GraphSpec(orig_path, base_name, ...)

A deferred subgraph build.

Functions

collect_selected_files_from_manifest(manifest)	Collect structure files defined in the manifest input rules.
create_graphs(manifest)	Construct deferred subgraph builders from the manifest input structures.
get_exposed_residues(graph, rsa_filter, ...)	Generate a filtered subgraph containing exposed residues.
list_struct_files(folder, extensions)	Recursively list structure files inside a directory.
resolve_selection_params_for_file(file_path, ...)	Resolve selection parameters for a specific input file.

Exceptions

LogicError

Raised when a logical selection expression cannot be evaluated.