API Reference

MultiplexSeries 

class muxpack.MultiplexSeries(edges: Table, vertices: Table = None, relationtypes: Table = None)[source]

Bases: object

A multiplexseries is a series of Multiplex graphs with multiple layers, spanning multiple periods.

__init__(edges: Table, vertices: Table = None, relationtypes: Table = None) → None[source]

Initialize a multiplex series with the given edges and vertices tables.

Parameters:

- edges – table with columns src, dst, period, layer, and relationtype.
- vertices – table with column id, period, and optional additional columns. Must have a period column because the edges table has one.
- relationtypes – table with columns relationtype, layer, label, and optional additional columns.

Raises:

- ValueError – if the edges table does not satisfy the required schema.
- ValueError – if the vertices table does not satisfy the required schema.

add_filter(periods: list[int] = None, layers: dict[str, list[int] | None] = None, src: list[int] = None, dst: list[int] = None) → None[source]

Apply a filter to the multiplex series in place. Filtering is lazy: the filter is only executed when saving or converting to another format. Passing None or an empty list for any argument means no filtering is applied for that dimension.

For advanced filtering, modify the edges property directly using ibis expressions.

Parameters:

- periods – list of periods to keep.
- layers – dict of {layer:[relationtype]} to keep.
- src – list of source vertex ids (ego) to keep.
- dst – list of destination vertex ids (non-ego) to keep.

collapse() → Multiplex[source]

Collapse the multiplex series into a single Multiplex by discarding period information. Duplicate edges across periods are removed. This is useful for analyses that do not require temporal information.

Returns:

Multiplex containing all distinct edges across all periods, with period=None.

collapse_to(dir: Path | str) → None[source]

Collapse the multiplex series and save the result to disk. This is a convenience method equivalent to calling collapse() followed by Multiplex.save().

Parameters:: - dir – path to the directory where the collapsed Multiplex will be saved.

edges: Table: The edges of the multiplex. This is a table with columns “src”, “dst”, “period”, “layer” and “relationtype”.

get_multiplex(period: int) → Multiplex[source]

Return the multiplex for a specific period.

Parameters:

- period – the period to retrieve.

Returns:

Multiplex object containing only the edges and vertices for the given period.

layers() → list[str][source]

Get the list of layers present in the multiplex series.

Returns:

Sorted list of layer names.

multiplexes() → list[Tuple[int, Multiplex]][source]

Return all multiplexes in the series, one per period.

Returns:

List of (period, Multiplex) tuples, ordered by period.

periods() → list[int][source]

Get the list of periods present in the multiplex series.

Returns:

Sorted list of period values.

relationtypes: Table | None

save(dir: Path | str, **kw_args) → None[source]

Save the multiplex series to disk. The directory is created if it does not exist; existing files are overwritten. Saving also evaluates the lazy edges and vertices expressions and updates them to point at the saved files, which can improve subsequent performance.

Parameters:: - dir – path to the directory where the MultiplexSeries will be saved. - **kw_args: additional keyword arguments forwarded to

io.save_multiplexseries.

update_relationtypes() → None[source]: Update the relationtypes table by deriving it from the edges table. This is useful when the relationtypes table was not provided at initialization. A label column is constructed as "<layer>_<relationtype>". self.relationtypes is updated in place.

update_vertices() → None[source]: Update the vertices table by deriving it from the edges table. This is useful when the vertices table was not provided at initialization. Both self.vertices and self.vertex_ids are updated in place.

vertex_ids: Table

vertices: Table | None: The vertices of the multiplex. This is a table with a column “id”,”period” and optional additional columns.

Multiplex 

class muxpack.Multiplex(edges: Table, vertices: Table = None, period: int | None = None)[source]

Bases: object

A multiplex is a graph with multiple layers. Each layer represents a different type of relationship between the same set of vertices, during one period. For example, in a social network, one layer could represent friendships, while another layer could represent professional connections. For multiple periods, use MultiplexSeries.

__init__(edges: Table, vertices: Table = None, period: int | None = None) → None[source]

Initialize a multiplex with the given edges and vertices tables.

Parameters:

- edges – table with columns src, dst, layer, and relationtype.
- vertices – table with column id and optional additional columns.
- period – the period this multiplex belongs to, or None if not applicable.

Raises:

- ValueError – if the edges table does not satisfy the required schema.
- ValueError – if the vertices table does not satisfy the required schema.

edges: Table: The edges of the multiplex. This is a table with columns “src”, “dst”, “layer”,”relationtype” and optionally weight.

layers() → list[str][source]

Get the list of layers present in the multiplex.

Returns:

List of layer names.

outdegree(by_layer: bool = False) → Table[source]

Compute the out-degree of each vertex in the multiplex.

Parameters:: - by_layer – if True, compute the out-degree separately for each layer.
Returns:: - by_layer=False – Table with columns “id” and “out_degree”, where “id” is the vertex id and “out_degree” is the total number of outgoing edges from that vertex across all layers. - by_layer=True: Table with columns “id”, “layer”, and “out_degree”, where “id” is the vertex id, “layer” is the layer name, and “out_degree” is the number of outgoing edges from that vertex in that layer.

period: int | None

save(dir: Path | str, **kw_args) → None[source]

Save the multiplex to disk. The directory is created if it does not exist; existing files are overwritten. Saving also evaluates the lazy edges and vertices expressions and updates them to point at the saved files, which can improve subsequent performance.

Parameters:

- dir – path to the directory where the Multiplex will be saved.
- **kw_args – additional keyword arguments forwarded to io.save_multiplex.

to_csr_matrices() → dict[str, scipy.sparse.csr_matrix][source]

Transform the multiplex into a dictionary of sparse matrices, one per layer.

Returns:

Dictionary mapping layer name to a sparse boolean matrix of shape (n_vertices, n_vertices).

to_csr_matrix(use_weight: bool | str | Value = False) → csr_matrix[bool] | csr_matrix[float][source]

Transform the multiplex into a sparse matrix, collapsing all layers into one. To keep layers separate, use to_csr_matrices instead.

Parameters:

- use_weight – optional column in the edges table to use as weights for the adjacency matrix. If False, the adjacency matrix will be unweighted (boolean).
if True, the method will look for a column named “weight” in the edges table. If a string is provided, it will be used as the name of the weight column. – If not provided, the adjacency matrix will be unweighted (boolean).

Returns:

Sparse boolean matrix of shape (n_vertices, n_vertices).

to_networkx() → MultiDiGraph[source]

Convert the multiplex to a NetworkX MultiDiGraph.

Returns:

NetworkX MultiDiGraph built from the CSR matrix representation of the edges.

update_vertices() → None[source]: Update the vertices table by deriving it from the edges table. This is useful when the vertices table was not provided at initialization. self.vertices is updated in place.

vertices: Table: The vertices of the multiplex. This is a table with a column “id” and optional additional columns.

Bipartite 

class muxpack.bipartite.Bipartite(edges: Table, role_src: str = 'src', role_dst: str = 'dst', relationtype: str = 'relationtype')[source]

Bases: object

Lazy Bipartite storage - sort on role_src, role_dst

__init__(edges: Table, role_src: str = 'src', role_dst: str = 'dst', relationtype: str = 'relationtype')[source]

Initialize a bipartite graph with the given edges table and role labels.

Parameters:

- edges – table containing the bipartite edges.
- role_src – column name for the source role.
- role_dst – column name for the destination role.
- relationtype – column name for the relation type.

edges: Table

project_to_dst() → Table[source]

Project the bipartite graph onto the destination role, producing a unipartite edge table. Two destination nodes are connected if they share a common source node.

Returns:

Table with columns src, dst, and relationtype.

project_to_src() → Table[source]

Project the bipartite graph onto the source role, producing a unipartite edge table. Two source nodes are connected if they share a common destination node.

Returns:

Table with columns src, dst, and relationtype.

relationtype: str

role_dst: str

role_src: str

save(dir: Path | str) → None[source]

Save the bipartite graph to disk. Edges are saved as a Parquet file and metadata (role_src, role_dst, relationtype) as a JSON file. The edges property is updated to point at the saved file.

Parameters:: - dir – path to the directory where the BiPartite graph will be saved.

Validation 

muxpack.check_edges(edges: Table, check_period=True) → bool[source]

Check that the edges table has the required columns and types.

Parameters:

- edges – the edges table to check.
- check_period – whether to require a period column.

Returns:

True if the edges table is valid, False otherwise.

muxpack.check_vertices(vertices: Table, check_period=True) → bool[source]

Check that the vertices table has the required columns and types.

Parameters:

- vertices – the vertices table to check.
- check_period – whether to require a period column.

Returns:

True if the vertices table is valid, False otherwise.

muxpack.check.check_column_type(t: Table, expected_types: dict[str, str], optional: bool = False) → bool[source]

Check that the columns in a table have the expected types.

Parameters:

- t – the table to check.
- expected_types – dictionary mapping column names to expected type strings (e.g., "integer", "string").
- optional – accept that the column does not exist.

Returns:

True if all specified columns exist and have the expected types, False otherwise.

Input / Output 

muxpack.read_multiplexseries(dir: Path) → MultiplexSeries[source]

Load a multiplex series from a directory containing Parquet files.

The expected directory structure is:

dir/
    <period>/
        edges/
            <layer>/
                *.parquet
        vertices.parquet

Parameters:

- dir – path to the root directory containing the Parquet files.

Returns:

MultiplexSeries loaded from the directory.

muxpack.save_multiplexseries(edges: Table, vertices: Table, dir: Path | str, existing_data_behavior='delete_matching', **kwargs) → Tuple[Table, Table][source]

Save edges and vertices to disk following the muxpack directory structure. The directory and all sub-directories are created if they do not exist. Edges and vertices are not validated for consistency.

Parameters:

- edges – edge table to save.
- vertices – vertex table to save.
- dir – root path where the network will be saved.
- existing_data_behavior – passed through to pyarrow.dataset.write_dataset.
- **kwargs – additional keyword arguments forwarded to pyarrow.dataset.write_dataset.

Returns:

Tuple of (edges, vertices) table objects pointing to the saved files.

muxpack.io.read_multiplexseries(dir: Path) → MultiplexSeries[source]

Load a multiplex series from a directory containing Parquet files.

The expected directory structure is:

dir/
    <period>/
        edges/
            <layer>/
                *.parquet
        vertices.parquet

Parameters:

- dir – path to the root directory containing the Parquet files.

Returns:

MultiplexSeries loaded from the directory.

muxpack.io.save_multiplex(edges: Table, vertices: Table, dir: Path | str, period: int | None, existing_data_behavior='delete_matching', **kwargs) → Tuple[Table, Table][source]

Save a single-period multiplex to disk following the muxpack directory structure. The directory and all sub-directories are created if they do not exist. Edges and vertices are not validated for consistency.

Parameters:

- edges – edge table to save.
- vertices – vertex table to save. - period: the period for this multiplex; if None, all rows in edges

are written to the same directory.
- dir – root path where the multiplex will be saved.
- existing_data_behavior – passed through to pyarrow.dataset.write_dataset.
- **kwargs – additional keyword arguments forwarded to pyarrow.dataset.write_dataset.

Returns:

Tuple of (edges, vertices) table objects pointing to the saved files.

muxpack.io.save_multiplexseries(edges: Table, vertices: Table, dir: Path | str, existing_data_behavior='delete_matching', **kwargs) → Tuple[Table, Table][source]

Save edges and vertices to disk following the muxpack directory structure. The directory and all sub-directories are created if they do not exist. Edges and vertices are not validated for consistency.

Parameters:

- edges – edge table to save.
- vertices – vertex table to save.
- dir – root path where the network will be saved.
- existing_data_behavior – passed through to pyarrow.dataset.write_dataset.
- **kwargs – additional keyword arguments forwarded to pyarrow.dataset.write_dataset.

Returns:

Tuple of (edges, vertices) table objects pointing to the saved files.

muxpack.io.save_bipartite(edges: Table, role_src: str, role_dst: str, relationtype: str, dir: Path | str) → None[source]

Save a bipartite graph to disk as a Parquet file plus a JSON metadata file.

Parameters:

- edges – edge table to save.
- role_src – column name used for the source role.
- role_dst – column name used for the destination role.
- relationtype – column name used for the relation type.
- dir – path to the directory where the files will be saved.

muxpack.io.read_bipartite(dir: Path | str) → Bipartite[source]

Load a bipartite graph from disk.

Parameters:

- dir – path to the directory containing edges.parquet and metadata.json.

Returns:

BiPartite object with edges and metadata loaded from disk.

Sparse matrices 

muxpack.to_csr_matrix(edges: Table, vertices: Table | None) → scipy.sparse.csr_matrix[source]

Transform an edge list into a sparse matrix (csr_matrix).

Parameters:

- edges – table with src and dst columns. - vertices: table with an id column; edges are filtered to vertices present

in this table.

Returns:

Square CSR sparse matrix of shape (n_vertices, n_vertices).

Note

vertices is currently required and should not be None.

muxpack.to_csr_matrix.to_period_csr_matrix(edges: Table, vertices: Table | None, periods: list[int] = []) → Generator[Tuple[scipy.sparse.csr_matrix, int], None, None][source]

Generate a sparse matrix for each period.

Parameters:

- edges – table with columns src, dst, and period.
- vertices – table with columns id and period, or None to derive vertices from the edges table for each period.
- periods – list of periods to generate matrices for. If empty, all periods present in edges are used.

Returns:

Generator of (csr_matrix, period) tuples, one per period.

NetworkX 

muxpack.networkx.to_MultiDiGraph(edges: Table, vertices: Table) → MultiDiGraph[source]

Convert an edge list and vertex table to a NetworkX MultiDiGraph.

Parameters:

- edges – table with src and dst columns.
- vertices – table with an id column.

Returns:

NetworkX MultiDiGraph built from the CSR matrix representation of the edges.

API Reference

MultiplexSeries

Multiplex

Bipartite

Validation

Input / Output

Sparse matrices

NetworkX

MultiplexSeries 

Multiplex 

Bipartite 

Validation 

Input / Output 

Sparse matrices 

NetworkX 