gcmpy package — gcmpy documentation

# gcmpy package

## Submodules

## gcmpy.distributions module

gcmpy.distributions.exponential(a: float) → Callable

  Implemnts an exponential distribution. :param a: distribution parameter :returns p: callable

gcmpy.distributions.log_normal()

gcmpy.distributions.poisson(kmean: float) → Callable

  Implements a poisson distribution.

  Parameters

    kmean – mean of poisson distribution

  Returns p

    Callable

gcmpy.distributions.power_law(alpha: float) → Callable

  Implements a power law distribution with exponent alpha. Undefined for k = 0.

  Parameters

    alpha – power law exponent

  Returns p

    callable

gcmpy.distributions.scale_free_cut_off(alpha: float, kappa: float) → Callable

  Implements a scale free with exponential degree cutoff function. Limits to scale free for large degree cutoff. Undefined for k = 0.

  Parameters

    - k – int degree

    - alpha – float power law exponent

    - kappa – float degree cutoff

gcmpy.distributions.weibull()

## gcmpy.gcm_algorithm module

class gcmpy.gcm_algorithm.GCM_algorithm(motif_sizes: List[int], build_functions: List[Callable[[gcmpy.types._NODES], gcmpy.types._EDGES]])

  Bases: `object`

  Generalised configuration model algorithm.

  Parameters

    - num_networks – the number of networks to create

    - motif_sizes – list of ints that indicate the number of nodes in each motif

    - build_functions – callbacks that accept list of nodes and return edges

  random_clustered_graph(jds: gcmpy.types._JDS) → gcmpy.utils.edge_list

    Generate a random graph from a given joint degree sequence of motifs. If motif constructors are not specified, ValueError is raised.

    Parameters

      jds – joint degree sequence

    Returns

      a list of edges in the graph as an edge_list object

class gcmpy.gcm_algorithm.ResampleJDS(num_networks: int, motif_sizes: List[int], build_functions: List[Callable[[gcmpy.types._NODES], gcmpy.types._EDGES]], network_name: Optional[str] = None)

  Bases: `gcmpy.gcm_algorithm.GCM_algorithm`

  Resamples a joint degree sequence to create multiple networks.

  Parameters

    - num_networks – the number of networks to create

    - motif_sizes – list of ints that indicate the number of nodes in each motif

    - network_name – string identifier/classifier for network

    - build_functions – callbacks that accept list of nodes and return edges

  random_clustered_graph_from_resampled_jds(jds: gcmpy.types._JDS) → gcmpy.utils.results

    Routine to create multiple configuration model networks from a single joint degree sequence. This essentially rewires a given sequence of joint degrees using the configuration model.

    Parameters

      jds – joint degree sequence

    Returns results

      data of constructed networks

## gcmpy.joint_degree module

class gcmpy.joint_degree.JDD_Interface(modulo)

  Bases: `object`

  Joint degree distribution interface. Subclasses will define how self._jdd is created, and all implementations should do so upon construction.

  Parameters

    modulo – list of integers for number of nodes in each motif

  convert_jds_to_jdd(jds: gcmpy.types._JDS)

    Convert a joint degree sequence to self._jdd.

    Parameters

      jds – joint degree sequence

  normalise_jdd()

    Normalises self._jdd probability distribution.

  sample_JDS(N: int) → gcmpy.types._JDS

    Method to ensure the sum of the motifs in each dimension mod modulo[i] (which is the number of vertices in each motif) is zero by adding motifs to the motif list. This ensures the JDS is graphic.

    Parameters

      N – number of samples

    Returns jds

      joint degree sequnce

class gcmpy.joint_degree.JDD_clique_cover(C: gcmpy.types._COVER)

  Bases: `gcmpy.joint_degree.JDD_Interface`

  Creates self._jdd from a list of cliques in the network. The sizes of the cliques can be obtained from the self._modulo member.

  create_jdd() → None

class gcmpy.joint_degree.JDD_delta_model(fp: Callable, modulo: List[int], probs: List[float], target_k: int, kmin: int, kmax: int)

  Bases: `gcmpy.joint_degree.JDD_split_K_model`

  A distribution of single edges apart from a specified target degree. For instance a distribution of degrees in a single dimension (2-cliques) with zeros for all other motif type counts, apart from when k=target.

  create_jdd() → None

    Creates self._jdd using the degree delta model.

class gcmpy.joint_degree.JDD_empirical_data(jds: gcmpy.types._JDS, modulo: List[int])

  Bases: `gcmpy.joint_degree.JDD_Interface`

  An empirical joint degree sequence is used to create self._jdd. :param jds: joint degree sequence

class gcmpy.joint_degree.JDD_joint_function(fp: Callable, modulo: List[int], hi_lo_degree_bounds: Tuple[int, int], use_sampling: bool = False, n_samples: int = 100000.0)

  Bases: `gcmpy.joint_degree.JDD_Interface`

  Multivariate function to evaluate the probability of given joint degree from an analytical source. Note, callable self._fp must accept a joint degree tuple and return a float.

  Parameters

    - fp – callback

    - modulo – list of ints for number of vertices in each motif

    - hi_lo_degree_bounds – list of tuples (int,int) for kmin,kmax per topology

    - use_sampling – bool to use sampling or direct approach

    - n_samples – number of samples if not direct

class gcmpy.joint_degree.JDD_manual(jdd: gcmpy.types._JDD, modulo: List[int])

  Bases: `gcmpy.joint_degree.JDD_Interface`

  Specify self._jdd by hand. :param jdd: joint degree distribution

class gcmpy.joint_degree.JDD_marginals(arr_fp: List[Callable], modulo: List[int], hi_lo_degree_bounds: List[Tuple[int, int]], use_sampling: bool = False, n_samples: int = 100000.0)

  Bases: `gcmpy.joint_degree.JDD_Interface`

  Merge uncorrelated marginals in each topology from analytical data together to create self._jdd. If using a direct method, all possible joint degree tuples are evaluated; however, for large varience in the allowed degrees this method is slow. Instead, we can choose to sample the analytical functions by setting use_sampling which draws n_samples weighted samples from each marginal function.

  Parameters

    - arr_fp – array of callbacks

    - modulo – list of ints for number of vertices in each motif

    - hi_lo_degree_bounds – list of tuples (int,int) for kmin,kmax per topology

    - use_sampling – bool to use sampling or direct approach

    - n_samples – number of samples if not direct

class gcmpy.joint_degree.JDD_split_K_model(fp: Callable, modulo: List[int], probs: List[float], kmin: int, kmax: int)

  Bases: `gcmpy.joint_degree.JDD_Interface`

  An overall degree distribution is split with probabilities of creating each motif.

  calc_prob_of_joint_degree(jd: gcmpy.types._JOINT_DEGREE) → float

    calculates the probability of a joint degree from the input params.

    Parameters

      jd – joint degree

    Returns probability

      float value

  create_jdd() → None

    Creates self._jdd using the split degree model

  get_valid_joint_degrees(remaining_degree: int, topology: int) → List[gcmpy.types._JOINT_DEGREE]

    Returns a list of tuples by recursion. Only an ordered list of cliques are currently supported.

    Parameters

      - remaining_degree – current free edges that can be partitioned

      - topology – column index of joint degree tuple

    :returns list of joint degrees

  resolve_degree(k: int, prob_overall_k: float) → None

    creates all valid joint degrees for overall k and their probability and updates self._jdd.

    Parameters

      - k – overall degree

      - prob_overall_k – float value

## gcmpy.motif_generators module

gcmpy.motif_generators.clique_motif(nodes: gcmpy.types._NODES) → List[gcmpy.types._EDGE]

  Accepts list of ints and creates all possible pairs which it returns as a list of tuples of int pairs

  Parameters

    nodes – list of nodes (int)

  Returns

    edge list as list of tuples (int, int)

gcmpy.motif_generators.cycle_motif(nodes: gcmpy.types._NODES) → List[gcmpy.types._EDGE]

  Accepts a list of ints and creates a cycle of adjacent node pairs. Creates two iterators and then increments one before zipping together to create tuples. Finally, connects the start and end of the chain toegher.

  Parameters

    nodes – list of nodes (int)

  Returns

    edge list as list of tuples (int, int)

gcmpy.motif_generators.diamond_motif(nodes: gcmpy.types._NODES) → List[gcmpy.types._EDGE]

  Accepts list of ints and creates edge pairs for a diamond motif of 4 vertices.

  Parameters

    nodes – list of nodes (int)

  Returns

    edge list as list of tuples (int, int)

## gcmpy.types module

## gcmpy.utils module

class gcmpy.utils.edge_list

  Bases: `object`

  Network represented as an edge list. The GCM class uses this structure to generate networks which can then be converted to other network libraries.

  add_edge(e: gcmpy.types._EDGE)

    Adds an edge to the networkx

  add_edges_from(edges: gcmpy.types._EDGES) → None

    Adds edges from list of tuples (int,int) to the edge list. :param edges: list of tuples of ints.

  find_cliques()

    Returns all maximal cliques in an undirected graph by converting the edge list to a nx graph object first.

  has_edges() → bool

    True if graph has edges remaining

  remove_edge(i: int, j: int) → None

    Removes edge (i,j) from G. Assumes i<j and no duplicates.

class gcmpy.utils.output_data(i: int)

  Bases: `object`

  An object to store output data from the process. :param i: integer for experiment index

class gcmpy.utils.results

  Bases: `object`

  A collection of output_data objects that can be serialised and converted to other graph formats.

  add_result(r: gcmpy.utils.output_data) → None
  read_results_from_binary_file(filename: str) → None

    read the results structure from a binary file. :param filename: name of the file to read.

  serialise_results_to_file(filename: str) → None

    Dump the results structure to a binary file. :param filename: name of file to create.

## Module contents