Add pipeline module and ase function

Makefile

@@ -13,6 +13,9 @@ lint:
 test:
 	pytest tests
 
+fast-test:
+	pytest tests --ignore=tests/test_latentdistributiontest.py --ignore=tests/test_latentpositiontest.py
+
 type-check:
 	mypy ./graspologic
 

docs/reference/reference/embed.rst

@@ -10,7 +10,7 @@ Decomposition
 
 .. autofunction:: select_dimension
 
-.. autofunction:: selectSVD
+.. autofunction:: select_svd
 
 Single graph embedding
 ----------------------

docs/reference/reference/index.rst

@@ -16,6 +16,8 @@ Reference
    models
    nominate
    partition
+   preconditions
+   pipeline
    plotting
    preprocessing
    simulations

docs/reference/reference/pipeline.rst

@@ -0,0 +1,14 @@
+Pipeline
+========
+.. automodule:: graspologic.pipeline
+
+GraphBuilder
+------------
+.. autoclass:: GraphBuilder
+
+Embed
+-----
+.. automodule:: graspologic.pipeline.embed
+.. autoclass:: graspologic.pipeline.embed.embeddings.Embeddings
+.. autofunction:: graspologic.pipeline.embed.adjacency_spectral_embedding.adjacency_spectral_embedding
+

docs/reference/reference/preconditions.rst

@@ -0,0 +1,7 @@
+Preconditions
+=============
+
+.. autofunction:: graspologic.preconditions.check_argument_types
+.. autofunction:: graspologic.preconditions.check_optional_argument_types
+.. autofunction:: graspologic.preconditions.check_argument
+.. autofunction:: graspologic.preconditions.is_real_weighted

graspologic/__init__.py

@@ -10,6 +10,7 @@
 import graspologic.models
 import graspologic.nominate
 import graspologic.partition
+import graspologic.pipeline
 import graspologic.preprocessing
 import graspologic.plot
 import graspologic.simulations

graspologic/embed/__init__.py

@@ -7,7 +7,7 @@
 from .mds import ClassicalMDS
 from .n2v import node2vec_embed
 from .omni import OmnibusEmbed
-from .svd import select_dimension, selectSVD
+from .svd import select_dimension, select_svd
 from .base import BaseSpectralEmbed
 from .mug2vec import mug2vec
 from .case import CovariateAssistedEmbed
@@ -21,7 +21,7 @@
     "MultipleASE",
     "node2vec_embed",
     "select_dimension",
-    "selectSVD",
+    "select_svd",
     "BaseSpectralEmbed",
     "CovariateAssistedEmbed",
 ]

graspologic/embed/ase.py

@@ -1,6 +1,8 @@
 # Copyright (c) Microsoft Corporation and contributors.
 # Licensed under the MIT License.
 
+from typing import Optional
+
 from .base import BaseSpectralEmbed
 from ..utils import augment_diagonal
 
@@ -12,7 +14,7 @@ class AdjacencySpectralEmbed(BaseSpectralEmbed):
     The adjacency spectral embedding (ASE) is a k-dimensional Euclidean representation
     of the graph based on its adjacency matrix. It relies on an SVD to reduce
     the dimensionality to the specified k, or if k is unspecified, can find a number of
-    dimensions automatically (see :class:`~graspologic.embed.selectSVD`).
+    dimensions automatically (see :class:`~graspologic.embed.select_svd`).
 
     Read more in the `Adjacency Spectral Embedding Tutorial
     <https://microsoft.github.io/graspologic/tutorials/embedding/AdjacencySpectralEmbed.html>`_
@@ -62,6 +64,10 @@ class AdjacencySpectralEmbed(BaseSpectralEmbed):
         If graph is directed, whether to concatenate left and right (out and in) latent
         positions along axis 1.
 
+    svd_seed : int or None (default ``None``)
+        Only applicable for ``algorithm="randomized"``; allows you to seed the
+        randomized svd solver for deterministic, albeit pseudo-randomized behavior.
+
 
 
     Attributes
@@ -79,7 +85,7 @@ class AdjacencySpectralEmbed(BaseSpectralEmbed):
 
     See Also
     --------
-    graspologic.embed.selectSVD
+    graspologic.embed.select_svd
     graspologic.embed.select_dimension
 
     Notes
@@ -114,6 +120,7 @@ def __init__(
         check_lcc=True,
         diag_aug=True,
         concat=False,
+        svd_seed: Optional[int] = None,
     ):
         super().__init__(
             n_components=n_components,
@@ -122,6 +129,7 @@ def __init__(
             n_iter=n_iter,
             check_lcc=check_lcc,
             concat=concat,
+            svd_seed=svd_seed,
         )
 
         if not isinstance(diag_aug, bool):

graspologic/embed/base.py

@@ -2,22 +2,21 @@
 # Licensed under the MIT License.
 
 import warnings
-
 from abc import abstractmethod
+from typing import Optional
 
+import networkx as nx
 import numpy as np
 from sklearn.base import BaseEstimator
 from sklearn.utils.validation import check_is_fitted
 
+from .svd import select_svd
 from ..utils import (
     augment_diagonal,
     import_graph,
     is_almost_symmetric,
     is_fully_connected,
 )
-from .svd import selectSVD
-
-import networkx as nx
 
 
 class BaseSpectralEmbed(BaseEstimator):
@@ -60,6 +59,10 @@ class BaseSpectralEmbed(BaseEstimator):
         If graph(s) are directed, whether to concatenate each graph's left and right
         (out and in) latent positions along axis 1.
 
+    svd_seed : int or None (default ``None``)
+        Only applicable for ``algorithm="randomized"``; allows you to seed the
+        randomized svd solver for deterministic, albeit pseudo-randomized behavior.
+
     Attributes
     ----------
     n_components_ : int
@@ -69,7 +72,7 @@ class BaseSpectralEmbed(BaseEstimator):
 
     See Also
     --------
-    graspologic.embed.selectSVD, graspologic.embed.select_dimension
+    graspologic.embed.select_svd, graspologic.embed.select_dimension
     """
 
     def __init__(
@@ -80,6 +83,7 @@ def __init__(
         n_iter=5,
         check_lcc=True,
         concat=False,
+        svd_seed: Optional[int] = None,
     ):
         self.n_components = n_components
         self.n_elbows = n_elbows
@@ -90,6 +94,7 @@ def __init__(
             msg = "Parameter `concat` is expected to be type bool"
             raise TypeError(msg)
         self.concat = concat
+        self.svd_seed = svd_seed
 
     def _reduce_dim(self, A, directed=None):
         """
@@ -101,12 +106,13 @@ def _reduce_dim(self, A, directed=None):
         A: array-like, shape (n_vertices, n_vertices)
             Adjacency matrix to embed.
         """
-        U, D, V = selectSVD(
+        U, D, V = select_svd(
             A,
             n_components=self.n_components,
             n_elbows=self.n_elbows,
             algorithm=self.algorithm,
             n_iter=self.n_iter,
+            svd_seed=self.svd_seed,
         )
 
         self.n_components_ = D.size
@@ -348,6 +354,7 @@ def __init__(
         check_lcc=True,
         diag_aug=True,
         concat=False,
+        svd_seed: Optional[int] = None,
     ):
         super().__init__(
             n_components=n_components,
@@ -356,6 +363,7 @@ def __init__(
             n_iter=n_iter,
             check_lcc=check_lcc,
             concat=concat,
+            svd_seed=svd_seed,
         )
 
         if not isinstance(diag_aug, bool):

graspologic/embed/lse.py

@@ -83,9 +83,13 @@ class LaplacianSpectralEmbed(BaseSpectralEmbed):
     singular_values_ : array, shape (n_components)
         Singular values associated with the latent position matrices.
 
+    svd_seed : int or None (default ``None``)
+        Only applicable for ``algorithm="randomized"``; allows you to seed the
+        randomized svd solver for deterministic, albeit pseudo-randomized behavior.
+
     See Also
     --------
-    graspologic.embed.selectSVD
+    graspologic.embed.select_svd
     graspologic.embed.select_dimension
     graspologic.utils.to_laplacian
 
@@ -123,6 +127,7 @@ def __init__(
         check_lcc: bool = True,
         regularizer: Optional[float] = None,
         concat: bool = False,
+        svd_seed: Optional[int] = None,
     ):
         super().__init__(
             n_components=n_components,
@@ -131,6 +136,7 @@ def __init__(
             n_iter=n_iter,
             check_lcc=check_lcc,
             concat=concat,
+            svd_seed=svd_seed,
         )
         self.form = form
         self.regularizer = regularizer

graspologic/embed/mase.py

@@ -1,10 +1,12 @@
 # Copyright (c) Microsoft Corporation and contributors.
 # Licensed under the MIT License.
 
+from typing import Optional
+
 import numpy as np
 
 from .base import BaseEmbedMulti
-from .svd import select_dimension, selectSVD
+from .svd import select_dimension, select_svd
 from ..utils import is_almost_symmetric
 
 
@@ -70,6 +72,10 @@ class MultipleASE(BaseEmbedMulti):
         If graph(s) are directed, whether to concatenate each graph's left and right (out and in) latent positions
         along axis 1.
 
+    svd_seed : int or None (default ``None``)
+        Only applicable for ``algorithm="randomized"``; allows you to seed the
+        randomized svd solver for deterministic, albeit pseudo-randomized behavior.
+
 
     Attributes
     ----------
@@ -112,6 +118,7 @@ def __init__(
         scaled=True,
         diag_aug=True,
         concat=False,
+        svd_seed: Optional[int] = None,
     ):
         if not isinstance(scaled, bool):
             msg = "scaled must be a boolean, not {}".format(scaled)
@@ -124,6 +131,7 @@ def __init__(
             n_iter=n_iter,
             diag_aug=diag_aug,
             concat=concat,
+            svd_seed=svd_seed,
         )
         self.scaled = scaled
 
@@ -136,11 +144,12 @@ def _reduce_dim(self, graphs):
 
         # embed individual graphs
         embeddings = [
-            selectSVD(
+            select_svd(
                 graph,
                 n_components=n_components,
                 algorithm=self.algorithm,
                 n_iter=self.n_iter,
+                svd_seed=self.svd_seed,
             )
             for graph in graphs
         ]
@@ -178,20 +187,22 @@ def _reduce_dim(self, graphs):
 
         # Second SVD for vertices
         # The notation is slightly different than the paper
-        Uhat, sing_vals_left, _ = selectSVD(
+        Uhat, sing_vals_left, _ = select_svd(
             Us,
             n_components=self.n_components,
             n_elbows=self.n_elbows,
             algorithm=self.algorithm,
             n_iter=self.n_iter,
+            svd_seed=self.svd_seed,
         )
 
-        Vhat, sing_vals_right, _ = selectSVD(
+        Vhat, sing_vals_right, _ = select_svd(
             Vs,
             n_components=self.n_components,
             n_elbows=self.n_elbows,
             algorithm=self.algorithm,
             n_iter=self.n_iter,
+            svd_seed=self.svd_seed,
         )
         return Uhat, Vhat, sing_vals_left, sing_vals_right
 

graspologic/embed/mds.py

@@ -1,11 +1,13 @@
 # Copyright (c) Microsoft Corporation and contributors.
 # Licensed under the MIT License.
 
+from typing import Optional
+
 import numpy as np
 from sklearn.base import BaseEstimator
 from sklearn.utils import check_array
 
-from .svd import selectSVD
+from .svd import select_svd
 from ..utils import is_symmetric
 
 
@@ -72,6 +74,10 @@ class ClassicalMDS(BaseEstimator):
     dissimilarity_matrix_ : array, shape (n_features, n_features)
         Dissimilarity matrix
 
+    svd_seed : int or None (default ``None``)
+        Only applicable for ``n_components!=1``; allows you to seed the
+        randomized svd solver for deterministic, albeit pseudo-randomized behavior.
+
     See Also
     --------
     graspologic.embed.select_dimension
@@ -82,7 +88,13 @@ class ClassicalMDS(BaseEstimator):
     Aalborg University, Denmark 46.5 (2003).
     """
 
-    def __init__(self, n_components=None, n_elbows=2, dissimilarity="euclidean"):
+    def __init__(
+        self,
+        n_components=None,
+        n_elbows=2,
+        dissimilarity="euclidean",
+        svd_seed: Optional[int] = None,
+    ):
         # Check inputs
         if n_components is not None:
             if not isinstance(n_components, int):
@@ -101,6 +113,7 @@ def __init__(self, n_components=None, n_elbows=2, dissimilarity="euclidean"):
         self.dissimilarity = dissimilarity
 
         self.n_elbows = n_elbows
+        self.svd_seed = svd_seed
 
     def _compute_euclidean_distances(self, X):
         """
@@ -187,8 +200,12 @@ def fit(self, X, y=None):
             algorithm = "full"
         else:
             algorithm = "randomized"
-        U, D, V = selectSVD(
-            B, n_elbows=self.n_elbows, algorithm=algorithm, n_components=n_components
+        U, D, V = select_svd(
+            B,
+            n_elbows=self.n_elbows,
+            algorithm=algorithm,
+            n_components=n_components,
+            svd_seed=self.svd_seed,
         )
 
         self.n_components_ = len(D)