faissknn 0.0.1__tar.gz

faissknn-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Isaac Corley
+
+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.

faissknn-0.0.1/PKG-INFO

@@ -0,0 +1,89 @@
+Metadata-Version: 2.1
+Name: faissknn
+Version: 0.0.1
+Summary: Faiss implementation of multiclass and multilabel K-Nearest Neighbors Classifiers
+Home-page: https://github.com/isaaccorley/faissknn
+Author: Isaac Corley
+Author-email: isaac.corley@my.utsa.edu
+Keywords: pytorch,machine learning,deep learning
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: <4,>=3.9
+Description-Content-Type: text/markdown
+Provides-Extra: dev
+License-File: LICENSE
+
+# FAISSKNN
+`faissknn` contains implementations for both multiclass and multilabel K-Nearest Neighbors Classifier implementations. The classifiers follow the `scikit-learn`: `fit`, `predict`, and `predict_proba` methods.
+
+### Install
+
+The FAISS authors recommend to install `faiss` through conda e.g. `conda install -c pytorch faiss-gpu`. See [FAISS install page](https://github.com/facebookresearch/faiss/blob/main/INSTALL.md) for more info.
+
+Once `faiss` is installed, `faissknn` can be install through pypi:
+
+```
+pip install faissknn
+```
+
+### Usage
+
+Multiclass:
+
+```python
+from sklearn.datasets import make_classification
+from sklearn.model_selection import train_test_split
+
+from faissknn import FaissKNNClassifier
+
+x, y = make_classification()
+x_train, x_test, y_train, y_test = train_test_split(x, y)
+model = FaissKNNClassifier(
+    n_neighbors=5,
+    n_classes=None,
+    device="cpu"
+)
+model.fit(x_train, y_train)
+
+y_pred = model.predict(x_test) # (N,)
+y_proba = model.predict_proba(x_test) # (N, C)
+```
+
+Multilabel:
+
+```python
+from sklearn.datasets import make_classification
+from sklearn.model_selection import train_test_split
+
+from faissknn import FaissKNNMultilabelClassifier
+
+x, y = make_multilabel_classification()
+x_train, x_test, y_train, y_test = train_test_split(x, y)
+model = FaissKNNClassifier(
+    n_neighbors=5,
+    device="cpu"
+)
+model.fit(x_train, y_train)
+
+y_pred = model.predict(x_test) # (N, C)
+y_proba = model.predict_proba(x_test) # (N, C)
+```
+
+GPU/CUDA: `faissknn` also supports running on the GPU to speed up computation. Simply change the device to `cuda` or a specific cuda device `cuda:0`
+
+```python
+model = FaissKNNClassifier(
+    n_neighbors=5,
+    device="cuda"
+)
+model = FaissKNNClassifier(
+    n_neighbors=5,
+    device="cuda:0"
+)
+```

faissknn-0.0.1/README.md

@@ -0,0 +1,68 @@
+# FAISSKNN
+`faissknn` contains implementations for both multiclass and multilabel K-Nearest Neighbors Classifier implementations. The classifiers follow the `scikit-learn`: `fit`, `predict`, and `predict_proba` methods.
+
+### Install
+
+The FAISS authors recommend to install `faiss` through conda e.g. `conda install -c pytorch faiss-gpu`. See [FAISS install page](https://github.com/facebookresearch/faiss/blob/main/INSTALL.md) for more info.
+
+Once `faiss` is installed, `faissknn` can be install through pypi:
+
+```
+pip install faissknn
+```
+
+### Usage
+
+Multiclass:
+
+```python
+from sklearn.datasets import make_classification
+from sklearn.model_selection import train_test_split
+
+from faissknn import FaissKNNClassifier
+
+x, y = make_classification()
+x_train, x_test, y_train, y_test = train_test_split(x, y)
+model = FaissKNNClassifier(
+    n_neighbors=5,
+    n_classes=None,
+    device="cpu"
+)
+model.fit(x_train, y_train)
+
+y_pred = model.predict(x_test) # (N,)
+y_proba = model.predict_proba(x_test) # (N, C)
+```
+
+Multilabel:
+
+```python
+from sklearn.datasets import make_classification
+from sklearn.model_selection import train_test_split
+
+from faissknn import FaissKNNMultilabelClassifier
+
+x, y = make_multilabel_classification()
+x_train, x_test, y_train, y_test = train_test_split(x, y)
+model = FaissKNNClassifier(
+    n_neighbors=5,
+    device="cpu"
+)
+model.fit(x_train, y_train)
+
+y_pred = model.predict(x_test) # (N, C)
+y_proba = model.predict_proba(x_test) # (N, C)
+```
+
+GPU/CUDA: `faissknn` also supports running on the GPU to speed up computation. Simply change the device to `cuda` or a specific cuda device `cuda:0`
+
+```python
+model = FaissKNNClassifier(
+    n_neighbors=5,
+    device="cuda"
+)
+model = FaissKNNClassifier(
+    n_neighbors=5,
+    device="cuda:0"
+)
+```

faissknn-0.0.1/faissknn/__init__.py

@@ -0,0 +1,5 @@
+"""faissknn."""
+from .knn import FaissKNNClassifier, FaissKNNMultilabelClassifier  # noqa: F401
+
+__author__ = "Isaac Corley"
+__version__ = "0.0.1"

faissknn-0.0.1/faissknn/knn.py

@@ -0,0 +1,175 @@
+"""Modified from https://github.com/scikit-learn-contrib/DESlib/blob/master/deslib/util/faiss_knn_wrapper.py#L19-L203."""  # noqa: E501
+from typing import Optional
+
+import faiss
+import numpy as np
+
+
+class FaissKNNClassifier:
+    """A multiclass exact KNN classifier implemented using the FAISS library."""
+
+    def __init__(
+        self, n_neighbors: int, n_classes: Optional[int] = None, device: str = "cpu"
+    ) -> None:
+        """Instantiate a faiss KNN Classifier.
+
+        Args:
+            n_neighbors: number of KNN neighbors
+            n_classes: (optional) number of dataset classes
+                (otherwise derive from the data)
+            device: a torch device, e.g. cpu, cuda, cuda:0, etc.
+        """
+        self.n_neighbors = n_neighbors
+        self.n_classes = n_classes
+
+        if device == "cpu":
+            self.cuda = False
+            self.device = None
+        else:
+            self.cuda = True
+            if ":" in device:
+                self.device = int(device.split(":")[-1])
+            else:
+                self.device = 0
+
+    def create_index(self, d: int) -> None:
+        """Create the faiss index.
+
+        Args:
+            d: feature dimension
+        """
+        if self.cuda:
+            self.res = faiss.StandardGpuResources()
+            self.config = faiss.GpuIndexFlatConfig()
+            self.config.device = self.device
+            self.index = faiss.GpuIndexFlatL2(self.res, d, self.config)
+        else:
+            self.index = faiss.IndexFlatL2(d)
+
+    def fit(self, X: np.ndarray, y: np.ndarray) -> object:
+        """Store train X and y.
+
+        Args:
+            X: input features (N, d)
+            y: input labels (N, ...)
+
+        Returns:
+            self
+        """
+        X = np.atleast_2d(X).astype(np.float32)
+        X = np.ascontiguousarray(X)
+        self.create_index(X.shape[-1])
+        self.index.add(X)
+        self.y = y.astype(int)
+        if self.n_classes is None:
+            self.n_classes = len(np.unique(y))
+        return self
+
+    def __del__(self) -> None:
+        """Cleanup helpers."""
+        if hasattr(self, "index"):
+            self.index.reset()
+            del self.index
+        if hasattr(self, "res"):
+            self.res.noTempMemory()
+            del self.res
+
+    def predict(self, X: np.ndarray) -> np.ndarray:
+        """Predict int labels given X.
+
+        Args:
+            X: input features (N, d)
+
+        Returns:
+            preds: int predicted labels (N,)
+        """
+        X = np.atleast_2d(X).astype(np.float32)
+        _, idx = self.index.search(X, self.n_neighbors)
+        class_idx = self.y[idx]
+        counts = np.apply_along_axis(
+            lambda x: np.bincount(x, minlength=self.n_classes),
+            axis=1,
+            arr=class_idx.astype(np.int16),
+        )
+        preds = np.argmax(counts, axis=1)
+        return preds
+
+    def predict_proba(self, X: np.ndarray) -> np.ndarray:
+        """Predict float probabilities for labels given X.
+
+        Args:
+            X: input features (N, d)
+
+        Returns:
+            preds_proba: float probas per labels (N, c)
+        """
+        X = np.atleast_2d(X).astype(np.float32)
+        _, idx = self.index.search(X, self.n_neighbors)
+        class_idx = self.y[idx]
+        counts = np.apply_along_axis(
+            lambda x: np.bincount(x, minlength=self.n_classes),
+            axis=1,
+            arr=class_idx.astype(np.int16),
+        )
+
+        preds_proba = counts / self.n_neighbors
+        return preds_proba
+
+
+class FaissKNNMultilabelClassifier(FaissKNNClassifier):
+    """A multilabel exact KNN classifier implemented using the FAISS library."""
+
+    def predict(self, X: np.ndarray) -> np.ndarray:
+        """Predict one-hot int labels given X.
+
+        Args:
+            X: input features (N, d)
+
+        Returns:
+            preds: int predicted labels (N, c)
+        """
+        X = np.atleast_2d(X).astype(np.float32)
+        _, idx = self.index.search(X, self.n_neighbors)
+        class_idx = self.y[idx]
+
+        preds = []
+        for i in range(class_idx.shape[-1]):
+            class_idx_i = class_idx[..., i]
+            counts_i = np.apply_along_axis(
+                lambda x: np.bincount(x, minlength=2),
+                axis=1,
+                arr=class_idx_i.astype(np.int16),
+            )
+            preds_i = np.argmax(counts_i, axis=1)
+            preds.append(preds_i)
+
+        preds = np.stack(preds, axis=1)
+        return preds
+
+    def predict_proba(self, X):
+        """Predict float probabilities for labels given X.
+
+        Args:
+            X: input features (N, d)
+
+        Returns:
+            preds_proba: float probas per labels (N, c)
+        """
+        X = np.atleast_2d(X).astype(np.float32)
+        _, idx = self.index.search(X, self.n_neighbors)
+        class_idx = self.y[idx]
+
+        preds_proba = []
+        for i in range(class_idx.shape[-1]):
+            class_idx_i = class_idx[..., i]
+            counts_i = np.apply_along_axis(
+                lambda x: np.bincount(x, minlength=2),
+                axis=1,
+                arr=class_idx_i.astype(np.int16),
+            )
+            preds_proba_i = counts_i / self.n_neighbors
+            preds_proba_i = preds_proba_i[:, 1]
+            preds_proba.append(preds_proba_i)
+
+        preds_proba = np.stack(preds_proba, axis=1)
+        return preds_proba

faissknn-0.0.1/faissknn.egg-info/PKG-INFO

@@ -0,0 +1,89 @@
+Metadata-Version: 2.1
+Name: faissknn
+Version: 0.0.1
+Summary: Faiss implementation of multiclass and multilabel K-Nearest Neighbors Classifiers
+Home-page: https://github.com/isaaccorley/faissknn
+Author: Isaac Corley
+Author-email: isaac.corley@my.utsa.edu
+Keywords: pytorch,machine learning,deep learning
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: <4,>=3.9
+Description-Content-Type: text/markdown
+Provides-Extra: dev
+License-File: LICENSE
+
+# FAISSKNN
+`faissknn` contains implementations for both multiclass and multilabel K-Nearest Neighbors Classifier implementations. The classifiers follow the `scikit-learn`: `fit`, `predict`, and `predict_proba` methods.
+
+### Install
+
+The FAISS authors recommend to install `faiss` through conda e.g. `conda install -c pytorch faiss-gpu`. See [FAISS install page](https://github.com/facebookresearch/faiss/blob/main/INSTALL.md) for more info.
+
+Once `faiss` is installed, `faissknn` can be install through pypi:
+
+```
+pip install faissknn
+```
+
+### Usage
+
+Multiclass:
+
+```python
+from sklearn.datasets import make_classification
+from sklearn.model_selection import train_test_split
+
+from faissknn import FaissKNNClassifier
+
+x, y = make_classification()
+x_train, x_test, y_train, y_test = train_test_split(x, y)
+model = FaissKNNClassifier(
+    n_neighbors=5,
+    n_classes=None,
+    device="cpu"
+)
+model.fit(x_train, y_train)
+
+y_pred = model.predict(x_test) # (N,)
+y_proba = model.predict_proba(x_test) # (N, C)
+```
+
+Multilabel:
+
+```python
+from sklearn.datasets import make_classification
+from sklearn.model_selection import train_test_split
+
+from faissknn import FaissKNNMultilabelClassifier
+
+x, y = make_multilabel_classification()
+x_train, x_test, y_train, y_test = train_test_split(x, y)
+model = FaissKNNClassifier(
+    n_neighbors=5,
+    device="cpu"
+)
+model.fit(x_train, y_train)
+
+y_pred = model.predict(x_test) # (N, C)
+y_proba = model.predict_proba(x_test) # (N, C)
+```
+
+GPU/CUDA: `faissknn` also supports running on the GPU to speed up computation. Simply change the device to `cuda` or a specific cuda device `cuda:0`
+
+```python
+model = FaissKNNClassifier(
+    n_neighbors=5,
+    device="cuda"
+)
+model = FaissKNNClassifier(
+    n_neighbors=5,
+    device="cuda:0"
+)
+```

faissknn-0.0.1/faissknn.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+LICENSE
+README.md
+pyproject.toml
+setup.cfg
+faissknn/__init__.py
+faissknn/knn.py
+faissknn.egg-info/PKG-INFO
+faissknn.egg-info/SOURCES.txt
+faissknn.egg-info/dependency_links.txt
+faissknn.egg-info/requires.txt
+faissknn.egg-info/top_level.txt
+tests/test_knn.py

faissknn-0.0.1/faissknn.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

faissknn-0.0.1/faissknn.egg-info/requires.txt

@@ -0,0 +1,10 @@
+numpy
+
+[dev]
+black
+isort[colors]
+flake8
+pydocstyle
+pytest
+mypy
+scikit-learn

faissknn-0.0.1/faissknn.egg-info/top_level.txt

@@ -0,0 +1 @@
+faissknn

faissknn-0.0.1/pyproject.toml

@@ -0,0 +1,59 @@
+[build-system]
+requires = [
+    # setuptools 42+ required for metadata.license_files support in setup.cfg
+    "setuptools>=42,<68",
+]
+build-backend = "setuptools.build_meta"
+
+[tool.black]
+target-version = ["py39", "py310"]
+color = true
+skip_magic_trailing_comma = true
+
+[tool.isort]
+profile = "black"
+known_first_party = ["tests", "faissknn"]
+skip_gitignore = true
+color_output = true
+
+[tool.mypy]
+python_version = "3.10"
+ignore_missing_imports = true
+show_error_codes = true
+exclude = "(build|data|dist|docs/src|images|logo|logs|output)/"
+
+# Strict
+warn_unused_configs = true
+disallow_any_generics = true
+disallow_subclassing_any = true
+disallow_untyped_calls = true
+disallow_untyped_defs = true
+disallow_incomplete_defs = true
+check_untyped_defs = true
+disallow_untyped_decorators = true
+no_implicit_optional = true
+warn_redundant_casts = true
+warn_unused_ignores = true
+warn_return_any = true
+no_implicit_reexport = true
+strict_equality = true
+
+[tool.pydocstyle]
+convention = "google"
+match_dir = "(faissknn)"
+
+[tool.pytest.ini_options]
+# Skip slow tests by default
+addopts = "-m 'not slow'"
+# https://docs.pytest.org/en/latest/how-to/capture-warnings.html
+markers = [
+    "slow: marks tests as slow",
+]
+norecursedirs = [
+    ".ipynb_checkpoints",
+    "data",
+    "__pycache__",
+]
+testpaths = [
+    "tests",
+]

faissknn-0.0.1/setup.cfg

@@ -0,0 +1,60 @@
+[metadata]
+name = faissknn
+version = attr: faissknn.__version__
+author = Isaac Corley
+author_email = isaac.corley@my.utsa.edu
+description = Faiss implementation of multiclass and multilabel K-Nearest Neighbors Classifiers
+long_description = file: README.md
+long_description_content_type = text/markdown
+url = https://github.com/isaaccorley/faissknn
+license_files = LICENSE
+classifiers = 
+	Development Status :: 3 - Alpha
+	Intended Audience :: Science/Research
+	Programming Language :: Python :: 3
+	Programming Language :: Python :: 3.9
+	Programming Language :: Python :: 3.10
+	License :: OSI Approved :: MIT License
+	Operating System :: OS Independent
+	Topic :: Scientific/Engineering :: Artificial Intelligence
+keywords = pytorch, machine learning, deep learning
+
+[options]
+install_requires = 
+	numpy
+python_requires = >=3.9,<4
+packages = find:
+
+[options.packages.find]
+include = faissknn*
+
+[options.extras_require]
+dev = 
+	black
+	isort[colors]
+	flake8
+	pydocstyle
+	pytest
+	mypy
+	scikit-learn
+
+[flake8]
+max-line-length = 88
+extend-ignore = 
+	E203,
+exclude = 
+	build/,
+	dist/,
+	.cache/,
+	.mypy_cache/,
+	.pytest_cache/,
+	__pycache__/,
+	*.egg-info/,
+	
+	.git/,
+	.github/,
+
+[egg_info]
+tag_build = 
+tag_date = 0
+

faissknn-0.0.1/tests/test_knn.py

@@ -0,0 +1,25 @@
+from typing import Sequence
+
+import numpy as np
+
+from faissknn import FaissKNNClassifier, FaissKNNMultilabelClassifier
+
+
+def test_multiclass_knn(multiclass_dataset: Sequence[np.ndarray]):
+    x_train, y_train, x_test, y_test = multiclass_dataset
+    knn = FaissKNNClassifier(n_neighbors=5, n_classes=None, device="cpu")
+    knn.fit(x_train, y_train)
+    y_pred = knn.predict(x_test)
+    y_proba = knn.predict_proba(x_test)
+    assert y_pred.ndim == 1
+    assert y_proba.ndim == 2
+
+
+def test_multilabel_knn(multilabel_dataset: Sequence[np.ndarray]):
+    x_train, y_train, x_test, y_test = multilabel_dataset
+    knn = FaissKNNMultilabelClassifier(n_neighbors=5, n_classes=None, device="cpu")
+    knn.fit(x_train, y_train)
+    y_pred = knn.predict(x_test)
+    y_proba = knn.predict_proba(x_test)
+    assert y_pred.ndim == 2
+    assert y_proba.ndim == 2