diff --git a/skimage/graph/_ncut.py b/skimage/graph/_ncut.py index e31b9431..3e961ad4 100644 --- a/skimage/graph/_ncut.py +++ b/skimage/graph/_ncut.py @@ -4,7 +4,23 @@ from scipy import sparse def DW_matrix(graph): + """Returns the diagonal and weight matrix of a graph. + Parameters + ---------- + graph : RAG + A Region Adjacency Graph. + + Returns + ------- + D : csc_matrix + The diagonal matrix of the graph. `D[i,i]` is the sum of weights of all + edges incident on `i`. All other enteries are `0`. + W : csc_matrix + The weight matrix of the graph. `W[i,j]` is the weight of the edge + joining `i` to `j`. + """ + #Cause sparse.eigsh prefers CSC format W = nx.to_scipy_sparse_matrix(graph, format='csc') entries = W.sum(0) D = sparse.dia_matrix((entries, 0), shape=W.shape).tocsc() @@ -12,7 +28,23 @@ def DW_matrix(graph): def ncut_cost(mask, D, W): + """Returns the N-cut cost of a bi-partition of a graph. + Parameters + ---------- + mask : ndarray + The mask for the nodes in the graph. Nodes corrsesponding to a `True` + value are in one set. + D : csc_matrix + The diagonal matrix of the graph. + W : csc_matrix + The weight matrix of the graph. + + Returns + ------- + cost : float + The cost of performing the N-cut. + """ mask = np.array(mask) mask_list = [np.logical_xor(mask[i], mask) for i in range(mask.shape[0])] mask_array = np.array(mask_list) @@ -25,6 +57,18 @@ def ncut_cost(mask, D, W): def normalize(a): + """Normalize values in an array between `0` and `1`. + + Parameters + ---------- + a : ndarray + The array to be normalized. + + Returns + ------- + out : ndarray + The normalized array. + """ mi = a.min() mx = a.max() return (a - mi) / (mx - mi)