Initial commit

Author: mattt

.github/workflows/ci.yml

@@ -0,0 +1,29 @@
+name: CI
+
+on: [push]
+
+jobs:
+  macos:
+    runs-on: macOS-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v1
+      - name: Build and Test
+        run: swift test
+
+  linux:
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        swift: ["5.1"]
+
+    container:
+      image: swift:${{ matrix.swift }}
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v1
+      - name: Build and Test
+        run: swift test --enable-test-discovery

.github/workflows/documentation.yml

@@ -0,0 +1,27 @@
+name: Documentation
+
+on:
+  push:
+    branches:
+      - master
+    paths:
+      - Sources
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v1
+      - name: Generate Documentation
+        uses: SwiftDocOrg/swift-doc@master
+        with:
+          inputs: "Sources"
+          output: "Documentation"
+      - name: Upload Documentation to Wiki
+        uses: SwiftDocOrg/github-wiki-publish-action@master
+        with:
+          path: "Documentation"
+        env:
+          GITHUB_PERSONAL_ACCESS_TOKEN: ${{ secrets.GITHUB_PERSONAL_ACCESS_TOKEN }}

.gitignore

@@ -0,0 +1,6 @@
+.DS_Store
+/.build
+/Packages
+/*.xcodeproj
+xcuserdata/
+.swiftpm

LICENSE.md

@@ -0,0 +1,19 @@
+Copyright 2020 Read Evaluate Press, LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a
+copy of this software and associated documentation files (the "Software"),
+to deal in the Software without restriction, including without limitation
+the rights to use, copy, modify, merge, publish, distribute, sublicense,
+and/or sell copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.

Package.swift

@@ -0,0 +1,28 @@
+// swift-tools-version:5.1
+// The swift-tools-version declares the minimum version of Swift required to build this package.
+
+import PackageDescription
+
+let package = Package(
+    name: "DBSCAN",
+    products: [
+        // Products define the executables and libraries produced by a package, and make them visible to other packages.
+        .library(
+            name: "DBSCAN",
+            targets: ["DBSCAN"]),
+    ],
+    dependencies: [
+        // Dependencies declare other packages that this package depends on.
+        // .package(url: /* package url */, from: "1.0.0"),
+    ],
+    targets: [
+        // Targets are the basic building blocks of a package. A target can define a module or a test suite.
+        // Targets can depend on other targets in this package, and on products in packages which this package depends on.
+        .target(
+            name: "DBSCAN",
+            dependencies: []),
+        .testTarget(
+            name: "DBSCANTests",
+            dependencies: ["DBSCAN"]),
+    ]
+)

README.md

@@ -0,0 +1,80 @@
+# DBSCAN
+
+**D**ensity-**b**ased **s**patial **c**lustering of **a**pplications with **n**oise
+([DBSCAN](https://en.wikipedia.org/wiki/DBSCAN)).
+
+## Usage
+
+```swift
+import DBSCAN
+import simd
+
+let input: [SIMD3<Double>] = [[ 0, 10, 20 ],
+                              [ 0, 11, 21 ],
+                              [ 0, 12, 20 ],
+                              [ 20, 33, 59 ],
+                              [ 21, 32, 56 ],
+                              [ 59, 77, 101 ],
+                              [ 58, 79, 100 ],
+                              [ 58, 76, 102 ],
+                              [ 300, 70, 20 ],
+                              [ 500, 300, 202],
+                              [ 500, 302, 204 ]]
+
+let dbscan = DBSCAN(input)
+
+#if swift(>=5.2)
+let (clusters, outliers) = dbscan(epsilon: 10,
+                                  minimumNumberOfPoints: 1,
+                                  distanceFunction: simd.distance)
+#else // Swift <5.2 requires explicit `callAsFunction` method name
+let (clusters, outliers) = dbscan.callAsFunction(epsilon: 10, 
+                                                 minimumNumberOfPoints: 1, 
+                                                 distanceFunction: simd.distance)
+#endif
+
+print(clusters)
+// [ [0, 10, 20], [0, 11, 21], [0, 12, 20] ]
+// [ [20, 33, 59], [21, 32, 56] ],
+// [ [58, 79, 100], [58, 76, 102], [59, 77, 101] ],
+// [ [500, 300, 202], [500, 302, 204] ],
+
+print(outliers)
+// [ [ 300, 70, 20 ] ]
+```
+
+## Requirements
+
+- Swift 5.1+
+
+## Installation
+
+### Swift Package Manager
+
+Add the SwiftMarkup package to your target dependencies in `Package.swift`:
+
+```swift
+import PackageDescription
+
+let package = Package(
+  name: "YourProject",
+  dependencies: [
+    .package(
+        url: "https://github.com/NSHipster/DBSCAN",
+        from: "0.0.1"
+    ),
+  ]
+)
+```
+
+Then run the `swift build` command to build your project.
+
+## License
+
+MIT
+
+## Contact
+
+Mattt ([@mattt](https://twitter.com/mattt))
+
+[SE-0253]: https://github.com/apple/swift-evolution/blob/master/proposals/0253-callable.md "Callable values of user-defined nominal types"

Sources/DBSCAN/DBSCAN.swift

@@ -0,0 +1,97 @@
+/**
+ A density-based, non-parametric clustering algorithm
+ ([DBSCAN](https://en.wikipedia.org/wiki/DBSCAN)).
+
+ Given a set of points in some space,
+ this algorithm groups points with many nearby neighbors
+ and marks points in low-density regions as outliers.
+
+ - Authors: Ester, Martin; Kriegel, Hans-Peter; Sander, Jörg; Xu, Xiaowei (1996)
+            "A density-based algorithm for discovering clusters
+            in large spatial databases with noise."
+            _Proceedings of the Second International Conference on
+            Knowledge Discovery and Data Mining (KDD-96)_.
+ */
+public struct DBSCAN<Value: Equatable> {
+    private class Point: Equatable {
+        typealias Label = Int
+
+        let value: Value
+        var label: Label?
+
+        init(_ value: Value) {
+            self.value = value
+        }
+
+        static func == (lhs: Point, rhs: Point) -> Bool {
+            return lhs.value == rhs.value
+        }
+    }
+
+    /// The values to be clustered.
+    public var values: [Value]
+
+    /// Creates a new clustering algorithm with the specified values.
+    /// - Parameter values: The values to be clustered.
+    public init(_ values: [Value]) {
+        self.values = values
+    }
+
+
+    /**
+     Clusters values according to the specified parameters.
+
+     - Parameters:
+       - epsilon: The maximum distance from a specified value
+                  for which other values are considered to be neighbors.
+       - minimumNumberOfPoints: The minimum number of points
+                                required to form a dense region.
+       - distanceFunction: A function that computes
+                           the distance between two values.
+     - Throws: Rethrows any errors produced by `distanceFunction`.
+     - Returns: A tuple containing an array of clustered values
+                and an array of outlier values.
+    */
+    public func callAsFunction(epsilon: Double, minimumNumberOfPoints: Int, distanceFunction: (Value, Value) throws -> Double) rethrows -> (clusters: [[Value]], outliers: [Value]) {
+        precondition(minimumNumberOfPoints >= 0)
+
+        let points = values.map { Point($0) }
+
+        var currentLabel = 0
+        for point in points {
+            guard point.label == nil else { continue }
+
+            var neighbors = try points.filter { try distanceFunction(point.value, $0.value) < epsilon }
+            if neighbors.count >= minimumNumberOfPoints {
+                defer { currentLabel += 1 }
+                point.label = currentLabel
+
+                while !neighbors.isEmpty {
+                    let neighbor = neighbors.removeFirst()
+                    guard neighbor.label == nil else { continue }
+
+                    neighbor.label = currentLabel
+
+                    let n1 = try points.filter { try distanceFunction(neighbor.value, $0.value) < epsilon }
+                    if n1.count >= minimumNumberOfPoints {
+                        neighbors.append(contentsOf: n1)
+                    }
+                }
+            }
+        }
+
+        var clusters: [[Value]] = []
+        var outliers: [Value] = []
+
+        for points in Dictionary(grouping: points, by: { $0.label }).values {
+            let values = points.map { $0.value }
+            if values.count == 1 {
+                outliers.append(contentsOf: values)
+            } else {
+                clusters.append(values)
+            }
+        }
+
+        return (clusters, outliers)
+    }
+}

Tests/DBSCANTests/DBSCANTests.swift

@@ -0,0 +1,39 @@
+import XCTest
+@testable import DBSCAN
+
+import simd
+
+final class DBSCANTests: XCTestCase {
+    func testExample() {
+        let input: [SIMD3<Double>] = [[ 0, 10, 20 ],
+                                      [ 0, 11, 21 ],
+                                      [ 0, 12, 20 ],
+                                      [ 20, 33, 59 ],
+                                      [ 21, 32, 56 ],
+                                      [ 59, 77, 101 ],
+                                      [ 58, 79, 100 ],
+                                      [ 58, 76, 102 ],
+                                      [ 300, 70, 20 ],
+                                      [ 500, 300, 202],
+                                      [ 500, 302, 204 ]]
+
+        let dbscan = DBSCAN(input)
+
+        #if swift(>=5.2)
+        let (clusters, outliers) = dbscan(epsilon: 10, minimumNumberOfPoints: 1, distanceFunction: simd.distance)
+        #else
+        let (clusters, outliers) = dbscan.callAsFunction(epsilon: 10, minimumNumberOfPoints: 1, distanceFunction: simd.distance)
+        #endif
+
+        XCTAssertEqual(clusters.count, 4)
+        XCTAssertEqual(Set(clusters.map { Set($0) }), [
+            [ [20.0, 33.0, 59.0], [21.0, 32.0, 56.0] ],
+            [ [58.0, 79.0, 100.0], [58.0, 76.0, 102.0], [59.0, 77.0, 101.0] ],
+            [ [500.0, 300.0, 202.0], [500.0, 302.0, 204.0] ],
+            [ [0.0, 10.0, 20.0], [0.0, 11.0, 21.0], [0.0, 12.0, 20.0] ]
+        ])
+
+        XCTAssertEqual(outliers.count, 1)
+        XCTAssertEqual(outliers[0], [300.0, 70.0, 20.0])
+    }
+}

Tests/LinuxMain.swift

@@ -0,0 +1 @@
+fatalError("Run with `swift test --enable-test-discovery`")