🧹 Filters

Submodules

hypergraphx.filters.metadata_filters module

hypergraphx.filters.metadata_filters.filter_hypergraph(hypergraph, node_criteria=None, edge_criteria=None, mode='keep', keep_edges=False, *, inplace=True, node_criteria_mode='all', edge_criteria_mode='all')[source]

Filters nodes and edges of a hypergraph based on metadata attributes and allowed values.

Parameters:

  • hypergraph (object) – The hypergraph instance to filter. Must have _node_metadata and _edge_metadata attributes, along with remove_node and remove_edge methods.

  • node_criteria (dict, optional) – A dictionary specifying metadata attribute keys and allowed values for nodes. Example: {“type”: [“person”, “animal”]}.

  • edge_criteria (dict, optional) – A dictionary specifying metadata attribute keys and allowed values for edges. Example: {“relationship”: [“friendship”, “collaboration”]}.

  • mode (str, optional) – Either “keep” to retain only matching nodes and edges, or “remove” to discard them. Default is “keep”.

  • keep_edges (bool, optional) – If False (default), edges involving removed nodes are fully removed. If True, edges are kept but the removed nodes are excluded from the edges.

  • node_criteria_mode ({"all", "any"}, optional) – How to combine multiple node criteria. Default is “all”.

  • edge_criteria_mode ({"all", "any"}, optional) – How to combine multiple edge criteria. Default is “all”.

Returns:

If inplace=True (default), the hypergraph is modified in place and None is returned. If inplace=False, a filtered copy is returned.

Return type:

object | None

Raises:

ValueError – If the mode is not “keep” or “remove”.

hypergraphx.filters.statistical_filters module

hypergraphx.filters.statistical_filters.get_svc(hypergraph, min_order=2, max_order=None, alpha=0.01, mp=False, n_jobs=None, max_groups=None)[source]

Extract the Statistically Validated Cores.

Parameters:

  • hypergraph (Hypergraph) – Hypergraph object for which the SVS will be extracted.

  • min_order (int) – Minimum size of the hyperlinks to be tested

  • max_order (int) – Maximum size of the hyperlinks to be tested

  • alpha (float) – Threshold of statistical significance for FDR validation.

  • mp (bool (default: False)) – Specify whether to use multiprocessing or not.

  • n_jobs (int, optional) – Number of worker processes to use when mp=True. Defaults to cpu_count().

  • max_groups (int, optional) – Guardrail: maximum number of groups tested per order. If exceeded, raises a ValueError.

Returns:

svs – The DataFrame is a Table with columns [‘edge’,’pvalue’,’fdr’]. ‘group’ contains all the cores (mapped as tuples) tested in the hypergraph ‘pvalue’ reports the pvalue ‘fdr’ is a bool that is True if the core has been validated, False otherwise

Return type:

DataFrame

hypergraphx.filters.statistical_filters.get_svh(hypergraph, max_order=10, alpha=0.01, mp=False, n_jobs=None, max_tests_per_order=None)[source]

Extract the Statistically Validated Hypergraph.

Parameters:

  • hypergraph (Hypergraph) – Hypergraph object for which the SVH will be extracted.

  • max_order (int) – Maximum order of the hyperlinks to be tested

  • alpha (float) – Threshold of statistical significance for FDR validation.

  • mp (Bool (default: False)) – Specify whether to use multiprocessing or not.

  • n_jobs (int, optional) – Number of worker processes to use when mp=True. Defaults to cpu_count().

  • max_tests_per_order (int, optional) – Guardrail: maximum number of hypothesis tests per order. If exceeded, raises a ValueError.

Returns:

svh – Dictionary where key is the order and value is a DataFrame with the result of validation. Each DataFrame is a Table with columns [‘edge’,’pvalue’,’fdr’]. ‘edge’ contains all the hyperlinks (mapped as tuples) present in the hypergraph ‘pvalue’ reports the pvalue ‘fdr’ is a bool that is True if the hyperlink belongs to the SVH, False otherwise

Return type:

dict

Module contents

Selection / validation utilities.

Public API: - filter_hypergraph: metadata-based node/edge filtering (supports inplace= and callable criteria). - get_svh, get_svc: statistically validated hyperlinks/cores (safe defaults: mp=False).

Next steps