Input/Output

NetworkX

These methods require networkx to be installed.

graphblas.io.from_networkx(G, nodelist=None, dtype=None, weight='weight', name=None)

Create a square adjacency Matrix from a networkx Graph.

Parameters

Gnx.Graph

Graph to convert

nodelistlist, optional

List of nodes in the nx.Graph. If not provided, all nodes will be used.

dtype

Data type

weightstr, default=”weight”

Weight attribute

namestr, optional

Name of resulting Matrix

Returns

Matrix

graphblas.io.to_networkx(m, edge_attribute='weight')

Create a networkx DiGraph from a square adjacency Matrix.

Parameters

mMatrix

Square adjacency Matrix

edge_attributestr, optional

Name of edge attribute from values of Matrix. If None, values will be skipped. Default is “weight”.

Returns

nx.DiGraph

NumPy

These methods convert to and from dense arrays. For more, see IO in the user guide.

classmethod Matrix.from_dense(values, missing_value=None, *, dtype=None, name=None, **opts)

Create a Matrix from a NumPy array or list of lists.

Parameters

valueslist or np.ndarray

List of values.

missing_valuescalar, optional

A scalar value to consider “missing”; elements of this value will be dropped. If None, then the resulting Matrix will be dense.

dtypeDataType, optional

Data type of the Matrix. If not provided, the values will be inspected to choose an appropriate dtype.

namestr, optional

Name to give the Matrix.

Returns

Matrix

See also

from_coo

from_edgelist

from_scalar

to_dense

Matrix.to_dense(fill_value=None, dtype=None, **opts)

Convert Matrix to NumPy array of the same shape with missing values filled.

Warning

This can create very large arrays that require a lot of memory; please use caution.

Parameters

fill_valuescalar, optional

Value used to fill missing values. This is required if there are missing values.

dtypeDataType, optional

Requested dtype for the output values array.

Returns

np.ndarray

See also

to_coo

to_dicts

to_edgelist

from_dense

classmethod Vector.from_dense(values, missing_value=None, *, dtype=None, name=None, **opts)

Create a Vector from a NumPy array or list.

Parameters

valueslist or np.ndarray

List of values.

missing_valuescalar, optional

A scalar value to consider “missing”; elements of this value will be dropped. If None, then the resulting Vector will be dense.

dtypeDataType, optional

Data type of the Vector. If not provided, the values will be inspected to choose an appropriate dtype.

namestr, optional

Name to give the Vector.

Returns

Vector

See also

from_coo

from_dict

from_pairs

from_scalar

to_dense

Vector.to_dense(fill_value=None, dtype=None, **opts)

Convert Vector to NumPy array of the same shape with missing values filled.

Warning

This can create very large arrays that require a lot of memory; please use caution.

Parameters

fill_valuescalar, optional

Value used to fill missing values. This is required if there are missing values.

dtypeDataType, optional

Requested dtype for the output values array.

Returns

np.ndarray

See also

to_coo

to_dict

from_dense

Scipy Sparse

These methods require scipy to be installed.

graphblas.io.from_scipy_sparse(A, *, dup_op=None, name=None)

Create a Matrix from a scipy.sparse array or matrix.

Input data in “csr” or “csc” format will be efficient when importing with SuiteSparse:GraphBLAS.

Parameters

Ascipy.sparse

Scipy sparse array or matrix

dup_opBinaryOp, optional

Aggregation function for formats that allow duplicate entries (e.g. coo)

namestr, optional

Name of resulting Matrix

Returns

Matrix

graphblas.io.to_scipy_sparse(A, format='csr')

Create a scipy.sparse array from a GraphBLAS Matrix or Vector.

Parameters

AMatrix or Vector

GraphBLAS object to be converted

formatstr

{‘bsr’, ‘csr’, ‘csc’, ‘coo’, ‘lil’, ‘dia’, ‘dok’}

Returns

scipy.sparse array

PyData Sparse

These methods require sparse to be installed.

graphblas.io.from_pydata_sparse(s, *, dup_op=None, name=None)

Create a Vector or a Matrix from a pydata.sparse array or matrix.

Input data in “gcxs” format will be efficient when importing with SuiteSparse:GraphBLAS.

Parameters

ssparse

PyData sparse array or matrix (see https://sparse.pydata.org)

dup_opBinaryOp, optional

Aggregation function for formats that allow duplicate entries (e.g. coo)

namestr, optional

Name of resulting Matrix

Returns

Vector

Matrix

graphblas.io.to_pydata_sparse(A, format='coo')

Create a pydata.sparse array from a GraphBLAS Matrix or Vector.

Parameters

AMatrix or Vector

GraphBLAS object to be converted

formatstr

{‘coo’, ‘dok’, ‘gcxs’}

Returns

sparse array (see https://sparse.pydata.org)

Matrix Market

Matrix Market is a plain-text format for storing graphs.

These methods require scipy to be installed.

graphblas.io.mmread(source, engine='auto', *, dup_op=None, name=None, **kwargs)

Create a GraphBLAS Matrix from the contents of a Matrix Market file.

This uses scipy.io.mmread or fast_matrix_market.mmread.

By default, fast_matrix_market will be used if available, because it is faster. Additional keyword arguments in **kwargs will be passed to the engine’s mmread. For example, parallelism=8 will set the number of threads to use to 8 when using fast_matrix_market.

Parameters

sourcestr or file

Filename (.mtx or .mtz.gz) or file-like object

engine{“auto”, “scipy”, “fmm”, “fast_matrix_market”}, default “auto”

How to read the matrix market file. “scipy” uses scipy.io.mmread, “fmm” and “fast_matrix_market” uses fast_matrix_market.mmread, and “auto” will use “fast_matrix_market” if available.

dup_opBinaryOp, optional

Aggregation function for duplicate coordinates (if found)

namestr, optional

Name of resulting Matrix

Returns

Matrix

graphblas.io.mmwrite(target, matrix, engine='auto', *, comment='', field=None, precision=None, symmetry=None, **kwargs)

Write a Matrix Market file from the contents of a GraphBLAS Matrix.

This uses scipy.io.mmwrite.

Parameters

targetstr or file target

Filename (.mtx) or file-like object opened for writing

matrixMatrix

Matrix to be written

engine{“auto”, “scipy”, “fmm”, “fast_matrix_market”}, default “auto”

How to read the matrix market file. “scipy” uses scipy.io.mmwrite, “fmm” and “fast_matrix_market” uses fast_matrix_market.mmwrite, and “auto” will use “fast_matrix_market” if available.

commentstr, optional

Comments to be prepended to the Matrix Market file

fieldstr

{“real”, “complex”, “pattern”, “integer”}

precisionint, optional

Number of digits to write for real or complex values

symmetrystr, optional

{“general”, “symmetric”, “skew-symmetric”, “hermetian”}

Awkward Array

Awkward Array is a library for nested, variable-sized data, including arbitrary-length lists, records, mixed types, and missing data, using NumPy-like idioms. Note that the intended use of the awkward-array-related io functions is to convert graphblas objects to awkward, perform necessary computations/transformations and, if required, convert the awkward array back to graphblas format. To facilitate this conversion process, graphblas.io.to_awkward adds top-level attribute format, describing the format of the graphblas object (this attributed is used by the graphblas.io.from_awkward function to reconstruct the graphblas object).

graphblas.io.to_awkward(A, format=None)

Create an Awkward Array from a GraphBLAS Matrix.

Parameters

AMatrix or Vector

GraphBLAS object to be converted

formatstr {‘csr’, ‘csc’, ‘hypercsr’, ‘hypercsc’, ‘vec}

Default format is csr for Matrix; vec for Vector

The Awkward Array will have top-level attributes based on format:

- vec/csr/csc: values, indices

- hypercsr/hypercsc: values, indices, offset_labels

Top-level parameters will also be set: format, shape

Returns

awkward.Array

graphblas.io.from_awkward(A, *, name=None)

Create a Matrix or Vector from an Awkward Array.

The Awkward Array must have top-level parameters: format, shape

The Awkward Array must have top-level attributes based on format: - vec/csr/csc: values, indices - hypercsr/hypercsc: values, indices, offset_labels

Parameters

Aawkward.Array

Awkward Array with values and indices

namestr, optional

Name of resulting Matrix or Vector

Returns

Vector or Matrix

Note: the intended purpose of this function is to facilitate

conversion of an awkward-array that was created via to_awkward

function. If attempting to convert an arbitrary awkward-array,

make sure that the top-level attributes and parameters contain

the expected values.

Visualization

graphblas.viz.draw(m)

Draw a square adjacency Matrix as a graph.

Requires networkx and matplotlib to be installed.

Example output: