@graphty/layout 1.2.0 → 1.2.1

package/src/layouts/hierarchical/bipartite.ts

@@ -0,0 +1,94 @@
+/**
+ * Bipartite layout algorithm
+ */
+
+import { Graph, Node, PositionMap } from '../../types';
+import { _processParams } from '../../utils/params';
+import { getNodesFromGraph } from '../../utils/graph';
+import { rescaleLayout } from '../../utils/rescale';
+
+/**
+ * Position nodes in two straight lines (bipartite layout).
+ * 
+ * @param G - Graph or list of nodes
+ * @param nodes - Nodes in one node set of the graph
+ * @param align - The alignment of nodes: 'vertical' or 'horizontal'
+ * @param scale - Scale factor for positions
+ * @param center - Coordinate pair around which to center the layout
+ * @param aspectRatio - The ratio of the width to the height of the layout
+ * @returns Positions dictionary keyed by node
+ */
+export function bipartiteLayout(
+  G: Graph,
+  nodes: Node[] | null = null,
+  align: 'vertical' | 'horizontal' = 'vertical',
+  scale: number = 1,
+  center: number[] | null = null,
+  aspectRatio: number = 4 / 3
+): PositionMap {
+  if (align !== 'vertical' && align !== 'horizontal') {
+    throw new Error("align must be either vertical or horizontal");
+  }
+
+  const processed = _processParams(G, center || [0, 0], 2);
+  const graph = processed.G;
+  center = processed.center;
+
+  const allNodes = getNodesFromGraph(graph);
+
+  if (allNodes.length === 0) {
+    return {};
+  }
+
+  // If nodes not provided, try to determine bipartite sets
+  if (!nodes) {
+    // A simple heuristic for bipartite detection: use nodes with even/odd indices
+    // This is a simplification, in Python NetworkX has bipartite.sets()
+    nodes = allNodes.filter((_: Node, i: number): boolean => i % 2 === 0);
+  }
+
+  const left = new Set(nodes);
+  const right: Set<Node> = new Set(allNodes.filter((n: Node) => !left.has(n)));
+
+  const height = 1;
+  const width = aspectRatio * height;
+  const offset = [width / 2, height / 2];
+
+  const pos: PositionMap = {};
+
+  // Position nodes in the left set
+  const leftNodes = [...left];
+  leftNodes.forEach((node, i) => {
+    const x = 0;
+    const y = i * height / (leftNodes.length || 1);
+    pos[node] = [x, y];
+  });
+
+  // Position nodes in the right set
+  const rightNodes = [...right];
+  rightNodes.forEach((node, i) => {
+    const x = width;
+    const y = i * height / (rightNodes.length || 1);
+    pos[node] = [x, y];
+  });
+
+  // Center positions around the origin and apply offset
+  for (const node in pos) {
+    pos[node][0] -= offset[0];
+    pos[node][1] -= offset[1];
+  }
+
+  // Rescale positions
+  const scaledPos = rescaleLayout(pos, scale, center) as PositionMap;
+
+  // Handle horizontal alignment
+  if (align === 'horizontal') {
+    for (const node in scaledPos) {
+      const temp = scaledPos[node][0];
+      scaledPos[node][0] = scaledPos[node][1];
+      scaledPos[node][1] = temp;
+    }
+  }
+
+  return scaledPos;
+}

package/src/layouts/hierarchical/index.ts

@@ -0,0 +1,7 @@
+/**
+ * Hierarchical layout algorithms
+ */
+
+export { bipartiteLayout } from './bipartite';
+export { multipartiteLayout } from './multipartite';
+export { bfsLayout } from './bfs';

package/src/layouts/hierarchical/multipartite.ts

@@ -0,0 +1,88 @@
+import type { Graph, Node, PositionMap } from '../../types';
+import { getNodesFromGraph, getNeighbors } from '../../utils/graph';
+import { _processParams } from '../../utils/params';
+import { rescaleLayout } from '../../utils/rescale';
+
+/**
+ * Position nodes in layers of straight lines (multipartite layout).
+ * 
+ * @param G - Graph or list of nodes
+ * @param subsetKey - Object mapping layers to node sets, or node attribute name
+ * @param align - The alignment of nodes: 'vertical' or 'horizontal'
+ * @param scale - Scale factor for positions
+ * @param center - Coordinate pair around which to center the layout
+ * @returns Positions dictionary keyed by node
+ */
+export function multipartiteLayout(
+  G: Graph,
+  subsetKey: Record<number | string, Node | Node[]> | string = 'subset',
+  align: 'vertical' | 'horizontal' = 'vertical',
+  scale: number = 1,
+  center: number[] | null = null
+): PositionMap {
+  if (align !== 'vertical' && align !== 'horizontal') {
+    throw new Error("align must be either vertical or horizontal");
+  }
+
+  const processed = _processParams(G, center || [0, 0], 2);
+  const graph = processed.G;
+  center = processed.center;
+
+  const allNodes = getNodesFromGraph(graph);
+
+  if (allNodes.length === 0) {
+    return {};
+  }
+
+  // Convert subsetKey to a layer mapping if it's a string
+  let layers: Record<number | string, Node[]> = {};
+  if (typeof subsetKey === 'string') {
+    // In JS we don't have access to node attributes directly
+    // This is a simplification - in a real implementation we would need
+    // to access node attributes from the graph
+    console.warn("Using string subsetKey requires node attributes, using default partitioning");
+    // Create a simple partitioning as fallback
+    layers = { 0: allNodes };
+  } else {
+    // subsetKey is already a mapping of layers to nodes
+    // Convert single nodes to arrays
+    for (const [key, value] of Object.entries(subsetKey)) {
+      if (Array.isArray(value)) {
+        layers[key] = value;
+      } else {
+        layers[key] = [value];
+      }
+    }
+  }
+
+  const layerCount = Object.keys(layers).length;
+  let pos: PositionMap = {};
+
+  // Process each layer
+  Object.entries(layers).forEach(([layer, nodes], layerIdx) => {
+    const layerNodes = Array.isArray(nodes) ? nodes : [nodes];
+    const layerSize = layerNodes.length;
+
+    layerNodes.forEach((node, nodeIdx) => {
+      // Place nodes in a grid: layerIdx determines x-coordinate (column)
+      // nodeIdx determines y-coordinate (row position within column)
+      const x = layerIdx - (layerCount - 1) / 2;
+      const y = nodeIdx - (layerSize - 1) / 2;
+      pos[node] = [x, y];
+    });
+  });
+
+  // Rescale positions
+  pos = rescaleLayout(pos, scale, center) as PositionMap;
+
+  // Handle horizontal alignment
+  if (align === 'horizontal') {
+    for (const node in pos) {
+      const temp = pos[node][0];
+      pos[node][0] = pos[node][1];
+      pos[node][1] = temp;
+    }
+  }
+
+  return pos;
+}

package/src/layouts/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Re-export all layout algorithms
+ */
+
+export * from './basic';
+export * from './geometric';
+export * from './force-directed';
+export * from './hierarchical';
+export * from './specialized';

package/src/layouts/specialized/index.ts

@@ -0,0 +1,6 @@
+/**
+ * Specialized layout algorithms
+ */
+
+export { spectralLayout } from './spectral';
+export { planarLayout } from './planar';

package/src/layouts/specialized/planar.ts

@@ -0,0 +1,65 @@
+/**
+ * Planar layout algorithm
+ */
+
+import { Graph, Node, Edge, PositionMap } from '../../types';
+import { _processParams } from '../../utils/params';
+import { getNodesFromGraph, getEdgesFromGraph } from '../../utils/graph';
+import { rescaleLayout } from '../../utils/rescale';
+import { checkPlanarity, combinatorialEmbeddingToPos } from '../../algorithms/planarity';
+
+/**
+ * Position nodes without edge intersections (planar layout).
+ * 
+ * @param G - Graph
+ * @param scale - Scale factor for positions
+ * @param center - Coordinate pair around which to center the layout
+ * @param dim - Dimension of layout (must be 2)
+ * @returns Positions dictionary keyed by node
+ */
+export function planarLayout(
+  G: Graph,
+  scale: number = 1,
+  center: number[] | null = null,
+  dim: number = 2
+): PositionMap {
+  if (dim !== 2) {
+    throw new Error("can only handle 2 dimensions");
+  }
+
+  const processed = _processParams(G, center || [0, 0], dim);
+  
+  // Planar layout requires a proper Graph, not just a list of nodes
+  if (Array.isArray(processed.G)) {
+    throw new Error('Planar layout requires a Graph with edges, not just a list of nodes');
+  }
+  
+  const graph = processed.G;
+  center = processed.center;
+
+  const nodes = getNodesFromGraph(graph);
+  const edges = getEdgesFromGraph(graph);
+
+  if (nodes.length === 0) {
+    return {};
+  }
+
+  // Check if graph is planar and get embedding
+  const { isPlanar, embedding } = checkPlanarity(graph, nodes, edges);
+
+  if (!isPlanar) {
+    throw new Error("G is not planar.");
+  }
+
+  if (!embedding) {
+    throw new Error("Failed to generate planar embedding.");
+  }
+
+  // Convert embedding to positions
+  let pos = combinatorialEmbeddingToPos(embedding, nodes);
+
+  // Rescale the positions
+  pos = rescaleLayout(pos, scale, center) as PositionMap;
+
+  return pos;
+}

package/src/layouts/specialized/spectral.ts

@@ -0,0 +1,128 @@
+/**
+ * Spectral layout algorithm using eigenvectors of the graph Laplacian
+ */
+
+import { Graph, Node, Edge, PositionMap } from '../../types';
+import { _processParams } from '../../utils/params';
+import { getNodesFromGraph, getEdgesFromGraph } from '../../utils/graph';
+import { rescaleLayout } from '../../utils/rescale';
+
+/**
+ * Position nodes in a spectral layout using eigenvectors of the graph Laplacian.
+ * 
+ * @param G - Graph
+ * @param scale - Scale factor for positions
+ * @param center - Coordinate pair around which to center the layout
+ * @param dim - Dimension of layout
+ * @returns Positions dictionary keyed by node
+ */
+export function spectralLayout(
+  G: Graph,
+  scale: number = 1,
+  center: number[] | null = null,
+  dim: number = 2
+): PositionMap {
+  const processed = _processParams(G, center, dim);
+  const graph = processed.G;
+  center = processed.center;
+
+  const nodes = getNodesFromGraph(graph);
+
+  if (nodes.length <= 2) {
+    if (nodes.length === 0) {
+      return {};
+    } else if (nodes.length === 1) {
+      return { [nodes[0]]: center };
+    } else {
+      return {
+        [nodes[0]]: center.map(v => v - scale),
+        [nodes[1]]: center.map(v => v + scale)
+      };
+    }
+  }
+
+  // Create adjacency matrix
+  const N = nodes.length;
+  const nodeIndices: Record<Node, number> = {};
+  nodes.forEach((node: Node, i: number) => { nodeIndices[node] = i; });
+
+  const A = Array(N).fill(0).map(() => Array(N).fill(0));
+  const edges = getEdgesFromGraph(graph);
+
+  for (const [source, target] of edges) {
+    const i = nodeIndices[source];
+    const j = nodeIndices[target];
+    A[i][j] = 1;
+    A[j][i] = 1; // Make symmetric for undirected graphs
+  }
+
+  // Create Laplacian matrix: L = D - A where D is degree matrix
+  const L = Array(N).fill(0).map(() => Array(N).fill(0));
+  for (let i = 0; i < N; i++) {
+    // Compute degree (sum of row)
+    L[i][i] = A[i].reduce((sum, val) => sum + val, 0);
+    for (let j = 0; j < N; j++) {
+      L[i][j] -= A[i][j];
+    }
+  }
+
+  // Compute eigenvectors using power iteration method
+  // We need the smallest non-zero eigenvectors of L
+  const eigenvectors: number[][] = [];
+
+  // For each dimension, find an eigenvector
+  for (let d = 0; d < dim; d++) {
+    let vector = Array(N).fill(0).map(() => Math.random() - 0.5);
+
+    // Orthogonalize against previous eigenvectors
+    for (const ev of eigenvectors) {
+      const dot = vector.reduce((acc, val, idx) => acc + val * ev[idx], 0);
+      vector = vector.map((val, idx) => val - dot * ev[idx]);
+    }
+
+    // Normalize
+    const norm = Math.sqrt(vector.reduce((acc, val) => acc + val * val, 0));
+    vector = vector.map(val => val / norm);
+
+    // Apply shifted inverse iteration to find smallest non-zero eigenvector
+    // This is a simplification of the actual algorithm
+    for (let iter = 0; iter < 100; iter++) {
+      // Apply Laplacian
+      const newVec = Array(N).fill(0);
+      for (let i = 0; i < N; i++) {
+        for (let j = 0; j < N; j++) {
+          newVec[i] += L[i][j] * vector[j];
+        }
+      }
+
+      // Orthogonalize against the constant vector (eigenvector with eigenvalue 0)
+      const mean = newVec.reduce((acc, val) => acc + val, 0) / N;
+      newVec.forEach((val, idx, arr) => { arr[idx] = val - mean; });
+
+      // Normalize
+      const newNorm = Math.sqrt(newVec.reduce((acc, val) => acc + val * val, 0));
+      if (newNorm < 1e-10) continue; // Skip if vector is close to zero
+
+      vector = newVec.map(val => val / newNorm);
+    }
+
+    eigenvectors.push(vector);
+  }
+
+  // Create position array from eigenvectors
+  const positions: number[][] = Array(N).fill(0).map(() => Array(dim).fill(0));
+  for (let i = 0; i < N; i++) {
+    for (let d = 0; d < dim; d++) {
+      positions[i][d] = eigenvectors[d][i];
+    }
+  }
+
+  // Rescale and create position dictionary
+  const scaledPositions = rescaleLayout(positions as any, scale);
+  const pos: PositionMap = {};
+  nodes.forEach((node: Node, i: number) => {
+    pos[node] = (scaledPositions as number[][])[i].map((val: number, j: number) => val + center[j]);
+  });
+
+  return pos;
+}

package/src/types/embedding.ts

@@ -0,0 +1,11 @@
+/**
+ * Embedding type for planar layout algorithms
+ */
+
+import { Node, Position } from './index';
+
+export interface Embedding {
+  nodeOrder: Node[];
+  faceList: Node[][];
+  nodePositions: Record<Node, Position>;
+}

package/src/types/graph.ts

@@ -0,0 +1,13 @@
+/**
+ * Core graph type definitions
+ */
+
+export type Node = string | number;
+
+export type Edge = [Node, Node];
+
+export type Graph = {
+  nodes: () => Node[];
+  edges: () => Edge[];
+  getEdgeData?: (source: Node, target: Node, attr: string) => any;
+};

package/src/types/index.ts

@@ -0,0 +1,7 @@
+/**
+ * Re-export all type definitions
+ */
+
+export * from './graph';
+export * from './layout';
+export * from './embedding';

package/src/types/layout.ts

@@ -0,0 +1,9 @@
+/**
+ * Layout-specific type definitions
+ */
+
+import { Node } from './graph';
+
+export type Position = number[];
+
+export type PositionMap = Record<Node, Position>;

package/src/utils/graph.ts

@@ -0,0 +1,77 @@
+/**
+ * Graph utility functions
+ */
+
+import { Graph, Node, Edge } from '../types';
+
+/**
+ * Extract nodes from a graph object
+ * 
+ * @param G - Graph or list of nodes
+ * @returns Array of nodes
+ */
+export function getNodesFromGraph(G: Graph | Node[]): Node[] {
+  if (Array.isArray(G)) {
+    return G;
+  }
+  return G.nodes();
+}
+
+/**
+ * Extract edges from a graph object
+ * 
+ * @param G - Graph or list of nodes
+ * @returns Array of edges
+ */
+export function getEdgesFromGraph(G: Graph | Node[]): Edge[] {
+  if (Array.isArray(G)) {
+    return [];
+  }
+  return G.edges();
+}
+
+/**
+ * Get the degree of a node in the graph
+ * 
+ * @param graph - Graph object
+ * @param node - Node to get degree for
+ * @returns Degree of the node
+ */
+export function getNodeDegree(graph: Graph, node: Node): number {
+  if (!graph.edges) return 0;
+  
+  const edges = graph.edges();
+  let degree = 0;
+  
+  for (const [source, target] of edges) {
+    if (source === node || target === node) {
+      degree++;
+    }
+  }
+  
+  return degree;
+}
+
+/**
+ * Get the neighbors of a node in the graph
+ * 
+ * @param graph - Graph object
+ * @param node - Node to get neighbors for
+ * @returns Array of neighbor nodes
+ */
+export function getNeighbors(graph: Graph, node: Node): Node[] {
+  if (!graph.edges) return [];
+
+  const neighbors = new Set<Node>();
+  const edges = graph.edges();
+
+  for (const [source, target] of edges) {
+    if (source === node) {
+      neighbors.add(target);
+    } else if (target === node) {
+      neighbors.add(source);
+    }
+  }
+
+  return Array.from(neighbors);
+}

package/src/utils/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Re-export all utilities
+ */
+
+export * from './numpy';
+export * from './random';
+export * from './graph';
+export * from './params';
+export * from './rescale';

package/src/utils/numpy.ts

@@ -0,0 +1,108 @@
+/**
+ * NumPy-like array manipulation functions
+ * Maintains exact same functionality as original implementation
+ */
+
+export const np = {
+  zeros: function (shape: number | number[]): number | number[] | number[][] | any[] {
+    if (typeof shape === 'number') {
+      return Array(shape).fill(0);
+    }
+    if (shape.length === 1) {
+      return Array(shape[0]).fill(0);
+    }
+    return Array(shape[0]).fill(0).map(() => this.zeros(shape.slice(1)));
+  },
+
+  ones: function (shape: number | number[]): number | any[] {
+    if (typeof shape === 'number') {
+      return Array(shape).fill(1);
+    }
+    if (shape.length === 1) {
+      return Array(shape[0]).fill(1);
+    }
+    return Array(shape[0]).fill(1).map(() => this.ones(shape.slice(1)));
+  },
+
+  linspace: function (start: number, stop: number, num: number): number[] {
+    const step = (stop - start) / (num - 1);
+    return Array.from({ length: num }, (_, i) => start + i * step);
+  },
+
+  array: function (arr: any): any[] {
+    return Array.isArray(arr) ? [...arr] : [arr];
+  },
+
+  repeat: function (a: any, repeats: number): any[] {
+    const result: any[] = [];
+    for (let i = 0; i < repeats; i++) {
+      result.push(...np.array(a));
+    }
+    return result;
+  },
+
+  mean: function (arr: number[] | number[][], axis: number | null = null): number | number[] {
+    if (axis === null) {
+      const flatArr = Array.isArray(arr[0])
+        ? (arr as number[][]).flat(Infinity) as number[]
+        : arr as number[];
+      const sum = flatArr.reduce((a, b) => a + b, 0);
+      return sum / flatArr.length;
+    }
+
+    if (axis === 0) {
+      const result: number[] = [];
+      const matrix = arr as number[][];
+      for (let i = 0; i < matrix[0].length; i++) {
+        let sum = 0;
+        for (let j = 0; j < matrix.length; j++) {
+          sum += matrix[j][i];
+        }
+        result.push(sum / matrix.length);
+      }
+      return result;
+    }
+
+    return (arr as number[][]).map(row => np.mean(row) as number);
+  },
+
+  add: function (a: number | number[], b: number | number[]): number | number[] {
+    if (!Array.isArray(a) && !Array.isArray(b)) {
+      return a + b;
+    }
+    if (!Array.isArray(a)) {
+      return (b as number[]).map(val => a + val);
+    }
+    if (!Array.isArray(b)) {
+      return (a as number[]).map(val => val + b);
+    }
+    return (a as number[]).map((val, i) => val + (b as number[])[i]);
+  },
+
+  subtract: function (a: number | number[], b: number | number[]): number | number[] {
+    if (!Array.isArray(a) && !Array.isArray(b)) {
+      return a - b;
+    }
+    if (!Array.isArray(a)) {
+      return (b as number[]).map(val => a - val);
+    }
+    if (!Array.isArray(b)) {
+      return (a as number[]).map(val => val - b);
+    }
+    return (a as number[]).map((val, i) => val - (b as number[])[i]);
+  },
+
+  max: function (arr: number | number[]): number {
+    if (!Array.isArray(arr)) return arr;
+    return Math.max(...(arr as number[]).flat(Infinity) as number[]);
+  },
+
+  min: function (arr: number | number[]): number {
+    if (!Array.isArray(arr)) return arr;
+    return Math.min(...(arr as number[]).flat(Infinity) as number[]);
+  },
+
+  norm: function (arr: number[]): number {
+    return Math.sqrt(arr.reduce((sum, val) => sum + val * val, 0));
+  }
+};

package/src/utils/params.ts

@@ -0,0 +1,26 @@
+/**
+ * Parameter processing utilities
+ */
+
+import { Graph, Node } from '../types';
+
+/**
+ * Process and validate layout parameters
+ * Helper function similar to _process_params in Python version
+ * 
+ * @param G - Graph object or array of nodes
+ * @param center - Center coordinates or null
+ * @param dim - Dimension of layout
+ * @returns Processed parameters
+ */
+export function _processParams(G: Graph | Node[], center: number[] | null, dim: number): { G: Graph | Node[]; center: number[] } {
+  if (!center) {
+    center = Array(dim).fill(0);
+  }
+
+  if (center.length !== dim) {
+    throw new Error("length of center coordinates must match dimension of layout");
+  }
+
+  return { G, center };
+}