deepgeodemo 0.1.4__tar.gz

deepgeodemo-0.1.4/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Stef De Sabbata
+
+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.

deepgeodemo-0.1.4/PKG-INFO

@@ -0,0 +1,133 @@
+Metadata-Version: 2.4
+Name: deepgeodemo
+Version: 0.1.4
+Summary: A library and CLI tool for geodemographic classification using deep autoencoders.
+Author-email: Stef De Sabbata <stef@stefdesabbata.io>
+License: MIT
+Project-URL: Homepage, https://stefdesabbata.github.io/deepgeodemo/
+Project-URL: Repository, https://github.com/stefdesabbata/deepgeodemo
+Keywords: geodemographic,geodemographics,autoencoders
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: GIS
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: numpy>=2.0
+Requires-Dist: pandas>=2.2
+Requires-Dist: scikit-learn>=1.5
+Requires-Dist: torch>=2.4
+Requires-Dist: torchvision
+Requires-Dist: torchaudio
+Requires-Dist: tensorboard>=2.18
+Requires-Dist: lightning>=2.4
+Requires-Dist: matplotlib>=3.9
+Requires-Dist: seaborn>=0.13
+Requires-Dist: clustergram>=0.8
+Requires-Dist: pytest>=7.0
+Provides-Extra: gpu
+Requires-Dist: cudf-cu12>=24.10; extra == "gpu"
+Requires-Dist: cuml-cu12>=24.10; extra == "gpu"
+Dynamic: license-file
+
+# DeepGeoDemo: Deep Embedding Geodemographics Made Simple
+
+## Overview
+
+DeepGeoDemo makes it easy to build geodemographic classifications powered by deep embeddings. Configure your autoencoder in a simple YAML file and run the full pipeline from the command line, or import DeepGeoDemo as a Python library when you need more control.
+
+
+
+## Installation
+
+The package is currently under development and can be installed from the repository. The package requires Python 3.12. The package can be installed using the following commands. This will install the package with the CPU dependencies --- i.e., the cpu version of [PyTorch](https://pytorch.org/) and [scikit-learn](https://scikit-learn.org/stable/index.html) for clustering.
+
+Create a virtual environment, e.g. using conda.
+
+```bash
+conda create -n deepgeodemo python=3.12
+conda activate deepgeodemo
+```
+
+Install the package via `pip`.
+
+```bash
+pip install deepgeodemo
+```
+
+Alternatively, the package can be installed with the GPU dependencies if available and [RAPIDS](https://docs.rapids.ai/) for the clustering.
+
+```bash
+pip install --extra-index-url=https://pypi.nvidia.com deepgeodemo[gpu]
+```
+
+
+## Usage
+
+The commands below illustrate how to use the Command-Line Interface (CLI) to run the tool using the example configuration file `example/example.yml` and data (eight random blobs in sixteen dimensions). The `-t` flag is used to train the autoencoder and `l` to create the latent representation. The `-s` flag is used to search for the best k. The `-c` flag is used to run clustering using k-means. If available, the cuml backend is used for clustering. The `-v` flag is optional and is used to display the progress of the process. 
+
+Train the autoencoder.
+
+```bash
+deepgeodemo -tv example/example.yml
+```
+
+Create latent representation using on the previously trained autoencoder. Note that this will load a model from disk, and thus it will rais a warning message, as that can result in **arbitrary code execution**. Do it only if you got the file from a **trusted** source -- e.g., a model file you trained yourself, using the command above.
+
+```bash
+deepgeodemo -lv example/example.yml
+```
+
+Alternatively, you can train the autoencoder and create the latent representation in one go. In this case, the autoencoder will still be saved, but the latent representation will be created directly with the model in memory (rather than loading from the disk).
+
+```bash
+deepgeodemo -tlv example/example.yml
+```
+
+Run clustering in test mode to search for best k. Add `-r` for RAPIDS backend, default is scikit-learn.
+
+```bash
+deepgeodemo -sv example/example.yml
+```
+
+Run clustering using k-means. Add `-r` for RAPIDS backend, default is scikit-learn.
+
+```bash
+deepgeodemo -cv example/example.yml
+```
+
+Alternatively, you can run everything in one go as well.
+
+```bash
+deepgeodemo -tlscv example/example.yml
+```
+
+For a more concrete example, you can test the tool using the 2021 OAC data available from [Jakub Wyszomierski's repo](https://github.com/jakubwyszomierski/OAC2021-2). Download the [Clean data](https://liveuclac-my.sharepoint.com/:f:/g/personal/zcfajwy_ucl_ac_uk/Eqd1EV2WgOFJmZ7kLx-oDYMBdxqNe9IJmli6M8S-e91F0g?e=M9wh5j) used to create the [2021 OAC](https://data.cdrc.ac.uk/dataset/output-area-classification-2021), unzip the file and set the value of `data: source` to the location of one of the file datasets on your computer. It is advisable to normalise the data before training the autoencoder, e.g., using min-max scaling. Please increase the number of epochs and the number of clustering iteration to get meaninful results.
+
+
+
+## Unit Tests
+
+If you want to run the unit tests, you can install the package in editable mode.
+
+```bash
+# Clone the repository
+gh repo clone stefdesabbata/deepgeodemo
+cd deepgeodemo
+
+# Install the package
+pip install -e .
+```
+
+Then run the tests.
+
+```bash
+python -m pytest tests/ -v
+```
+
+
+## Acknowledgement
+
+Many thanks to [Owen Goodwin](https://github.com/ogoodwin505), [Pengyuan Liu](https://github.com/PengyuanLiu1993) and [Alex Singleton](https://github.com/alexsingleton) for their collaboration on this project and for testing the pre-alpha versions of the tool.

deepgeodemo-0.1.4/README.md

@@ -0,0 +1,99 @@
+# DeepGeoDemo: Deep Embedding Geodemographics Made Simple
+
+## Overview
+
+DeepGeoDemo makes it easy to build geodemographic classifications powered by deep embeddings. Configure your autoencoder in a simple YAML file and run the full pipeline from the command line, or import DeepGeoDemo as a Python library when you need more control.
+
+
+
+## Installation
+
+The package is currently under development and can be installed from the repository. The package requires Python 3.12. The package can be installed using the following commands. This will install the package with the CPU dependencies --- i.e., the cpu version of [PyTorch](https://pytorch.org/) and [scikit-learn](https://scikit-learn.org/stable/index.html) for clustering.
+
+Create a virtual environment, e.g. using conda.
+
+```bash
+conda create -n deepgeodemo python=3.12
+conda activate deepgeodemo
+```
+
+Install the package via `pip`.
+
+```bash
+pip install deepgeodemo
+```
+
+Alternatively, the package can be installed with the GPU dependencies if available and [RAPIDS](https://docs.rapids.ai/) for the clustering.
+
+```bash
+pip install --extra-index-url=https://pypi.nvidia.com deepgeodemo[gpu]
+```
+
+
+## Usage
+
+The commands below illustrate how to use the Command-Line Interface (CLI) to run the tool using the example configuration file `example/example.yml` and data (eight random blobs in sixteen dimensions). The `-t` flag is used to train the autoencoder and `l` to create the latent representation. The `-s` flag is used to search for the best k. The `-c` flag is used to run clustering using k-means. If available, the cuml backend is used for clustering. The `-v` flag is optional and is used to display the progress of the process. 
+
+Train the autoencoder.
+
+```bash
+deepgeodemo -tv example/example.yml
+```
+
+Create latent representation using on the previously trained autoencoder. Note that this will load a model from disk, and thus it will rais a warning message, as that can result in **arbitrary code execution**. Do it only if you got the file from a **trusted** source -- e.g., a model file you trained yourself, using the command above.
+
+```bash
+deepgeodemo -lv example/example.yml
+```
+
+Alternatively, you can train the autoencoder and create the latent representation in one go. In this case, the autoencoder will still be saved, but the latent representation will be created directly with the model in memory (rather than loading from the disk).
+
+```bash
+deepgeodemo -tlv example/example.yml
+```
+
+Run clustering in test mode to search for best k. Add `-r` for RAPIDS backend, default is scikit-learn.
+
+```bash
+deepgeodemo -sv example/example.yml
+```
+
+Run clustering using k-means. Add `-r` for RAPIDS backend, default is scikit-learn.
+
+```bash
+deepgeodemo -cv example/example.yml
+```
+
+Alternatively, you can run everything in one go as well.
+
+```bash
+deepgeodemo -tlscv example/example.yml
+```
+
+For a more concrete example, you can test the tool using the 2021 OAC data available from [Jakub Wyszomierski's repo](https://github.com/jakubwyszomierski/OAC2021-2). Download the [Clean data](https://liveuclac-my.sharepoint.com/:f:/g/personal/zcfajwy_ucl_ac_uk/Eqd1EV2WgOFJmZ7kLx-oDYMBdxqNe9IJmli6M8S-e91F0g?e=M9wh5j) used to create the [2021 OAC](https://data.cdrc.ac.uk/dataset/output-area-classification-2021), unzip the file and set the value of `data: source` to the location of one of the file datasets on your computer. It is advisable to normalise the data before training the autoencoder, e.g., using min-max scaling. Please increase the number of epochs and the number of clustering iteration to get meaninful results.
+
+
+
+## Unit Tests
+
+If you want to run the unit tests, you can install the package in editable mode.
+
+```bash
+# Clone the repository
+gh repo clone stefdesabbata/deepgeodemo
+cd deepgeodemo
+
+# Install the package
+pip install -e .
+```
+
+Then run the tests.
+
+```bash
+python -m pytest tests/ -v
+```
+
+
+## Acknowledgement
+
+Many thanks to [Owen Goodwin](https://github.com/ogoodwin505), [Pengyuan Liu](https://github.com/PengyuanLiu1993) and [Alex Singleton](https://github.com/alexsingleton) for their collaboration on this project and for testing the pre-alpha versions of the tool.

deepgeodemo-0.1.4/pyproject.toml

@@ -0,0 +1,51 @@
+[build-system]
+requires = ["setuptools>=75", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "deepgeodemo"
+version = "0.1.4"
+description = "A library and CLI tool for geodemographic classification using deep autoencoders."
+keywords = ["geodemographic", "geodemographics", "autoencoders"]
+readme = "README.md"
+requires-python = ">=3.12"
+license = { text = "MIT" }
+authors = [
+  {name = "Stef De Sabbata", email = "stef@stefdesabbata.io"}
+]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Science/Research",
+  "Topic :: Scientific/Engineering :: GIS",
+  "Programming Language :: Python :: 3.12"
+]
+dependencies = [
+  "pyyaml>=6.0",
+  "numpy>=2.0",
+  "pandas>=2.2",
+  "scikit-learn>=1.5",
+  "torch>=2.4",
+  "torchvision",
+  "torchaudio",
+  "tensorboard>=2.18",
+  "lightning>=2.4",
+  "matplotlib>=3.9",
+  "seaborn>=0.13",
+  "clustergram>=0.8",
+  "pytest>=7.0"
+]
+
+[project.optional-dependencies]
+# Optional RAPIDS libraries
+gpu = [
+  "cudf-cu12>=24.10",
+  "cuml-cu12>=24.10"
+]
+
+[project.urls]
+Homepage = "https://stefdesabbata.github.io/deepgeodemo/"
+Repository = "https://github.com/stefdesabbata/deepgeodemo"
+
+[project.scripts]
+deepgeodemo = "deepgeodemo.cli:main"
+

deepgeodemo-0.1.4/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

deepgeodemo-0.1.4/src/deepgeodemo/__init__.py

@@ -0,0 +1,2 @@
+from .models import AutoEncoder
+from .autoencoder_train_latent import train_latent

deepgeodemo-0.1.4/src/deepgeodemo/activation.py

@@ -0,0 +1,153 @@
+from typing import Any, Literal
+import torch
+from torch import nn
+
+
+# Based on TopK activation function
+# by Gao et al (2024)
+# https://arxiv.org/abs/2406.04093
+#
+# Based on
+# https://github.com/openai/sparse_autoencoder
+# MIT license
+
+class TopK(nn.Module):
+    """TopK activation."""
+
+    def __init__(self,
+            postact_fn: nn.Module,
+            k: int
+            ) -> None:
+        super().__init__()
+        self.postact_fn = postact_fn
+        self.k = k
+
+    # Forward pass
+    def forward(self, x: torch.Tensor) -> torch.Tensor:
+        # If zeroing is disabled, just apply the post-activation function
+        output = self.postact_fn(x)
+        # Select top-k activations
+        topk = torch.topk(output, k=self.k, dim=-1)
+        # make all other values 0
+        output = torch.zeros_like(output)
+        output.scatter_(-1, topk.indices, topk.values)
+        return output
+
+# Based on Jumping Ahead's JumpReLU activation function
+# by Rajamanoharan et al (2024)
+# https://arxiv.org/abs/2407.14435
+#
+# Based on
+# https://github.com/jbloomAus/SAELens/blob/abcf9a603acf9344d249f0a595e89be45b77b7cf/sae_lens/training/training_sae.py#L64
+# MIT license
+#
+# Note: suggested hyperparameters for JumpReLU
+# jumprelu_bandwidth=0.001
+# jumprelu_init_threshold=0.001
+
+def _rectangle(x: torch.Tensor) -> torch.Tensor:
+    return ((x > -0.5) & (x < 0.5)).to(x.dtype)
+
+class _JumpReLUFunction(torch.autograd.Function):
+    """
+    Implements the JumpReLU activation function from Appendix J of https://arxiv.org/abs/2407.14435
+    """
+    
+    @staticmethod
+    def forward(
+            x: torch.Tensor,
+            threshold: torch.Tensor,
+            bandwidth: float,
+            ) -> torch.Tensor:
+        # Validate threshold tensor
+        if not (threshold > 0).all():
+            raise ValueError("All values in the threshold tensor must be positive.")
+        # Return the JumpReLU activation
+        return (x * (x > threshold)).to(x.dtype)
+
+    @staticmethod
+    def setup_context(
+            ctx:    Any, 
+            inputs: tuple[torch.Tensor, torch.Tensor, float], 
+            output: torch.Tensor
+            ) -> None:
+        # Save the input tensors and bandwidth for backward pass
+        x, threshold, bandwidth = inputs
+        del output
+        ctx.save_for_backward(x, threshold)
+        ctx.bandwidth = bandwidth
+
+    @staticmethod
+    def backward(
+            ctx:         Any, 
+            grad_output: torch.Tensor
+            ) -> tuple[torch.Tensor, torch.Tensor, None]:
+        # Retrieve saved tensors and bandwidth
+        x, threshold = ctx.saved_tensors
+        bandwidth = ctx.bandwidth
+        x_grad = (x > threshold).to(x.dtype) * grad_output
+        # Pseudo-derivative for the threshold using the STE
+        threshold_grad = torch.sum(
+            -(threshold / bandwidth)
+            * _rectangle((x - threshold) / bandwidth)
+            * grad_output,
+            dim=0,
+        )
+        return x_grad, threshold_grad, None
+    
+def jump_relu(
+        x:         torch.Tensor, 
+        threshold: torch.Tensor, 
+        bandwidth: float = 0.001
+        ) -> torch.Tensor:
+    """
+    Functional wrapper for the JumpReLU activation function.
+
+    Args:
+        x (torch.Tensor): The input tensor (pre-activations).
+        threshold (torch.Tensor): The trainable threshold parameter (θ).
+        bandwidth (float): The kernel bandwidth hyperparameter (ε).
+
+    Returns:
+        torch.Tensor: The output of the JumpReLU activation.
+    """
+    return _JumpReLUFunction.apply(x, threshold, bandwidth)
+
+
+class JumpReLU(nn.Module):
+    """
+    A PyTorch nn.Module for the JumpReLU activation function.
+
+    Args:
+        num_features (int): The number of features in the input tensor (e.g., M).
+        initial_threshold (float): The initial value for the threshold θ.
+        bandwidth (float): The kernel bandwidth hyperparameter ε.
+    """
+    def __init__(self, 
+            num_features:         int, 
+            initial_threshold: float = 0.001, 
+            bandwidth:         float = 0.001
+            ) -> None:
+        super().__init__()
+        # Bandwidth
+        self.bandwidth = bandwidth
+        # Threshold
+        # To ensure the threshold remains positive, train its logarithm.
+        initial_log_threshold = torch.log(torch.tensor(initial_threshold))
+        self.log_threshold = nn.Parameter(torch.full((num_features,), initial_log_threshold))
+
+    def forward(self, x: torch.Tensor) -> torch.Tensor:
+        """
+        Applies the JumpReLU activation to the input tensor.
+
+        Args:
+            x (torch.Tensor): The input tensor of pre-activations.
+        
+        Returns:
+            The output tensor.
+        """
+        # Exponentiate to get the positive threshold value for the forward pass.
+        threshold = torch.exp(self.log_threshold)
+        # Calculate pre-activations (see paper's SAE implementation https://arxiv.org/abs/2407.14435 )
+        x = torch.relu(x)
+        return jump_relu(x, threshold, self.bandwidth)

deepgeodemo-0.1.4/src/deepgeodemo/autoencoder_search.py

@@ -0,0 +1,97 @@
+import itertools
+import collections.abc
+import pandas as pd
+import torch
+from .autoencoder_train_latent import train_latent
+
+
+# Utitlities for generating configurations to search ----------------------
+
+# Split keys in the format 'key: value' into a list
+def key_splitter(key):
+    return key.split(': ') if ':' in key else [key]
+
+# Generate dictionaries of options from product
+# By Seth Johnson via stackoverflow
+# https://stackoverflow.com/questions/5228158/cartesian-product-of-a-dictionary-of-lists
+def product_dict(**kwargs):
+    keys = kwargs.keys()
+    for instance in itertools.product(*kwargs.values()):
+        yield dict(zip(keys, instance))
+
+# Generate configurations based on a base configuration and options
+def generate_configs(base, options, state_subversion_of=None):
+    configs = []
+    subv = 0
+    # For each combination of options, create a new configuration
+    for option in product_dict(**options):
+        description = {**base, **option}
+        # Add a version number to the configuration if specified
+        if state_subversion_of is not None:
+            subv += 1
+            description['autoencoder: version'] = str(state_subversion_of) + '-' + str(subv)
+        # Create config
+        config = {}
+        # For each item of the description
+        for descr_key, descr_value in description.items():
+            descr_key = key_splitter(descr_key)
+            config_pointer = config
+            # Traverse the config structure to the right position
+            for k in descr_key[:-1]:
+                if not k in config_pointer.keys():
+                    config_pointer[k] = {}
+                config_pointer = config_pointer[k]
+            # Set the value at the right position
+            config_pointer[descr_key[-1]] = descr_value
+        # Add the configuration to the list
+        configs.append(config)
+        # Clean up variables
+        del config, description, descr_key, descr_value, config_pointer
+    # Return all configs
+    return configs
+
+# Flatten dictionaries for reporting
+def flatten_dict(d, parent_key = ''):
+    items = []
+    for k, v in d.items():
+        new_key = parent_key + '_' + k if parent_key else k
+        if isinstance(v, collections.abc.MutableMapping) and v:
+            items.extend(flatten_dict(v, new_key).items())
+        else:
+            # Handle tensors
+            if isinstance(v, torch.Tensor):
+                if v.numel() == 1:
+                    v = v.item()
+                else:
+                    v = v.detach().cpu().tolist()
+            v = v if isinstance(v, (int, float)) else str(v)
+            items.append((new_key, v))
+    return dict(items)
+
+# Generate final report from configurations and reports
+def generate_final_report(configs, reports):
+    flat_configs = [flatten_dict(config) for config in configs]
+    flat_reports = [flatten_dict(report) for report in reports]
+    final_reports = []
+    for config, report in zip(flat_configs, flat_reports):
+        final_reports.append({**config, **report})
+    final_report_df = pd.DataFrame(final_reports)
+    return final_report_df
+
+
+# Main method searching across configurations -----------------------------
+
+def explore_configs(ae_base, ae_options, state_subversion_of=0, create_latent=False, verbose=True):
+    # Generate configurations based on the base and options
+    ae_configs = generate_configs(ae_base, ae_options, state_subversion_of)
+    ae_reports = []
+    # Run the training for each configuration
+    for i, ae_config in enumerate(ae_configs):
+        print(f'\n\n{'-'*76}')
+        print(f'Exploring configuration {i+1} of {len(ae_configs)}')
+        print(f'{'-'*76}\n')
+        ae_report = train_latent(ae_config, create_latent=create_latent, verbose=verbose)
+        ae_reports.append(ae_report)
+        del ae_report
+    ae_final_report = generate_final_report(ae_configs, ae_reports)
+    return ae_final_report