{"id":28959611,"url":"https://github.com/aidos-lab/diss-l-ect","last_synced_at":"2025-06-24T00:03:11.521Z","repository":{"id":295987400,"uuid":"816285016","full_name":"aidos-lab/Diss-l-ECT","owner":"aidos-lab","description":"Diss-l-ECT: Dissecting Graph Data with local Euler Characteristic Transforms","archived":false,"fork":false,"pushed_at":"2025-05-28T11:33:24.000Z","size":11929,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-05-28T12:32:29.303Z","etag":null,"topics":["graph-learning","icml-2025","topological-data-analysis","topological-deep-learning"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aidos-lab.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-06-17T12:32:47.000Z","updated_at":"2025-05-28T11:33:29.000Z","dependencies_parsed_at":"2025-05-28T12:43:29.477Z","dependency_job_id":null,"html_url":"https://github.com/aidos-lab/Diss-l-ECT","commit_stats":null,"previous_names":["aidos-lab/diss-l-ect"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/aidos-lab/Diss-l-ECT","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aidos-lab%2FDiss-l-ECT","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aidos-lab%2FDiss-l-ECT/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aidos-lab%2FDiss-l-ECT/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aidos-lab%2FDiss-l-ECT/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aidos-lab","download_url":"https://codeload.github.com/aidos-lab/Diss-l-ECT/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aidos-lab%2FDiss-l-ECT/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261577987,"owners_count":23179768,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["graph-learning","icml-2025","topological-data-analysis","topological-deep-learning"],"created_at":"2025-06-24T00:03:10.392Z","updated_at":"2025-06-24T00:03:11.492Z","avatar_url":"https://github.com/aidos-lab.png","language":"Python","readme":"# Diss-l-ECT: Dissecting Graph Data with local Euler Characteristic Transforms\n\n[![arXiv](https://img.shields.io/badge/arXiv-2410.02622-b31b1b.svg)](https://arxiv.org/abs/2410.02622)\n[![GitHub contributors](https://img.shields.io/github/contributors/aidos-lab/Diss-l-ECT)](https://github.com/aidos-lab/Diss-l-ECT/graphs/contributors)\n[![License](https://img.shields.io/github/license/aidos-lab/Diss-l-ECT)](/LICENSE.md)\n\n## Overview of local_ect.py\nThis module provides two primary functions for working with graph datasets, specifically leveraging **Local Euler Characteristic Transform (l-ECT)** and **XGBoost** for node classification tasks for featured graphs. The `compute_local_ect` function computes the ECT for local graph neighborhoods, and `xgb_model` uses the (l-ECT) information to train a machine learning model using **XGBoost**.\n\n### Dependencies\n- `torch`\n- `torch_geometric`\n- `numpy`\n- `matplotlib`\n- `sklearn`\n- `xgboost`\n\n### Dataset\nThe code is compatible with graph datasets from `torch_geometric`. It particularly supports node classification tasks using datasets like **WebKB**, but other datasets from `torch_geometric.datasets` can be used with minimal modifications.\n\n---\n\n## Function: `compute_local_ect`\n\n### Description:\nThis function computes the Local Euler Characteristic Transform (l-ECT) for each node in a graph dataset. The ECT captures structural information within a local neighborhood of a node up to a given radius (i.e., the number of hops). The result is a feature vector that encodes this local structure.\n\n### Parameters:\n- **`dataset`**: `torch_geometric` dataset  \n  The input graph dataset for which to compute the ECT. It should contain node features, edges, and labels.\n  \n- **`radius`**: `int`, default=1  \n  The number of hops to consider when extracting the local graph neighborhood for each node.\n  \n- **`ECT_TYPE`**: `str`, default='points'  \n  The type of structural information for the ECT calculation. Possible values are:\n  - `'points'`: Information about the nodes.\n  - `'edges'`: Information about the edges.\n\n- **`NUM_THETAS`**: `int`, default=64  \n  The dimensionality of the ECT approximation. The final ECT vector has dimensions `NUM_THETAS x NUM_THETAS`.\n\n- **`DEVICE`**: `str`, default='cpu'  \n  The device to be used for computation. Set it to `'cuda'` if GPU computation is needed.\n\n- **`subsample_size`**: `int`, default=None  \n  The number of randomly sampled nodes to compute the ECT for. If `None`, the ECT is computed for all nodes.\n\n### Returns:\n- **`ect`**: `torch.Tensor`  \n  A tensor of shape `(num_nodes, NUM_THETAS * NUM_THETAS)`, containing the ECT feature vectors for each node.\n\n### Example:\n```python\ndataset = WebKB(root='/tmp/Wisconsin', name='Wisconsin')\nect_features = compute_local_ect(dataset, radius=1, ECT_TYPE='points', NUM_THETAS=64)\n```\n\n---\n\n## Function: `xgb_model`\n\n### Description:\nThis function computes the local ECT features for a graph dataset and uses these features along with node attributes to train an XGBoost classifier. It supports evaluation using either accuracy or ROC AUC metrics.\n\n### Parameters:\n- **`dataset`**: `torch_geometric` dataset  \n  The input graph dataset, which should contain node features, edges, labels, and train/test masks.\n\n- **`radius1`**: `bool`, default=True  \n  Whether to compute ECT for 1-hop neighborhoods.\n\n- **`radius2`**: `bool`, default=True  \n  Whether to compute ECT for 2-hop neighborhoods.\n\n- **`ECT_TYPE`**: `str`, default='points'  \n  Type of structural information used for the ECT calculation. See `compute_local_ect` for details.\n\n- **`NUM_THETAS`**: `int`, default=64  \n  The dimensionality of the ECT approximation.\n\n- **`DEVICE`**: `str`, default='cpu'  \n  The device to be used for computation (`'cpu'` or `'cuda'`).\n\n- **`metric`**: `str`, default='accuracy'  \n  The metric for evaluating the classifier. Options:\n  - `'accuracy'`: Evaluates model performance using accuracy.\n  - `'roc'`: Evaluates model performance using ROC AUC score.\n\n- **`subsample_size`**: `int`, default=None  \n  The number of randomly sampled nodes to compute the ECT for. If `None`, the model is trained using all nodes.\n\n### Returns:\n- **`acc` or `roc`**: `float`  \n  The classification performance evaluated using the chosen metric.\n\n### Example:\n```python\ndataset = WebKB(root='/tmp/Wisconsin', name='Wisconsin')\naccuracy = xgb_model(dataset, radius1=True, radius2=False, ECT_TYPE='points', metric='accuracy')\n```\n\n---\n\n## Overview of rotation_invariant_metric.py\n\nThis module implements a rotation-invariant metric utilizing the ECT (Euler Characteristic Transform). It includes functionality for computing the ECT, defining a neural network model, and performing operations for spatial alignment of two data spaces.\n\n### Dependencies\n\nThis module requires the following libraries:\n\n- `torch`: The core PyTorch library for tensor operations and neural network functionalities.\n- `torch_geometric`: A library for geometric deep learning that extends PyTorch with tools for handling graph-structured data.\n- `geotorch`: A library for geometric deep learning and optimization on manifolds.\n- `sklearn`: For KDTree implementation to facilitate neighbor searches.\n\n### Constants\n\n- `dim`: Dimensionality of the input and output features (default is 768).\n- `in_size`: Input size, equal to `dim`.\n- `out_size`: Output size, equal to `dim`.\n- `DEVICE`: Device to run the computations, defaults to `'cpu'`.\n\n## Functions\n\n### `compute_ect(X, NUM_THETAS=64)`\n\nComputes the ECT transformation of the input tensor `X`.\n\n**Parameters:**\n- `X` (Tensor): The input tensor with features to be transformed.\n- `NUM_THETAS` (int): Number of theta values for the ECT layer (default is 64).\n\n**Returns:**\n- Tensor: The transformed tensor after applying the ECT layer.\n\n### `rotation_inv_distance(X, X_rot)`\n\nCalculates the rotation invariant distance between the input tensor `X` and its rotated version `X_rot` using the orthogonal model.\n\n**Parameters:**\n- `X` (Array-like): The original input data.\n- `X_rot` (Array-like): The rotated version of the input data.\n\n**Returns:**\n- Tuple: A tuple containing:\n  - The loss value as a tensor.\n  - The reconstructed input tensor after transformations.\n  - The weight matrix of the linear transformation.\n\n## Classes\n\n### `OrthogonalModel`\n\nA neural network model that applies an orthogonal transformation to input data.\n\n#### Methods\n\n- **`__init__()`**\n  Initializes the model with a linear layer. The weights of the layer are initialized to an identity matrix, and geometric constraints for orthogonality are applied.\n\n- **`forward(x)`**\n  Performs a forward pass through the model, applying the linear transformation and computing the ECT transformation.\n\n**Parameters:**\n- `x` (Tensor): Input tensor of shape `(batch_size, in_size)`.\n\n**Returns:**\n- Tensor: The output after applying the linear transformation and ECT layer.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faidos-lab%2Fdiss-l-ect","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faidos-lab%2Fdiss-l-ect","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faidos-lab%2Fdiss-l-ect/lists"}