Skip to content

Commit

Permalink
Readme update
Browse files Browse the repository at this point in the history
  • Loading branch information
@gbg141
gbg141 committed Jun 3, 2024
1 parent 64a8a60 commit 3011042
Showing 1 changed file with 72 additions and 68 deletions.
140 changes: 72 additions & 68 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,27 +22,30 @@ Assess how your model compares against state-of-the-art topological neural netwo
</div>

<p align="center">
<a href="#overview">Overview</a> •
<a href="#toolbox-get-started">Get Started</a> •
<a href="#pushpin-overview">Overview</a> •
<a href="#jigsaw-get-started">Get Started</a> •
<a href="https://github.com/pyt-team/TopoBenchmarkX/tree/dev/tutorials">Tutorials</a> •
<a href="#spiral_notepad-references">References</a>
<a href="#gear-neural-networks">Neural Networks</a> •
<a href="#arrows-clockwise-liftings">Liftings</a> •
<a href="#books-datasets">Datasets</a> •
<a href="#mag-right-references">References</a>
</p>


<p align="center">
<img src="resources/workflow.jpeg" width="700">
</p>


## Overview
## :pushpin: Overview

`TopoBenchmarkX` (TBX) is a Python library developed to train and compare the performances of topological neural networks using different topological domains. Here, a _topological domain_ means a graph, a simplicial complex, a cellular complex, or a hypergraph.

<p align="center">
<img src="resources/workflow.jpeg" width="700">
</p>

The main pipeline trains and evaluates a wide range of state-of-the-art neural networks (see [:gear: Neural Networks](https://github.com/pyt-team/TopoBenchmarkX/blob/ninamiolane-readme/README.md#gear-neural-networks)) on numerous and varied datasets and benchmark tasks.

Additionally, the library offers the ability to transform, i.e., _lift_, each dataset from one topological domain to another (see [:top: Liftings](https://github.com/pyt-team/TopoBenchmarkX/blob/ninamiolane-readme/README.md#top-liftings)).
Additionally, the library offers the ability to transform, i.e., _lift_, each dataset from one topological domain to another (see [:arrows_clockwise: Liftings](https://github.com/pyt-team/TopoBenchmarkX/blob/ninamiolane-readme/README.md#top-liftings)).

## :toolbox: Get Started
## :jigsaw: Get Started

### Create Environment

Expand Down Expand Up @@ -84,58 +87,6 @@ To add a new dataset and benchmark task, you can explore our [tutorials](https:/
## :gear: Neural Networks

We list the neural networks trained and evaluated by `TopoBenchmarkX`, organized by the topological domain over which they operate: graph, simplicial complex, cellular complex or hypergraph. Many of these neural networks were originally implemented in [`TopoModelX`](https://github.com/pyt-team/TopoModelX).
## Additional details on project
<details>
<summary><b>Hierarchy of configuration files</b></summary>

```
├── configs <- Hydra configs
│ ├── callbacks <- Callbacks configs
│ ├── dataset <- Dataset configs
│ │ ├── graph <- Graph dataset configs
│ │ ├── hypergraph <- Hypergraph dataset configs
│ │ └── simplicial <- Simplicial dataset configs
│ ├── debug <- Debugging configs
│ ├── evaluator <- Evaluator configs
│ ├── experiment <- Experiment configs
│ ├── extras <- Extra utilities configs
│ ├── hparams_search <- Hyperparameter search configs
│ ├── hydra <- Hydra configs
│ ├── local <- Local configs
│ ├── logger <- Logger configs
│ ├── loss <- Loss function configs
│ ├── model <- Model configs
│ │ ├── cell <- Cell model configs
│ │ ├── graph <- Graph model configs
│ │ ├── hypergraph <- Hypergraph model configs
│ │ └── simplicial <- Simplicial model configs
│ ├── optimizer <- Optimizer configs
│ ├── paths <- Project paths configs
│ ├── scheduler <- Scheduler configs
│ ├── trainer <- Trainer configs
│ ├── transforms <- Data transformation configs
│ │ ├── data_manipulations <- Data manipulation transforms
│ │ ├── dataset_defaults <- Default dataset transforms
│ │ ├── feature_liftings <- Feature lifting transforms
│ │ └── liftings <- Lifting transforms
│ │ ├── graph2cell <- Graph to cell lifting transforms
│ │ ├── graph2hypergraph <- Graph to hypergraph lifting transforms
│ │ ├── graph2simplicial <- Graph to simplicial lifting transforms
│ │ ├── graph2cell_default.yaml <- Default graph to cell lifting config
│ │ ├── graph2hypergraph_default.yaml <- Default graph to hypergraph lifting config
│ │ ├── graph2simplicial_default.yaml <- Default graph to simplicial lifting config
│ │ ├── no_lifting.yaml <- No lifting config
│ │ ├── custom_example.yaml <- Custom example transform config
│ │ └── no_transform.yaml <- No transform config
│ ├── wandb_sweep <- Weights & Biases sweep configs
│ │
│ ├── __init__.py <- Init file for configs module
│ └── run.yaml <- Main config for training
```


</details>



### Graphs
Expand Down Expand Up @@ -170,7 +121,7 @@ We list the neural networks trained and evaluated by `TopoBenchmarkX`, organized
| UniGNN | [UniGNN: a Unified Framework for Graph and Hypergraph Neural Networks](https://arxiv.org/pdf/2105.00956) |
| UniGNN2 | [UniGNN: a Unified Framework for Graph and Hypergraph Neural Networks](https://arxiv.org/pdf/2105.00956) |

## :top: Liftings
## :arrows_clockwise: Liftings

We list the liftings used in `TopoBenchmarkX` to transform datasets. Here, a _lifting_ refers to a function that transforms a dataset defined on a topological domain (_e.g._, on a graph) into the same dataset but supported on a different topological domain (_e.g._, on a simplicial complex).

Expand Down Expand Up @@ -212,18 +163,18 @@ We list the liftings used in `TopoBenchmarkX` to transform datasets. Here, a _li
| US-county-demos | Regression | In turn each node attribute is used as the target label. | [Source](https://arxiv.org/pdf/2002.08274) |
| ZINC | Regression | Graph-level regression. | [Source](https://pubs.acs.org/doi/10.1021/ci3001277) |

## :keyboard: Development
## :hammer_and_wrench: Development

To join the development of `TopoBenchmarkX`, you should install the library in dev mode.

For this, you can create an environment using either conda or docker. Both options are detailed below.

### Using Conda Environment
### :snake: Using Conda Environment

Follow the steps in [:toolbox: Get Started](https://github.com/pyt-team/TopoBenchmarkX/blob/ninamiolane-readme/README.md##toolbox-get-started).
Follow the steps in [:jigsaw: Get Started](https://github.com/pyt-team/TopoBenchmarkX/blob/ninamiolane-readme/README.md##toolbox-get-started).


### Using Docker
### :whale: Using Docker

For ease of use, TopoBenchmarkX employs <img src="https://github.com/wesbos/Font-Awesome-Docker-Icon/blob/master/docker-white.svg" width="20" height="20"> [Docker](https://www.docker.com/). To set it up on your system you can follow [their guide](https://docs.docker.com/get-docker/). once installed, please follow the next steps:

Expand Down Expand Up @@ -253,7 +204,7 @@ docker run -it -d --volume $(pwd):/TopoBenchmarkX topobenchmarkx:new
Happy development!


## 🔍 References ##
## :mag_right: References ##

To learn more about `TopoBenchmarkX`, we invite you to read the paper:

Expand All @@ -278,3 +229,56 @@ To learn more about `TopoBenchmarkX`, we invite you to read the paper:
</details>

If you find `TopoBenchmarkX` useful, we would appreciate if you cite it!


## :mouse: Additional details about the project
<details>
<summary><b>Hierarchy of configuration files</b></summary>

```
├── configs <- Hydra configs
│ ├── callbacks <- Callbacks configs
│ ├── dataset <- Dataset configs
│ │ ├── graph <- Graph dataset configs
│ │ ├── hypergraph <- Hypergraph dataset configs
│ │ └── simplicial <- Simplicial dataset configs
│ ├── debug <- Debugging configs
│ ├── evaluator <- Evaluator configs
│ ├── experiment <- Experiment configs
│ ├── extras <- Extra utilities configs
│ ├── hparams_search <- Hyperparameter search configs
│ ├── hydra <- Hydra configs
│ ├── local <- Local configs
│ ├── logger <- Logger configs
│ ├── loss <- Loss function configs
│ ├── model <- Model configs
│ │ ├── cell <- Cell model configs
│ │ ├── graph <- Graph model configs
│ │ ├── hypergraph <- Hypergraph model configs
│ │ └── simplicial <- Simplicial model configs
│ ├── optimizer <- Optimizer configs
│ ├── paths <- Project paths configs
│ ├── scheduler <- Scheduler configs
│ ├── trainer <- Trainer configs
│ ├── transforms <- Data transformation configs
│ │ ├── data_manipulations <- Data manipulation transforms
│ │ ├── dataset_defaults <- Default dataset transforms
│ │ ├── feature_liftings <- Feature lifting transforms
│ │ └── liftings <- Lifting transforms
│ │ ├── graph2cell <- Graph to cell lifting transforms
│ │ ├── graph2hypergraph <- Graph to hypergraph lifting transforms
│ │ ├── graph2simplicial <- Graph to simplicial lifting transforms
│ │ ├── graph2cell_default.yaml <- Default graph to cell lifting config
│ │ ├── graph2hypergraph_default.yaml <- Default graph to hypergraph lifting config
│ │ ├── graph2simplicial_default.yaml <- Default graph to simplicial lifting config
│ │ ├── no_lifting.yaml <- No lifting config
│ │ ├── custom_example.yaml <- Custom example transform config
│ │ └── no_transform.yaml <- No transform config
│ ├── wandb_sweep <- Weights & Biases sweep configs
│ │
│ ├── __init__.py <- Init file for configs module
│ └── run.yaml <- Main config for training
```


</details>

0 comments on commit 3011042

Please sign in to comment.