graph-tool

https://graph-tool.skewed.de/static/docs/stable/
Admin
graph-tool is an efficient Python module for manipulation and statistical analysis of graphs...
Tokens:544,660
Snippets:2,006
Trust Score:8.4
Update:1 year ago
Show doc for...
Tokens:
Raw
### Import graph-tool Modules

Source: https://graph-tool.skewed.de/static/docs/stable/_sources/quickstart

Imports all necessary components from the graph-tool library. This is a prerequisite for using any graph-tool functionalities. Ensure the graph_tool library is installed.

```python
from graph_tool.all import *

```

--------------------------------

### Load and Visualize Facebook Social Network in graph-tool

Source: https://graph-tool.skewed.de/static/docs/stable/_sources/quickstart

Loads the 'ego_social/facebook_combined' network from the graph-tool collection and visualizes its structure. This example requires the graph_tool library and demonstrates basic network loading and drawing functionalities.

```python
from graph_tool.all import *
g = collection.ns["ego_social/facebook_combined"]
graph_draw(g, g.vp._pos, output="facebook.pdf")
```

--------------------------------

### Load and Draw Graph for Search Examples (Python)

Source: https://graph-tool.skewed.de/static/docs/stable/search_module

This code snippet demonstrates how to load a graph from an XML file and draw it with specific vertex and edge properties. It is used as a common setup for various search algorithm examples within the graph-tool library. It requires the graph-tool library to be installed and the 'search_example.xml' file to be accessible.

```python
>>> g = gt.load_graph("../search_example.xml")
>>> name = g.vp["name"]
>>> weight = g.ep["weight"]
>>> pos = g.vp["pos"]
>>> gt.graph_draw(g, pos, vertex_text=name, vertex_font_size=12, vertex_shape="double_circle",
...               vertex_fill_color="#729fcf", vertex_pen_width=3,
...               edge_pen_width=weight, output="search_example.svg")
<...>

```

--------------------------------

### Setup Animations Environment

Source: https://graph-tool.skewed.de/static/docs/stable/_sources/demos/animation/animation

This setup code prepares the environment for animation examples by changing the directory and copying necessary PNG files. It uses Python's `glob` and `shutil` modules for file operations.

```python
mkchdir(DOC_DIR + "/demos/animation/output")

import glob
import shutil
for file in glob.glob(r'../*png'):
    shutil.copy(file, ".")
```

--------------------------------

### Import all graph-tool modules

Source: https://graph-tool.skewed.de/static/docs/stable/quickstart

Imports all necessary components from the graph-tool library. This is the first step before using any graph-tool functionalities. It makes all classes and functions available directly.

```python
>>> from graph_tool.all import *

```

--------------------------------

### Saving and Loading Graphs with graph-tool

Source: https://graph-tool.skewed.de/static/docs/stable/_sources/quickstart

Demonstrates the basic usage of saving a graph to a file using the '.gt.gz' format and then loading it back. This process ensures that the graph structure and its properties are preserved.

```python
g = Graph()
#  ... fill the graph ...
g.save("my_graph.gt.gz")
g2 = load_graph("my_graph.gt.gz")
# g and g2 should be identical copies of each other
```

--------------------------------

### Iterating Over Vertices and Edges

Source: https://graph-tool.skewed.de/static/docs/stable/_sources/quickstart

This section provides details on how to iterate through all vertices and edges within a graph.

```APIDOC
## Iterate Over All Vertices

### Description
Iterates through all vertices in the graph, yielding their descriptors.

### Method
`vertices()`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
# Assuming 'g' is a graph object
for v in g.vertices():
    print(v)
```

### Response
#### Success Response (200)
- **vertex_descriptor** (descriptor) - A descriptor for each vertex in the graph.

#### Response Example
```
# Example output (depends on graph content):
0
1
2
...
```

## Iterate Over All Edges

### Description
Iterates through all edges in the graph, yielding their descriptors.

### Method
`edges()`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
# Assuming 'g' is a graph object
for e in g.edges():
    print(e)
```

### Response
#### Success Response (200)
- **edge_descriptor** (descriptor) - A descriptor for each edge in the graph.

#### Response Example
```
# Example output (depends on graph content):
(0, 1)
(2, 3)
...
```
```

--------------------------------

### Visualize Graph with Properties

Source: https://graph-tool.skewed.de/static/docs/stable/_sources/quickstart

Visualizes a graph using property maps for styling. 'vertex_fill_color' and 'edge_pen_width' are set using the previously defined vertex and edge property maps, allowing for customized graph appearance.

```python
graph_draw(g, vertex_text=g.vertex_index, vertex_fill_color=vcolor,
           edge_pen_width=eweight, output="two-nodes-color.svg")

```

--------------------------------

### Vertex and Edge Removal

Source: https://graph-tool.skewed.de/static/docs/stable/_sources/quickstart

This section explains how to remove vertices and edges from a graph. It covers the performance implications and alternative methods for efficient removal.

```APIDOC
## Vertex Removal

### Description
Removes a specified vertex from the graph. Property map values are automatically updated.

### Method
`remove_vertex(vertex)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **vertex** (descriptor) - The descriptor of the vertex to remove.

### Request Example
```python
# Assuming 'g' is a graph object and 'v' is a vertex descriptor
g.remove_vertex(v)
```

### Response
#### Success Response (200)
None (operation is performed in-place)

#### Response Example
None

## Fast Vertex Removal

### Description
Allows for O(1) vertex removal by swapping the vertex to be deleted with the last vertex in the internal list. This invalidates the relative vertex ordering.

### Method
`remove_vertex(vertex, fast=True)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **vertex** (descriptor) - The descriptor of the vertex to remove.
- **fast** (boolean) - If True, enables fast removal. Defaults to False.

### Request Example
```python
# Assuming 'g' is a graph object and 'v' is a vertex descriptor
g.remove_vertex(v, fast=True)
```

### Response
#### Success Response (200)
None (operation is performed in-place)

#### Response Example
None

## Edge Removal

### Description
Removes an edge between two vertices. The operation is O(k_s + k_t), where k_s and k_t are the out-degree of the source and in-degree of the target vertex, respectively. Can be made O(1) with `set_fast_edge_removal`.

### Method
`remove_edge(edge)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **edge** (descriptor) - The descriptor of the edge to remove.

### Request Example
```python
# Assuming 'g' is a graph object and 'e' is an edge descriptor
g.remove_edge(e)
```

### Response
#### Success Response (200)
None (operation is performed in-place)

#### Response Example
None

## Fast Edge Removal

### Description
Enables O(1) edge removal at the expense of additional data storage.

### Method
`set_fast_edge_removal(enable)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **enable** (boolean) - Set to True to enable fast edge removal.

### Request Example
```python
g.set_fast_edge_removal(True)
```

### Response
#### Success Response (200)
None (operation is performed in-place)

#### Response Example
None
```

--------------------------------

### Create an empty graph in Python

Source: https://graph-tool.skewed.de/static/docs/stable/quickstart

Demonstrates how to instantiate a new, empty graph object. By default, graphs created this way are directed. This is a fundamental step for building any graph-based structure.

```python
>>> g = Graph()

```

--------------------------------

### Iterate Through Vertex Property Map Values (Python)

Source: https://graph-tool.skewed.de/static/docs/stable/quickstart

Shows how to iterate through the values of a vertex property map and display the first ten elements as a list.

```python
print(list(vprop)[:10])
```

--------------------------------

### Internalizing Graph Properties and Values

Source: https://graph-tool.skewed.de/static/docs/stable/_sources/quickstart

Illustrates the behavior of internal graph property maps, showing how to set both the property map object and its value. It also demonstrates deleting the property map entry from the dictionary.

```python
>>> gprop = g.new_graph_property("int")
>>> g.gp["foo"] = gprop                 # this sets the actual property map
>>> g.gp["foo"] = 42                    # this sets its value
>>> print(g.gp["foo"])
42
>>> del g.gp["foo"]                     # the property map entry is deleted from the dictionary
```

--------------------------------

### Create an Empty Graph

Source: https://graph-tool.skewed.de/static/docs/stable/_sources/quickstart

Demonstrates how to create a new, empty graph object. By default, graphs are directed. The 'directed' parameter can be set to False for undirected graphs. This is fundamental for all graph operations.

```python
g = Graph()
ug = Graph(directed=False)

```

--------------------------------

### Get In-Degree of a Vertex

Source: https://graph-tool.skewed.de/static/docs/stable/quickstart

Shows how to query the in-degree of a vertex using the `in_degree()` method. This is analogous to `out_degree()` and is useful for directed graphs.

```python
# Assuming 'g' is a Graph object and 'v' is a vertex descriptor
# print(v.in_degree())
```

--------------------------------

### Get Out-Degree of a Vertex in graph-tool

Source: https://graph-tool.skewed.de/static/docs/stable/_sources/quickstart

Demonstrates how to retrieve the out-degree of a specific vertex in a graph-tool graph. This method is essential for understanding the connectivity of a vertex.

```python
from graph_tool.all import *

g = Graph()
v1 = g.add_vertex()
v2 = g.add_vertex()
e = g.add_edge(v1, v2)
print(v1.out_degree())
```

--------------------------------

### Get Out-Degree of a Vertex

Source: https://graph-tool.skewed.de/static/docs/stable/quickstart

Demonstrates how to retrieve the out-degree of a vertex in a graph using the `out_degree()` method. This is a fundamental operation for understanding vertex connectivity.

```python
>>> g = Graph()
>>> v1 = g.add_vertex()
>>> v2 = g.add_vertex()
>>> e = g.add_edge(v1, v2)
>>> print(v1.out_degree())
1
```

--------------------------------

### Use Transformations for Function Arguments (Python)

Source: https://graph-tool.skewed.de/static/docs/stable/quickstart

Provides an example of using the `transform()` method to create temporary properties that can be passed as arguments to graph algorithms, such as `sfdp_layout`.

```python
erand = g.new_ep("double", vals=random(g.num_edges()) - .5)
pos = sfdp_layout(g, eweight=erand.t(abs))
```

--------------------------------

### Get Source and Target of an Edge in graph-tool

Source: https://graph-tool.skewed.de/static/docs/stable/_sources/quickstart

Shows how to obtain the source and target vertex descriptors for a given edge in a graph-tool graph. This is useful for traversing graph structures.

```python
from graph_tool.all import *

g = Graph()
v1 = g.add_vertex()
v2 = g.add_vertex()
e = g.add_edge(v1, v2)
print(e.source(), e.target())
```

--------------------------------

### Initialize and Run PottsMetropolisState Example (Python)

Source: https://graph-tool.skewed.de/static/docs/stable/autosummary/graph_tool.dynamics

This example demonstrates how to initialize a PottsMetropolisState object with a graph and interaction matrix, then iterate the dynamics asynchronously and visualize the results. It requires the graph-tool and numpy libraries.

```python
>>> g = gt.GraphView(gt.collection.data["polblogs"].copy(), directed=False)
>>> gt.remove_parallel_edges(g)
>>> g = gt.extract_largest_component(g, prune=True)
>>> f = np.eye(4) * 0.1
>>> state = gt.PottsGlauberState(g, f)
>>> ret = state.iterate_async(niter=1000 * g.num_vertices())
>>> gt.graph_draw(g, g.vp.pos, vertex_fill_color=state.s,
...               output="metropolis-potts.svg")
<...>
```

--------------------------------

### Get Vertex Index

Source: https://graph-tool.skewed.de/static/docs/stable/quickstart

Shows how to retrieve the unique index of a vertex using either the `vertex_index` property map of the graph or by directly converting the vertex descriptor to an integer.

```python
>>> v = g.add_vertex()
>>> print(g.vertex_index[v])
12
>>> print(int(v))
12
```

--------------------------------

### Setup for Network Reconstruction Simulation

Source: https://graph-tool.skewed.de/static/docs/stable/_sources/demos/reconstruction_indirect/reconstruction

Initializes the simulation environment by setting the current directory and seeding the random number generators for reproducibility. This setup is crucial before generating or processing network data.

```python
import numpy as np
import graph_tool as gt
from pathlib import Path

DOC_DIR = Path.cwd()
mkchdir(DOC_DIR / "demos/reconstruction_indirect/output")
np.random.seed(42)
gt.seed_rng(42)
```

--------------------------------

### Get Edge Source and Target Vertices

Source: https://graph-tool.skewed.de/static/docs/stable/quickstart

Illustrates how to obtain the source and target vertex descriptors of an edge using the `source()` and `target()` methods. This is essential for understanding edge relationships.

```python
>>> print(e.source(), e.target())
0 1
```

--------------------------------

### GraphView and Potts Model State Initialization

Source: https://graph-tool.skewed.de/static/docs/stable/_modules/graph_tool/dynamics/bp

Demonstrates the initialization of a GraphView, extraction of the largest component, and setting up a GenPottsBPState with interaction parameters. Includes an example of drawing the graph with sampled marginals.

```APIDOC
## POST /graph-tool/genpottsbpstate

### Description
Initializes a GenPottsBPState for a given graph and interaction parameters. This endpoint allows for the setup and sampling of states for a Potts model on a graph.

### Method
POST

### Endpoint
/graph-tool/genpottsbpstate

### Parameters
#### Path Parameters
None

#### Query Parameters
* **directed** (boolean) - Optional - Whether the graph is directed.
* **prune** (boolean) - Optional - Whether to prune the graph to its largest component.
* **marginal_init** (boolean) - Optional - Whether to initialize with marginals.
* **converge** (boolean) - Optional - Whether to converge the state upon initialization.

#### Request Body
* **g** (GraphView) - Required - The input graph.
* **f** (array) - Required - The interaction matrix for the Potts model.
* **x** (EdgePropertyMap) - Optional - Initial edge property map for messages.
* **theta** (VertexPropertyMap or Iterable) - Optional - Initial node property map for messages.
* **m** (EdgePropertyMap) - Optional - Initial edge property map for messages.
* **em** (EdgePropertyMap) - Optional - Initial edge property map for messages.
* **vm** (VertexPropertyMap) - Optional - Initial vertex property map for messages.
* **frozen** (VertexPropertyMap) - Optional - Initial vertex property map indicating frozen nodes.

### Request Example
```json
{
  "g": "<graph_object>",
  "f": [[1, 0, -1], [0, 1, -1], [-1, -1, 1.25]]
}
```

### Response
#### Success Response (200)
* **state** (GenPottsBPState) - The initialized Potts BP state.

#### Response Example
```json
{
  "state": "<potts_bp_state_object>"
}
```
```

--------------------------------

### Access Karate Graph README using graph-tool

Source: https://graph-tool.skewed.de/static/docs/stable/collection

This example shows how to access and print the README information associated with the 'karate' graph dataset using the graph-tool library. This requires the graph-tool library to be installed and the 'karate' graph to be loaded. The output provides citation and description details for the dataset.

```python
>>> print(g.gp.readme)
The file karate.gml contains the network of friendships between the 34
members of a karate club at a US university, as described by Wayne Zachary
in 1977.  If you use these data in your work, please cite W. W. Zachary, An
information flow model for conflict and fission in small groups, Journal of
Anthropological Research 33, 452-473 (1977).


```

--------------------------------

### Draw graph with labels and output to SVG in Python

Source: https://graph-tool.skewed.de/static/docs/stable/quickstart

Demonstrates visualizing a graph using `graph_draw()`. This example specifies vertex text labels using `g.vertex_index` and saves the output to an SVG file named 'two-nodes.svg'.

```python
>>> graph_draw(g, vertex_text=g.vertex_index, output="two-nodes.svg")
<...>

```

--------------------------------

### Draw graph with property map attributes in Python

Source: https://graph-tool.skewed.de/static/docs/stable/quickstart

Visualizes a graph using `graph_draw()`, incorporating custom attributes from property maps. This example uses `vertex_fill_color` for vertex colors and `edge_pen_width` for edge weights, outputting to 'two-nodes-color.svg'.

```python
>>> graph_draw(g, vertex_text=g.vertex_index, vertex_fill_color=vcolor,
...            edge_pen_width=eweight, output="two-nodes-color.svg")
<...>

```

--------------------------------

### Load and Visualize Facebook Network using graph-tool

Source: https://graph-tool.skewed.de/static/docs/stable/quickstart

Loads a Facebook social network from the Netzschleuder repository using graph-tool's collection interface and visualizes the network structure, saving the output to a PDF file. Requires the graph-tool library.

```python
from graph_tool import collection, graph_draw

g = collection.ns["ego_social/facebook_combined"]
graph_draw(g, g.vp._pos, output="facebook.pdf")
```

--------------------------------

### Create and Access Graph-Tool Property Maps

Source: https://graph-tool.skewed.de/static/docs/stable/_sources/quickstart

Demonstrates the creation of vertex, edge, and graph property maps with different value types and how to assign and access values using descriptors and indices. Supports various data types including floats, vectors, and Python objects.

```python
from graph_tool.all import *
from numpy.random import randint

g = Graph()
g.add_vertex(100)

# insert some random links
for s, t in zip(randint(0, 100, 100), randint(0, 100, 100)):
    g.add_edge(g.vertex(s), g.vertex(t))

vprop = g.new_vertex_property("double")              # Double-precision floating point
v = g.vertex(10)
vprop[v] = 3.1416

vprop2 = g.new_vertex_property("vector<int>")        # Vector of ints
v = g.vertex(40)
vprop2[v] = [1, 3, 42, 54]

eprop = g.new_edge_property("object")                # Arbitrary Python object.
e = g.edges().next()
eprop[e] = {"foo": "bar", "gnu": 42}                 # In this case, a dict.

gprop = g.new_graph_property("bool")                 # Boolean
gprop[g] = True

print(vprop[10])
print(list(vprop)[:10])

g.add_edge(30, 40)
eprop[(30, 40)] = "gnat"

```

--------------------------------

### Get Edge Index in Graph-tool

Source: https://graph-tool.skewed.de/static/docs/stable/_sources/quickstart

Retrieves the unique index of an edge in a graph-tool graph. The edge index is a numerical identifier for the edge. This is useful for tracking or referencing specific edges. Edge indices may not be contiguous if edges have been removed.

```python
e = g.add_edge(g.vertex(0), g.vertex(1))
print(g.edge_index[e])
```

--------------------------------

### Get Vertex Descriptor by Index in Graph-tool

Source: https://graph-tool.skewed.de/static/docs/stable/_sources/quickstart

Retrieves a vertex descriptor from a graph-tool graph using its index. This method is useful when the index is known but the descriptor is not readily available. It takes an integer index as input and returns a vertex descriptor.

```python
v = g.vertex(8)
```

--------------------------------

### PPBlockState Methods

Source: https://graph-tool.skewed.de/static/docs/stable/_modules/graph_tool/inference/planted_partition

Provides documentation for various methods of the PPBlockState class, including copying state, retrieving block information, and calculating entropy.

```APIDOC
## PPBlockState Methods

### Description
Provides methods for copying the state, retrieving block information, and calculating entropy related to the Bayesian planted partition model.

### Methods

#### `copy(g=None, b=None)`
Copies the state. The parameters override the state properties and have the same meaning as in the constructor.

- **g** (Graph, optional) - The graph to use for the new state.
- **b** (PropertyMap, optional) - The property map representing the partition for the new state.

#### `get_blocks()`
Returns the property map which contains the block labels for each vertex.

#### `get_state()`
Alias to `get_blocks()`.

#### `get_B()`
Returns the total number of blocks.

#### `get_nonempty_B()`
Alias to `get_B()`.

#### `get_Be()`
Returns the effective number of blocks, defined as e^H, with H = -sum(n_r/N * ln(n_r/N)), where n_r is the number of nodes in group r.

#### `virtual_vertex_move(v, s, **kwargs)`
Computes the entropy difference if vertex 'v' is moved to block 's'. The remaining parameters are the same as in `entropy()`.

- **v** (int) - The vertex to move.
- **s** (int) - The target block.
- **kwargs**: Additional arguments for the entropy calculation.

#### `move_vertex(v, s)`
Move vertex 'v' to block 's'.

- **v** (int) - The vertex to move.
- **s** (int) - The target block.

#### `_entropy(uniform=False, degree_dl_kind='distributed')`
Return the model entropy (negative log-likelihood).

- **uniform** (bool, optional, default: `False`) - If `True`, the uniform planted partition model is used, otherwise a non-uniform version is used.
- **degree_dl_kind** (str, optional, default: `'distributed'`) - Kind of degree distribution to use.

### Request Example (for `move_vertex`)
```json
{
  "v": 0,
  "s": 1
}
```

### Response Example (for `get_B`)
```json
{
  "number_of_blocks": 5
}
```
```

--------------------------------

### Copy Graph Structure

Source: https://graph-tool.skewed.de/static/docs/stable/_sources/quickstart

Demonstrates creating a deep copy of an existing graph. The 'Graph(g)' constructor copies the graph structure and property maps, ensuring modifications to the copy do not affect the original graph.

```python
g2 = Graph(g)                 # g2 is a copy of g

```

--------------------------------

### Compose Graph Views for Complex Filtering

Source: https://graph-tool.skewed.de/static/docs/stable/_sources/quickstart

Demonstrates how to compose multiple graph views to create complex filters. This example isolates the minimum spanning tree of vertices with an out-degree greater than four, then filters edges based on betweenness centrality.

```python
from graph_tool.all import GraphView, min_spanning_tree, triangulation
from numpy.random import random

# Assuming 'g' and 'pos' are defined graph and position objects
# g, pos = triangulation(random((500, 2)) * 4, type="delaunay")
# u = GraphView(g, vfilt=lambda v: v.out_degree() > 4)
# tree = min_spanning_tree(u)
# u = GraphView(u, efilt=tree)
```

--------------------------------

### AxelrodState Initialization and Usage Example (Python)

Source: https://graph-tool.skewed.de/static/docs/stable/_modules/graph_tool/dynamics

Initializes Axelrod's culture dissemination model. The example demonstrates creating a graph, initializing the AxelrodState, iterating the dynamics, and drawing the resulting state.

```python
gt.seed_rng(42)
        np.random.seed(42)

        g = gt.GraphView(gt.collection.data["polblogs"].copy(), directed=False)
        gt.remove_parallel_edges(g)
        g = gt.extract_largest_component(g, prune=True)
        state = gt.AxelrodState(g, f=10, q=30, r=0.005)
        ret = state.iterate_async(niter=10000000)
        gt.graph_draw(g, g.vp.pos,
                      vertex_fill_color=gt.perfect_prop_hash([state.s])[0],
                      vcmap=cm.magma, output="axelrod.svg")
```

--------------------------------

### Get Edge Descriptor by Source and Target Vertices in Graph-tool

Source: https://graph-tool.skewed.de/static/docs/stable/_sources/quickstart

Retrieves an edge descriptor from a graph-tool graph given the source and target vertex descriptors. This is useful for accessing a specific edge when its endpoints are known. It assumes the edge already exists.

```python
g.add_edge(g.vertex(2), g.vertex(3))
e = g.edge(2, 3)
```

--------------------------------

### Filtering Edges Based on Property Map in graph-tool

Source: https://graph-tool.skewed.de/static/docs/stable/quickstart

Shows how to create a graph view that filters out edges based on a condition applied to an edge property map. This example uses the 'betweenness' centrality values to selectively keep edges with values below a certain threshold.

```python
g = collection.ns["ego_social/facebook_combined"]
vb, eb = betweenness(g)
u = GraphView(g, efilt=eb.fa < 1e-6)
```

--------------------------------

### Initialize PPBlockState in Python

Source: https://graph-tool.skewed.de/static/docs/stable/_modules/graph_tool/inference/planted_partition

Initializes a PPBlockState object to obtain the partition of a network. It takes the graph, an optional initial partition, and entropy arguments. It sets up internal structures for efficient state management and calculations.

```python
PPBlockState(g, b=None, entropy_args={})
```

--------------------------------

### Get Vertex Index in graph-tool

Source: https://graph-tool.skewed.de/static/docs/stable/_sources/quickstart

Explains how to retrieve the unique index of a vertex in a graph-tool graph. The index is an integer between 0 and N-1, where N is the total number of vertices. This can be accessed via the graph's vertex_index property map or by converting the vertex descriptor to an int.

```python
from graph_tool.all import *

g = Graph()
v = g.add_vertex()
print(g.vertex_index[v])
print(int(v))
```

--------------------------------

### Internalizing Edge Property Maps

Source: https://graph-tool.skewed.de/static/docs/stable/_sources/quickstart

Demonstrates how to create a new edge property map, assign it a name within the graph's edge properties, and list the graph's properties. This allows the property map to be saved with the graph.

```python
>>> eprop = g.new_edge_property("string")
>>> g.ep["some name"] = eprop
>>> g.list_properties()
some name      (edge)    (type: string)
```

--------------------------------

### Graph Drawing Example using graph-tool

Source: https://graph-tool.skewed.de/static/docs/stable/_modules/graph_tool/search

This example demonstrates how to load a graph from an XML file and draw it using graph-tool. It visualizes vertex names and edge weights, outputting the drawing to an SVG file. This requires the 'search_example.xml' file to be present.

```python
g = gt.load_graph("../search_example.xml")
name = g.vp["name"]
weight = g.ep["weight"]
pos = g.vp["pos"]
gt.graph_draw(g, pos, vertex_text=name, vertex_font_size=12, vertex_shape="double_circle",
              vertex_fill_color="#729fcf", vertex_pen_width=3,
              edge_pen_width=weight, output="search_example.svg")
```

--------------------------------

### Python Example: A* Visitor Class

Source: https://graph-tool.skewed.de/static/docs/stable/_modules/graph_tool/search

This Python code defines a custom visitor class 'VisitorExample' that inherits from 'gt.AStarVisitor'. It tracks discovered vertices and examined edges, and can be used to customize A* search behavior.

```python
class VisitorExample(gt.AStarVisitor):

    def __init__(self, touched_v, touched_e, target):
        self.touched_v = touched_v
        self.touched_e = touched_e
        self.target = target

    def discover_vertex(self, u):
        self.touched_v[u] = True

    def examine_edge(self, e):
        self.touched_e[e] = True
```

--------------------------------

### Retrieving Vertex and Edge Descriptors

Source: https://graph-tool.skewed.de/static/docs/stable/_sources/quickstart

This section explains how to obtain vertex and edge descriptors using their indices or by iterating through graph elements.

```APIDOC
## Get Vertex by Index

### Description
Retrieves a vertex descriptor given its index.

### Method
`vertex(index)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **index** (integer) - The index of the vertex.

### Request Example
```python
# Assuming 'g' is a graph object
v = g.vertex(8)
```

### Response
#### Success Response (200)
- **vertex_descriptor** (descriptor) - The descriptor of the vertex.

#### Response Example
```json
{
  "vertex_descriptor": "<vertex_descriptor_object>"
}
```

## Get Edge by Source and Target Vertices

### Description
Retrieves an edge descriptor given the source and target vertex descriptors.

### Method
`edge(source_vertex, target_vertex)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **source_vertex** (descriptor) - The descriptor of the source vertex.
- **target_vertex** (descriptor) - The descriptor of the target vertex.

### Request Example
```python
# Assuming 'g' is a graph object and v1, v2 are vertex descriptors
e = g.edge(v1, v2)
```

### Response
#### Success Response (200)
- **edge_descriptor** (descriptor) - The descriptor of the edge.

#### Response Example
```json
{
  "edge_descriptor": "<edge_descriptor_object>"
}
```

## Get Edge Index

### Description
Retrieves the unique index of an edge.

### Method
`edge_index[edge_descriptor]`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **edge_descriptor** (descriptor) - The descriptor of the edge.

### Request Example
```python
# Assuming 'g' is a graph object and 'e' is an edge descriptor
index = g.edge_index[e]
```

### Response
#### Success Response (200)
- **index** (integer) - The index of the edge.

#### Response Example
```json
{
  "index": 1
}
```
```

--------------------------------

### NormCutState Initialization and Copying

Source: https://graph-tool.skewed.de/static/docs/stable/_modules/graph_tool/inference/norm_cut

Details on initializing and copying the NormCutState object, including parameters for graph and initial partition.

```APIDOC
## NormCutState Class

### Description
Represents the state for partitioning a network using the normalized cut algorithm. This class is included for comparison and generally, inference-based approaches are preferred.

### Methods

#### `__init__(self, g, b=None)`

Initializes the NormCutState.

*   **Parameters**
    *   `g` (Graph): The graph to be partitioned.
    *   `b` (PropertyMap, optional): Initial partition. Defaults to `None`, creating a partition into a single group.

#### `copy(self, g=None, b=None)`

Creates a copy of the current state.

*   **Parameters**
    *   `g` (Graph, optional): Override the graph property. Defaults to the current graph.
    *   `b` (PropertyMap, optional): Override the partition property. Defaults to the current partition.
*   **Returns**
    *   A new `NormCutState` object.

#### `get_B(self)`

Returns the total number of blocks (groups) in the current partition.

*   **Returns**
    *   int: The number of blocks.

#### `get_Be(self)`

Returns the effective number of blocks, calculated using entropy. The formula is :math:`e^{H}`, where :math:`H=-\sum_r\frac{n_r}{N}\ln \frac{n_r}{N}` and :math:`n_r` is the number of nodes in group :math:`r`.

*   **Returns**
    *   float: The effective number of blocks.

#### `norm_cut(self)`

Calculates and returns the normalized cut value for the current partition.

*   **Notes**
    The normalized cut is defined as :math:`B - \sum_r \frac{e_{rr}}{e_r}`, where :math:`B` is the number of groups, :math:`e_{rr}` is twice the number of edges within group :math:`r`, and :math:`e_r` is the sum of degrees of nodes in group :math:`r`.

*   **Returns**
    *   float: The normalized cut value.
```

--------------------------------

### Remove Edge and Vertex

Source: https://graph-tool.skewed.de/static/docs/stable/quickstart

Demonstrates the methods for removing edges and vertices from a graph: `remove_edge()` and `remove_vertex()`. Proper usage is important for graph integrity.

```python
>>> g.remove_edge(e)                               # e no longer exists
>>> g.remove_vertex(v2)                # the second vertex is also gone
```

--------------------------------

### PPBlockState Initialization

Source: https://graph-tool.skewed.de/static/docs/stable/_modules/graph_tool/inference/planted_partition

Initializes the PPBlockState object. This class is used to obtain the partition of a network according to the Bayesian planted partition model.

```APIDOC
## PPBlockState

### Description
Obtain the partition of a network according to the Bayesian planted partition model.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **g** (Graph) - Graph to be modelled.
- **b** (PropertyMap, optional) - Initial partition. If not supplied, a partition into a single group will be used.
- **entropy_args** (dict, optional) - Override default arguments for the `entropy()` method and related operations.

### Request Example
```json
{
  "g": "<graph_tool.Graph object>",
  "b": null,
  "entropy_args": {}
}
```

### Response
#### Success Response (200)
- **PPBlockState object** - An instance of the PPBlockState class.

#### Response Example
```json
{
  "example": "<PPBlockState object with X blocks, for graph Y, at 0xZ>"
}
```
```

--------------------------------

### Get OpenMP Schedule (Python)

Source: https://graph-tool.skewed.de/static/docs/stable/_sources/parallel

Retrieves the current OpenMP work sharing schedule type. Returns a string indicating the schedule (e.g., 'static', 'dynamic', 'guided').

```python
import graph_tool as gt

schedule = gt.openmp_get_schedule()
print(f"Current schedule: {schedule}")
```

--------------------------------

### Execute A* Search and Visualize Path in Graph-Tool

Source: https://graph-tool.skewed.de/static/docs/stable/_modules/graph_tool/search

This snippet demonstrates performing an A* search on a graph using graph-tool and then visualizing the shortest path found. It includes setting up edge and vertex properties for coloring and width, iterating through the path to assign these properties, and finally drawing the graph with the path highlighted. Dependencies include the graph-tool library and numpy.

```python
dist, pred = gt.astar_search(g, g.vertex(0), weight, visitor, dist_map=dist, cost_map=cost, heuristic=lambda v: h(v, array(target), state), implicit=True)

ecolor = g.new_edge_property("string")
vcolor = g.new_vertex_property("string")ewidth = g.new_edge_property("double")
ewidth.a = 1
for e in g.edges():
   ecolor[e] = "black"
for v in g.vertices():
   vcolor[v] = "white"
v = visitor.visited[tuple(target)]
while v != g.vertex(0):
    vcolor[v] = "black"
    p = g.vertex(pred[v])
    for e in v.out_edges():
        if e.target() == p:
            ecolor[e] = "#a40000"
            ewidth[e] = 3
    v = p
vcolor[v] = "black"
pos = gt.graph_draw(g, output_size=(300, 300), vertex_fill_color=vcolor, edge_color=ecolor,
                    edge_pen_width=ewidth, output="astar-implicit.svg")
```

--------------------------------

### Kirman State Initialization (Python)

Source: https://graph-tool.skewed.de/static/docs/stable/_modules/graph_tool/dynamics

Initializes the Kirman state dynamics. If the state is not provided, a random initial state is generated. It sets up the graph and parameters for the Kirman model.

```python
if s is None:
            s = g.new_vp("int32_t", vals=numpy.random.randint(0, 2, g.num_vertices()))
        DiscreteStateBase.__init__(self, g,
                                   lib_dynamics.make_kirman_state,
                                   dict(d=d, c1=c1, c2=c2), s)
```

--------------------------------

### Display Graph-Tool Build Configuration

Source: https://graph-tool.skewed.de/static/docs/stable/_modules/graph_tool

Prints detailed build configuration information for `graph-tool`, including version, compiler details, compilation flags, installation paths, and OpenMP status. It uses `libcore.mod_info()` and `os.uname()`.

```python
def show_config():
    """Show ``graph_tool`` build configuration."""
    info = libcore.mod_info()
    print("version:", info.version)
    print("gcc version:", info.gcc_version)
    print("compilation flags:", info.cxxflags)
    print("install prefix:", info.install_prefix)
    print("python dir:", info.python_dir)
    print("openmp:", libcore.openmp_enabled())
    print("uname:", " ".join(os.uname()))
```

--------------------------------

### Access Vertex Property by Index (Python)

Source: https://graph-tool.skewed.de/static/docs/stable/quickstart

Demonstrates direct access to a vertex property map using a vertex index to retrieve its stored value.

```python
print(vprop[10])
```

--------------------------------

### BlockState Initialization Parameters

Source: https://graph-tool.skewed.de/static/docs/stable/_modules/graph_tool/inference/blockmodel

Explains the parameters used to initialize the BlockState, a core component for blockmodeling in graph-tool. This includes options for prior distributions, weights, and constraints.

```APIDOC
## BlockState Initialization Parameters

### Description
This section details the parameters for initializing the `BlockState` object, which is used for blockmodeling in the graph-tool library. It covers various configurations for prior distributions, weights, and constraints that influence the blockmodeling process.

### Method
`__init__`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **g** (:class:`~graph_tool.Graph`) - The input graph.
- **b** (:class:`~graph_tool.VertexPropertyMap`, optional) - Initial partition of the vertices into blocks. If not provided, it can be inferred from `B`.
- **B** (`int`, optional) - The desired number of blocks. If `b` is not provided, a random partition into `B` blocks is created.
- **eweight** (:class:`~graph_tool.EdgePropertyMap`, optional) - Edge weights. If not provided, edges have a weight of 1.
- **vweight** (:class:`~graph_tool.VertexPropertyMap`, optional) - Vertex weights. If not provided, vertices have a weight of 1.
- **recs** (`list` of :class:`~graph_tool.PropertyMap`, optional) - A list of property maps for edge covariates.
- **rec_types** (`list` of `str`, optional) - A list of strings specifying the type of prior distribution for each edge covariate.
- **rec_params** (`list` of `dict`, optional) - A list of dictionaries containing parameters for the prior distributions of edge covariates.
- **clabel** (:class:`~graph_tool.VertexPropertyMap`, optional) - Constraint labels on vertices. Vertices with different labels will not be clustered in the same group.
- **pclabel** (:class:`~graph_tool.VertexPropertyMap`, optional) - Partition constraint labels on vertices, used for computing the partition description length.
- **bfield** (:class:`~graph_tool.VertexPropertyMap`, optional) - Local field acting as a prior for the node partition. Should be a vector property map of type ``vector<double>``.
- **Bfield** (:class:`~graph_tool.EdgePropertyMap`, optional) - Similar to `bfield` but for edge partitions.
- **deg_corr** (`bool`, optional, default: `True`) - Whether to use the degree-corrected version of the blockmodel ensemble.
- **dense_bg** (`bool`, optional, default: `False`) - Whether to use a dense matrix for the block graph.
- **entropy_args** (`dict`, optional, default: `{}`) - Arguments to override default settings for the `entropy()` method.
- ****kwargs** - Additional keyword arguments.

### Request Example
```json
{
  "g": "<graph_object>",
  "B": 5,
  "eweight": "<edge_property_map>",
  "vweight": "<vertex_property_map>",
  "rec_types": ["real-normal", "beta"],
  "rec_params": [
    {"m0": 0.5, "k0": 1, "v0": 1.0, "nu0": 3},
    {"alpha": 2, "beta": 2}
  ],
  "deg_corr": true,
  "dense_bg": false
}
```

### Response
#### Success Response (200)
- **BlockState object**: An initialized BlockState object.

#### Response Example
(No direct response body, returns an initialized object)
```

--------------------------------

### Add Multiple Vertices

Source: https://graph-tool.skewed.de/static/docs/stable/quickstart

Explains how to add multiple vertices to a graph at once using the `add_vertex()` method with a count parameter. It returns an iterator for the newly added vertices.

```python
>>> vlist = g.add_vertex(10)
>>> print(len(list(vlist)))
10
```

--------------------------------

### Create and Use Property Maps

Source: https://graph-tool.skewed.de/static/docs/stable/_sources/quickstart

Shows how to create and use property maps for storing attributes on graph elements (vertices and edges). 'new_ep' and 'new_vp' create edge and vertex property maps, respectively, with specified data types.

```python
eweight = g.new_ep("double")    # creates an EdgePropertyMap of type double
vcolor = g.new_vp("string")     # creates a VertexPropertyMap of type string
e   weight[e] = 25.3
vcolor[v1] = "#1c71d8"
vcolor[v2] = "#2ec27e"

```

--------------------------------

### Display graph-tool Build Configuration

Source: https://graph-tool.skewed.de/static/docs/stable/graph_tool

Prints the build configuration details of the installed graph-tool library. This information is useful for diagnosing compatibility issues or understanding available features.

```python
from graph_tool.all import *

show_config()

```

--------------------------------

### Iterate Over All Edges in Graph-tool

Source: https://graph-tool.skewed.de/static/docs/stable/_sources/quickstart

Iterates through all edge descriptors in a graph-tool graph. This method allows for processing each edge in the graph. The order of iteration depends on how edges were added and if any were removed.

```python
for e in g.edges():
    print(e)
```

--------------------------------

### Edge Removal Performance

Source: https://graph-tool.skewed.de/static/docs/stable/quickstart

Explains the time complexity of removing edges (O(ks+kt)) and how to achieve O(1) removal by enabling fast edge removal, which uses additional memory.

```python
set_fast_edge_removal(True)
```
Tokens:
Raw