init

Author: eberhardtj

README.adoc

@@ -0,0 +1,110 @@
+= culturegraph-clustering
+:TOC:
+
+A implementation of the graph clustering method used in culturegraph.
+
+The input problem is encoded as a bipartite input graph.
+A cluster is defined as a connected component in this input graph.
+
+A bipartite graph __G(U,V)__ is represented by two node sets (namely __U__ and __V__).
+We represent the bipartite graph with an adjacency list, that lists all
+children for each parent (assuming a digraph).
+
+Although the used bipartite graph is undirected, we refer to the node set __U__ with __"Parent Node Set"__ and
+to the node set __V__ with __"Child Node Set"__.
+
+== Installation
+
+=== Requirements
+
+- Java 8 or later
+
+=== Build CLI
+
+Run the following command to construct a jar with dependencies.
+
+----
+gradlew test fatJar
+----
+
+== Command Line Client
+
+=== Example
+
+The input file describes a adjacency list, where each line starts with a parent node, followed by its child nodes.
+Parent and child nodes belong to distinct sets of nodes that only share connections between each other.
+
+----
+% File: graph.txt
+% Schema: PARENT CHILD [... CHILD]
+A a b c
+B a
+C f
+----
+
+----
+java -Xmx1G -jar cluster-cli-VERSION.jar -i graph.txt -o mapping.txt
+----
+
+The resulting mapping tags each parent node with an number.
+All nodes that share the same number form a cluster.
+
+----
+A 1
+B 1
+C 2
+----
+
+TIP: For large problem instances, you need to tweak the JVM Memory option `-Xmx`.
+
+=== Usage
+
+Usage of the command line client.
+
+```
+Usage:
+
+<main class> [-chV] -o=OUTPUT [-s=NUM] INPUT
+
+Description:
+
+Clusters a bipartite-graph by its connected components.
+
+Parameters:
+
+      INPUT                   Input adjacency list (plain text or gzip).
+
+Options:
+
+  -o, --output=OUTPUT         Output node-cluster-mapping.
+  -c                          Compress output with gzip.
+  -s, --size=NUM              Minimum component size.
+                                Default: 0
+  -h, --help                  Display this help message.
+  -V, --version               Display version info.
+```
+
+== Good To Know
+
+- The input adjacency list should only contain unique lines.
+- If a connected component does not reaches the __minimum component size__, each parent node in this component is
+assigned to the component "__-1__".
+
+=== Temporary Files
+
+The procedure creates the following temporary files during a run.
+
+.Table Temporary Files
+|===
+|Name | Description
+
+| childNodeHashes.tmp
+| A list of uniques hashes for each unique child node label.
+
+| encodedInput.tmp
+| A encoded representation of the input adjacency list, where each node label is mapped to a unique numerical identifier.
+
+| encodedParentNodes.tmp
+| A label to number mapping for each parent node.
+
+|===

algorithm/build.gradle

@@ -0,0 +1,11 @@
+apply plugin: 'java-library'
+
+dependencies {
+    api project(':graph')
+    api project(':io')
+    api project(':label-encoder')
+    implementation group: 'net.sf.trove4j', name: 'trove4j', version: '3.0.3'
+    implementation group: 'org.slf4j', name: 'slf4j-api', version: '1.7.25'
+    testImplementation group: 'org.slf4j', name: 'slf4j-simple', version: '1.7.25'
+    testImplementation group: 'junit', name: 'junit', version: '4.12'
+}

algorithm/src/main/java/org/culturegraph/clustering/algorithm/core/AdjacencyListElement.java

@@ -0,0 +1,36 @@
+package org.culturegraph.clustering.algorithm.core;
+
+import java.util.List;
+
+public class AdjacencyListElement
+{
+    private Node node;
+    private List<Node> neighbourhood;
+
+    public AdjacencyListElement(Node node, List<Node> neighbourhood)
+    {
+        this.node = node;
+        this.neighbourhood = neighbourhood;
+    }
+
+    public Node getNode()
+    {
+        return node;
+    }
+
+    public List<Node> getNeighbourhood()
+    {
+        return neighbourhood;
+    }
+
+    public String asString()
+    {
+        return node.toString() + " " + neighbourhood.toString();
+    }
+
+    @Override
+    public String toString()
+    {
+        return asString();
+    }
+}

algorithm/src/main/java/org/culturegraph/clustering/algorithm/core/Algorithm.java

@@ -0,0 +1,6 @@
+package org.culturegraph.clustering.algorithm.core;
+
+public interface Algorithm
+{
+    void run() throws Exception;
+}

algorithm/src/main/java/org/culturegraph/clustering/algorithm/core/ClusteredNode.java

@@ -0,0 +1,23 @@
+package org.culturegraph.clustering.algorithm.core;
+
+public class ClusteredNode extends Node
+{
+    private int cluster;
+
+    public ClusteredNode(String label, int cluster)
+    {
+        super(label);
+        this.cluster = cluster;
+    }
+
+    public int getCluster()
+    {
+        return cluster;
+    }
+
+    @Override
+    public String asString()
+    {
+        return this.getLabel() + " " + cluster;
+    }
+}

algorithm/src/main/java/org/culturegraph/clustering/algorithm/core/EncodedNode.java

@@ -0,0 +1,32 @@
+package org.culturegraph.clustering.algorithm.core;
+
+public class EncodedNode extends Node
+{
+
+    private int id;
+
+    public EncodedNode(String label, int id)
+    {
+        super(label);
+        this.id = id;
+    }
+
+    public int getId()
+    {
+        return id;
+    }
+
+    public static EncodedNode parse(String s)
+    {
+        String[] pair = s.split(" ", 2);
+        String label = pair[0];
+        String idNumber = pair[1];
+        return new EncodedNode(label, Integer.parseInt(idNumber));
+    }
+
+    @Override
+    public String asString()
+    {
+        return this.getLabel() + " " + id;
+    }
+}

algorithm/src/main/java/org/culturegraph/clustering/algorithm/core/Node.java

@@ -0,0 +1,32 @@
+package org.culturegraph.clustering.algorithm.core;
+
+public class Node
+{
+    private final String label;
+
+    public Node(String label)
+    {
+        this.label = label;
+    }
+
+    public String getLabel()
+    {
+        return label;
+    }
+
+    public EncodedNode encode(int id)
+    {
+        return new EncodedNode(label, id);
+    }
+
+    @Override
+    public String toString()
+    {
+        return asString();
+    }
+
+    public String asString()
+    {
+        return label;
+    }
+}

algorithm/src/main/java/org/culturegraph/clustering/algorithm/core/Procedure.java

@@ -0,0 +1,5 @@
+package org.culturegraph.clustering.algorithm.core;
+
+public interface Procedure {
+    void apply() throws ProcedureException;
+}

algorithm/src/main/java/org/culturegraph/clustering/algorithm/core/ProcedureException.java

@@ -0,0 +1,9 @@
+package org.culturegraph.clustering.algorithm.core;
+
+public class ProcedureException extends StepException
+{
+    public ProcedureException(String message, Throwable cause)
+    {
+        super(message, cause);
+    }
+}

algorithm/src/main/java/org/culturegraph/clustering/algorithm/core/Step.java

@@ -0,0 +1,6 @@
+package org.culturegraph.clustering.algorithm.core;
+
+public interface Step<T>
+{
+    T apply() throws StepException;
+}