booldog.utils.cytoscape_utils

Helpers for exporting Cytoscape network views to image files, and for extracting node-induced subgraphs, via py4cytoscape. Requires a running Cytoscape instance (with the CyREST API reachable) to talk to.

Functions

export_network(suid, filename[, format, ...])

Export a Cytoscape network view to an image file.

extract_subnetwork(suid, seed_nodes[, ...])

Extract the node set (and, optionally, a Cytoscape subnetwork) of

_find_incomplete_hyperedge(node_names, edge_table, ...)

Find a gate in node_names whose inputs are only partly included.

Module Contents

booldog.utils.cytoscape_utils.export_network(suid, filename, format='png', overwrite_file=True, zoom=200)

Export a Cytoscape network view to an image file.

Fits the view to its content, clears any node/edge selection (so selection highlighting does not show up in the exported image), and exports the current view of the network identified by suid via py4cytoscape.network_views.export_image.

Parameters:

  • suid (int or str) – The Cytoscape network SUID (or, per py4cytoscape convention, a network name) identifying the network/view to export.

  • filename (str or Path) – Path of the image file to write. Coerced to str before being passed on to py4cytoscape.

  • format (str, default "png") – Image format to export, passed as py4cytoscape’s type argument (e.g. “png”, “pdf”, “svg”, …).

  • overwrite_file (bool, default True) – Whether to overwrite filename if it already exists.

  • zoom (int, default 200) – Zoom percentage applied to the exported image.

Return type:

None

Notes

py4cytoscape.network_views.fit_content fits the view to node positions only: it ignores edges/edge labels that extend beyond node boundaries, so such elements can be clipped in the exported image. This is a known Cytoscape limitation (reported as CSD-979); the Cytoscape developers’ response was “won’t fix”.

booldog.utils.cytoscape_utils.extract_subnetwork(suid, seed_nodes, boundary_node_types=('species',), direction='predecessors', node_type_column='type', subnetwork_name=None, verify=True)

Extract the node set (and, optionally, a Cytoscape subnetwork) of the hyperedge-closed neighbourhood of seed_nodes in a BoolDog logic-circuit network.

A logic_circuit-style network (see BoolDogModelIOToMixin.to_networkx with as_logic_circuit=True) represents each Boolean rule as species nodes feeding into logical_and/logical_or/logical_not gate nodes, which in turn feed the regulated species. A gate’s set of incoming edges is a single hyperedge: all of its inputs are one unit of meaning, so a naive “N-hop neighbours” traversal can silently include only some of a gate’s inputs and change what the extracted subgraph actually means. This function instead walks node-by-node, and whenever it reaches a gate node it always includes all of that gate’s inputs (its whole incoming hyperedge, also when walking downstream) as well as following its edges in direction - so no hyperedge is ever partially included - and only stops expanding at nodes whose type is in boundary_node_types (typically "species", i.e. regulator species one hop upstream of a seed, in their entirety as single nodes rather than expanding into their own regulators).

Parameters:

  • suid (int or str) – The Cytoscape network SUID (or network name) to read from.

  • seed_nodes (iterable of str) – Names of the node(s) to grow the subgraph from (e.g. the species whose regulators/targets should be included). Always fully expanded regardless of their own type, even if that type is also in boundary_node_types.

  • boundary_node_types (iterable of str, default ("species",)) – Node types (per node_type_column) at which traversal stops: such a node is included in the result but its own predecessors/successors are not walked into. Compare against the network’s "type" node column, e.g. {"species", "logical_and", "logical_or", "logical_not"}.

  • direction ({"predecessors", "successors"}, default "predecessors") – Whether to walk upstream (regulators of seed_nodes, following edges backward) or downstream (what seed_nodes regulate, following edges forward).

  • node_type_column (str, default "type") – Name of the node table column identifying each node’s type, checked against boundary_node_types.

  • subnetwork_name (str or None, optional) – If given, select the extracted node set and create a Cytoscape subnetwork from it (via py4cytoscape.networks.create_subnetwork) named subnetwork_name, clearing any prior selection first. Default None (no subnetwork is created; suid’s own selection is left untouched).

  • verify (bool, default True) – If True, after the walk, independently check for every non-boundary (gate-type) node in the result that the sources of all of its incoming edges in the full, unfiltered edge table are also present in the result - i.e. that no hyperedge was partially included, whatever the direction. Raises ValueError naming the first violation found if this check fails; such a violation would indicate a bug in this function rather than anything about the input network.

Returns:

  • node_names (set of str) – Names of all nodes in the extracted subgraph (seeds, gate nodes, and boundary-type nodes reached along the way).

  • subnetwork_suid (int, optional) – SUID of the created subnetwork; only returned if subnetwork_name was given.

Raises:

ValueError – If direction is not one of "predecessors"/"successors", or (when verify is True) if a hyperedge was found to be only partially included in the result.

booldog.utils.cytoscape_utils._find_incomplete_hyperedge(node_names, edge_table, name_to_type, boundary_node_types)

Find a gate in node_names whose inputs are only partly included.

Built directly from the full edge table (independent of the walk in extract_subnetwork), this checks every node in node_names whose type is not in boundary_node_types for incoming edges from nodes outside node_names.

Parameters:

  • node_names (set of str) – Names of the nodes in the extracted subgraph.

  • edge_table (pandas.DataFrame) – The full edge table, with "source" and "target" columns of node names.

  • name_to_type (dict) – Mapping of node name to node type.

  • boundary_node_types (iterable of str) – Node types that are not checked (see extract_subnetwork).

Returns:

(node, missing_source) for the first incomplete hyperedge found, or None if every checked node has all of its inputs in node_names.

Return type:

tuple of (str, str) or None