From 528f13fed8573a89132d0fe369848aba33d4727e Mon Sep 17 00:00:00 2001 From: Sultan Orazbayev Date: Wed, 19 Apr 2023 15:11:31 +0600 Subject: [PATCH 1/6] Update io.rst As raised in #436 --- docs/api_reference/io.rst | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/docs/api_reference/io.rst b/docs/api_reference/io.rst index 1b42c0648..afc76fb2b 100644 --- a/docs/api_reference/io.rst +++ b/docs/api_reference/io.rst @@ -49,6 +49,16 @@ These methods require `scipy `_ to be installed. .. autofunction:: graphblas.io.mmwrite +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. + +.. autofunction:: graphblas.io.from_awkward + +.. autofunction:: graphblas.io.to_awkward + Visualization ~~~~~~~~~~~~~ From e07eb153edd76ce78fca5f37812405d82e09730f Mon Sep 17 00:00:00 2001 From: SultanOrazbayev Date: Fri, 2 Jun 2023 13:24:31 +0600 Subject: [PATCH 2/6] Update documentation for `awkward-array`-related io functions. --- docs/api_reference/io.rst | 15 +++++++++++---- 1 file changed, 11 insertions(+), 4 deletions(-) diff --git a/docs/api_reference/io.rst b/docs/api_reference/io.rst index afc76fb2b..190100b52 100644 --- a/docs/api_reference/io.rst +++ b/docs/api_reference/io.rst @@ -52,13 +52,20 @@ These methods require `scipy `_ to be installed. 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. - -.. autofunction:: graphblas.io.from_awkward +`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). .. autofunction:: graphblas.io.to_awkward +.. autofunction:: graphblas.io.from_awkward + Visualization ~~~~~~~~~~~~~ From 55ab07d265a3433e17b7b4442bcd5914d718e681 Mon Sep 17 00:00:00 2001 From: SultanOrazbayev Date: Fri, 2 Jun 2023 13:24:55 +0600 Subject: [PATCH 3/6] Update the doc string and change the order of the functions to reflect their intended use case. --- graphblas/io/_awkward.py | 110 +++++++++++++++++++++------------------ 1 file changed, 58 insertions(+), 52 deletions(-) diff --git a/graphblas/io/_awkward.py b/graphblas/io/_awkward.py index 3119bdf3b..6c476817f 100644 --- a/graphblas/io/_awkward.py +++ b/graphblas/io/_awkward.py @@ -7,58 +7,6 @@ _AwkwardDoublyCompressedMatrix = None -def 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 - ---------- - A : awkward.Array - Awkward Array with values and indices - name : str, optional - Name of resulting Matrix or Vector - - Returns - ------- - Vector or Matrix - """ - params = A.layout.parameters - if missing := {"format", "shape"} - params.keys(): - raise ValueError(f"Missing parameters: {missing}") - format = params["format"] - shape = params["shape"] - - if len(shape) == 1: - if format != "vec": - raise ValueError(f"Invalid format for Vector: {format}") - return Vector.from_coo( - A.indices.layout.data, A.values.layout.data, size=shape[0], name=name - ) - nrows, ncols = shape - values = A.values.layout.content.data - indptr = A.values.layout.offsets.data - if format == "csr": - cols = A.indices.layout.content.data - return Matrix.from_csr(indptr, cols, values, ncols=ncols, name=name) - if format == "csc": - rows = A.indices.layout.content.data - return Matrix.from_csc(indptr, rows, values, nrows=nrows, name=name) - if format == "hypercsr": - rows = A.offset_labels.layout.data - cols = A.indices.layout.content.data - return Matrix.from_dcsr(rows, indptr, cols, values, nrows=nrows, ncols=ncols, name=name) - if format == "hypercsc": - cols = A.offset_labels.layout.data - rows = A.indices.layout.content.data - return Matrix.from_dcsc(cols, indptr, rows, values, nrows=nrows, ncols=ncols, name=name) - raise ValueError(f"Invalid format for Matrix: {format}") - - def to_awkward(A, format=None): """Create an Awkward Array from a GraphBLAS Matrix. @@ -179,3 +127,61 @@ def indices(self): # pragma: no branch (???) if classname: ret = ak.with_name(ret, classname) return ret + + +def 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 + ---------- + A : awkward.Array + Awkward Array with values and indices + name : str, 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. + """ + params = A.layout.parameters + if missing := {"format", "shape"} - params.keys(): + raise ValueError(f"Missing parameters: {missing}") + format = params["format"] + shape = params["shape"] + + if len(shape) == 1: + if format != "vec": + raise ValueError(f"Invalid format for Vector: {format}") + return Vector.from_coo( + A.indices.layout.data, A.values.layout.data, size=shape[0], name=name + ) + nrows, ncols = shape + values = A.values.layout.content.data + indptr = A.values.layout.offsets.data + if format == "csr": + cols = A.indices.layout.content.data + return Matrix.from_csr(indptr, cols, values, ncols=ncols, name=name) + if format == "csc": + rows = A.indices.layout.content.data + return Matrix.from_csc(indptr, rows, values, nrows=nrows, name=name) + if format == "hypercsr": + rows = A.offset_labels.layout.data + cols = A.indices.layout.content.data + return Matrix.from_dcsr(rows, indptr, cols, values, nrows=nrows, ncols=ncols, name=name) + if format == "hypercsc": + cols = A.offset_labels.layout.data + rows = A.indices.layout.content.data + return Matrix.from_dcsc(cols, indptr, rows, values, nrows=nrows, ncols=ncols, name=name) + raise ValueError(f"Invalid format for Matrix: {format}") From fbdeffb522d43bf86ce62c57b9c039bcc3aa1470 Mon Sep 17 00:00:00 2001 From: Sultan Orazbayev Date: Wed, 7 Jun 2023 23:35:17 +0600 Subject: [PATCH 4/6] Update io.rst remove trailing blanks --- docs/api_reference/io.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/api_reference/io.rst b/docs/api_reference/io.rst index 190100b52..af2a87520 100644 --- a/docs/api_reference/io.rst +++ b/docs/api_reference/io.rst @@ -57,9 +57,9 @@ 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, +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 +format of the `graphblas` object (this attributed is used by the `graphblas.io.from_awkward` function to reconstruct the `graphblas` object). .. autofunction:: graphblas.io.to_awkward From 82b2cb7cdc6b87ed1a901dc72d36e19d17573176 Mon Sep 17 00:00:00 2001 From: Sultan Orazbayev Date: Thu, 8 Jun 2023 09:22:58 +0600 Subject: [PATCH 5/6] Use double backticks --- docs/api_reference/io.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/api_reference/io.rst b/docs/api_reference/io.rst index af2a87520..4035cf5f1 100644 --- a/docs/api_reference/io.rst +++ b/docs/api_reference/io.rst @@ -55,12 +55,12 @@ 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, +``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). +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). .. autofunction:: graphblas.io.to_awkward From e3fe09a5af582397c1de9098a6a717409d41142a Mon Sep 17 00:00:00 2001 From: Sultan Orazbayev Date: Thu, 8 Jun 2023 09:24:17 +0600 Subject: [PATCH 6/6] Update io.rst --- docs/api_reference/io.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api_reference/io.rst b/docs/api_reference/io.rst index 4035cf5f1..e8f1748fd 100644 --- a/docs/api_reference/io.rst +++ b/docs/api_reference/io.rst @@ -55,7 +55,7 @@ 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, +``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