diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml index 866e2c4f..68cd8c14 100644 --- a/.github/workflows/lint.yml +++ b/.github/workflows/lint.yml @@ -2,9 +2,9 @@ name: Linting on: push: - branches: [ main,github-actions-test ] + branches: [main, github-actions-test] pull_request: - branches: [ main ] + branches: [main] jobs: ruff: diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index cd29197b..cee71457 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -2,24 +2,22 @@ name: "Test" on: push: - branches: [main,github-actions-test] + branches: [main, github-actions-test] paths-ignore: - - 'docs/**' - - 'README.md' - - 'LICENSE.txt' - - '.gitignore' + - "docs/**" + - "README.md" + - "LICENSE.txt" + - ".gitignore" pull_request: branches: [main] paths-ignore: - - 'docs/**' - - 'README.md' - - 'LICENSE.txt' - - '.gitignore' - + - "docs/**" + - "README.md" + - "LICENSE.txt" + - ".gitignore" jobs: - build: runs-on: ${{ matrix.os }} diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 647ab3af..fc81ff80 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -1,6 +1,3 @@ -default_language_version: - python: python3.10 - repos: - repo: https://github.com/pre-commit/pre-commit-hooks rev: v4.0.1 @@ -16,24 +13,35 @@ repos: args: - --maxkb=2048 - id: trailing-whitespace - - id: requirements-txt-fixer - repo: https://github.com/astral-sh/ruff-pre-commit rev: v0.1.14 hooks: - id: ruff - types_or: [ python, pyi, jupyter ] - args: [ --fix ] + types_or: [python, pyi, jupyter] + args: ["--fix", "--show-fixes"] - id: ruff-format - types_or: [ python, pyi, jupyter ] + types_or: [python, pyi, jupyter] - - repo: https://github.com/asottile/blacken-docs - rev: v1.12.0 + - repo: https://github.com/adamchainz/blacken-docs + rev: "1.16.0" hooks: - id: blacken-docs - additional_dependencies: [ black==20.8b0 ] + additional_dependencies: [black==24.*] - repo: https://github.com/numpy/numpydoc rev: v1.6.0 hooks: - id: numpydoc-validation + + - repo: https://github.com/pre-commit/mirrors-prettier + rev: "v3.1.0" + hooks: + - id: prettier + + - repo: https://github.com/pre-commit/pygrep-hooks + rev: "v1.10.0" + hooks: + - id: rst-backticks + - id: rst-directive-colons + - id: rst-inline-touching-normal diff --git a/README.md b/README.md index f196a6d5..452d3de9 100644 --- a/README.md +++ b/README.md @@ -29,15 +29,11 @@ - - - - ![toponetx](https://user-images.githubusercontent.com/8267869/234068354-af9480f1-1d18-4914-92f1-916d9093e44d.png) Many complex systems, ranging from socio-economic systems such as social networks, over to biological systems (e.g., proteins) and technical systems can be abstracted as a set of entities with are linked to each other via a set of relations. For instance, a social network may be abstracted as a set vertices corresponding to people linked via various social interactions, including pairwise relationships such as friendships and higher-order relationships involving multiple people. -This *relational data* can be abstracted as a topological domain such as a graph, hypergraph, simplicial, cellular path or combinatorial complex, which enables the principled analysis of such data. +This _relational data_ can be abstracted as a topological domain such as a graph, hypergraph, simplicial, cellular path or combinatorial complex, which enables the principled analysis of such data. `TopoNetX` provides a unified platform to compute with such relational data. @@ -73,32 +69,39 @@ TNX is developed by the [pyt-team](https://github.com/pyt-team) 1. Dynamic construction of cell, simplicial and combinatorial complexes, allowing users to add or remove objects from these structures after their initial creation. 2. Compatibility with the [`NetworkX`](https://networkx.org/) and [`gudhi`](https://gudhi.inria.fr/) packages, enabling users to -leverage the powerful algorithms and data structures provided by these packages. + leverage the powerful algorithms and data structures provided by these packages. 3. Support for attaching arbitrary attributes and data to cells, simplices and other entities in a complex, allowing users to store and manipulate a versatile range of information about these objects. 4. Computation of boundary operators, Hodge Laplacians and higher-order adjacency -operators on a complex, enabling users to study the topological properties of the space. + operators on a complex, enabling users to study the topological properties of the space. 5. Robust error handling and validation of input data, ensuring that the package is -reliable and easy to use. + reliable and easy to use. 6. Package dependencies are kept to a minimum, -to facilitate easy installation and -to reduce future installation issues arising from such dependencies. + to facilitate easy installation and + to reduce future installation issues arising from such dependencies. # 🤖 Installing TopoNetX 1. Clone a copy of `TopoNetX` from source: + ```bash git clone https://github.com/pyt-team/TopoNetX cd TopoNetX ``` + 2. If you have already cloned `TopoNetX` from source, update it: + ```bash git pull ``` + 3. Install `TopoNetX` in editable mode (requires pip ≥ 21.3 for [PEP 660](https://peps.python.org/pep-0610/) support): + ```bash pip install -e '.[all]' ``` + 4. Install pre-commit hooks: + ```bash pre-commit install ``` @@ -158,11 +161,12 @@ B02 = cc.incidence_matrix(0, 2) B03 = cc.incidence_matrix(0, 3) ``` -## 🔍 References ## +## 🔍 References To learn more about topological domains, and how they can be used in deep learning: - Mustafa Hajij, Ghada Zamzmi, Theodore Papamarkou, Nina Miolane, Aldo Guzmán-Sáenz, Karthikeyan Natesan Ramamurthy, Tolga Birdal, Tamal K. Dey, Soham Mukherjee, Shreyas N. Samaga, Neal Livesay, Robin Walters, Paul Rosen, Michael T. Schaub. [Topological Deep Learning: Going Beyond Graph Data](https://arxiv.org/abs/2206.00606). + ``` @misc{hajij2023topological, title={Topological Deep Learning: Going Beyond Graph Data}, @@ -173,7 +177,9 @@ To learn more about topological domains, and how they can be used in deep learni primaryClass={cs.LG} } ``` + - Mathilde Papillon, Sophia Sanborn, Mustafa Hajij, Nina Miolane. [Architectures of Topological Deep Learning: A Survey on Topological Neural Networks.](https://arxiv.org/pdf/2304.10031.pdf) + ``` @misc{papillon2023architectures, title={Architectures of Topological Deep Learning: A Survey on Topological Neural Networks}, @@ -190,6 +196,7 @@ To learn more about topological domains, and how they can be used in deep learni `TopoNetX` has been built with the help of several open-source packages. All of these are listed in setup.py. Some of these packages include: + - [`NetworkX`](https://networkx.org/) - [`HyperNetX`](https://pnnl.github.io/HyperNetX/) - [`gudhi`](https://gudhi.inria.fr/python/latest/) @@ -199,4 +206,4 @@ Some of these packages include: -Partially funded by the European Union (ERC, HIGH-HOPeS, 101039827). Views and opinions expressed are however those of the author(s) only and do not necessarily reflect those of the European Union or the European Research Council Executive Agency. Neither the European Union nor the granting authority can be held responsible for them. \ No newline at end of file +Partially funded by the European Union (ERC, HIGH-HOPeS, 101039827). Views and opinions expressed are however those of the author(s) only and do not necessarily reflect those of the European Union or the European Research Council Executive Agency. Neither the European Union nor the granting authority can be held responsible for them. diff --git a/codecov.yml b/codecov.yml index 85ba6f8b..08e6a00d 100644 --- a/codecov.yml +++ b/codecov.yml @@ -4,4 +4,4 @@ coverage: round: down precision: 2 ignore: - - "test/" \ No newline at end of file + - "test/" diff --git a/docs/api/index.rst b/docs/api/index.rst index 29b1c725..ce5ac0b6 100644 --- a/docs/api/index.rst +++ b/docs/api/index.rst @@ -2,14 +2,14 @@ API Reference ============= -The API reference gives an overview of `TopoNetX`, which consists of several modules: +The API reference gives an overview of ``TopoNetX``, which consists of several modules: -- `classes` implements the topological domains: simplicial complexes, cellular complexes, combinatorial complexes. -- `algorithms` implements signal processing techniques on topological domains, such as the eigendecomposition of a laplacian. -- `datasets` implements utilities to load small datasets on topological domains. -- `transform` implements functions to transform the topological domain that supports a dataset, effectively "lifting" the dataset onto another domain. -- `generators` implements functions to generate random topological domains. -- `transform` implements functions to convert a graph to a topological domain: simplicial complexes etc. +- ``classes`` implements the topological domains: simplicial complexes, cellular complexes, combinatorial complexes. +- ``algorithms`` implements signal processing techniques on topological domains, such as the eigendecomposition of a laplacian. +- ``datasets`` implements utilities to load small datasets on topological domains. +- ``transform`` implements functions to transform the topological domain that supports a dataset, effectively "lifting" the dataset onto another domain. +- ``generators`` implements functions to generate random topological domains. +- ``transform`` implements functions to convert a graph to a topological domain: simplicial complexes etc. .. toctree:: diff --git a/docs/contributing/index.rst b/docs/contributing/index.rst index a3ca021d..fb670b53 100644 --- a/docs/contributing/index.rst +++ b/docs/contributing/index.rst @@ -40,7 +40,7 @@ Follow these steps before submitting a PR: $ git add $ git commit -m "Add my feature" - to record your changes. Then push the changes to your fork of `TopoNextX` with: + to record your changes. Then push the changes to your fork of ``TopoNetX`` with: .. code-block:: bash @@ -54,9 +54,9 @@ Follow these steps before submitting a PR: Write Tests ----------- -The tests consist of classes appropriately named, located in the `test` folder, that check the validity of the code. +The tests consist of classes appropriately named, located in the ``test`` folder, that check the validity of the code. -Test functions should be located in files whose filenames start with `test_`. For example: +Test functions should be located in files whose filenames start with ``test_``. For example: .. code-block:: bash @@ -68,12 +68,12 @@ Test functions should be located in files whose filenames start with `test_`. Fo def test_capital_case(): assert add(4, 5) == 9 -Use an `assert` statement to check that the function under test returns the correct output. +Use an ``assert`` statement to check that the function under test returns the correct output. Run Tests ~~~~~~~~~ -Install `pytest` which is the software tools used to run tests: +Install ``pytest`` which is the software tools used to run tests: .. code-block:: bash @@ -85,7 +85,7 @@ Then run the test using: $ pytest test_add.py -Verify that the code you have added does not break `TopoNetX` by running all the tests. +Verify that the code you have added does not break ``TopoNetX`` by running all the tests. .. code-block:: bash diff --git a/docs/index.rst b/docs/index.rst index 2f63e2d6..5b8d9653 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,7 +1,7 @@ 🌐 TopoNetX (TNX) 🍩 ==================== -`TopoNetX` is a Python package for computing on topological domains. Topological domains are the natural mathematical structures representing relations between the components of a dataset. +``TopoNetX`` is a Python package for computing on topological domains. Topological domains are the natural mathematical structures representing relations between the components of a dataset. .. figure:: https://user-images.githubusercontent.com/8267869/234068354-af9480f1-1d18-4914-92f1-916d9093e44d.png :alt: natural shapes @@ -11,22 +11,22 @@ Many natural systems as diverse as social networks and proteins are characterized by relational structure. This is the structure of interactions between components in the system, such as social interactions between individuals or electrostatic interactions between atoms. -`TopoNetX` provides a unifying interface to compute with such relational data. +``TopoNetX`` provides a unifying interface to compute with such relational data. 🎯 Scope and functionality -------------------------- -`TopoNetX` (TNX) is a package for computing with topological domains and studying their properties. +``TopoNetX`` (TNX) is a package for computing with topological domains and studying their properties. With its dynamic construction capabilities and support for arbitrary -attributes and data, `TopoNetX` allows users to easily explore the topological structure +attributes and data, ``TopoNetX`` allows users to easily explore the topological structure of their data and gain insights into its underlying geometric and algebraic properties. Available functionality ranges from computing boundary operators and Hodge Laplacians on simplicial/cell/combinatorial complexes to performing higher-order adjacency calculations. -TNX is similar to `NetworkX`, a popular graph package, and extends its capabilities to support a +TNX is similar to ``NetworkX``, a popular graph package, and extends its capabilities to support a wider range of mathematical structures, including cell complexes, simplicial complexes and combinatorial complexes. @@ -35,7 +35,7 @@ found in higher-order networks such as simplicial, cellular, CW and combinatoria This package serves as a repository of the methods and algorithms we find most useful as we explore the knowledge that can be encoded via higher-order networks. -TNX supports the construction of topological structures including the `CellComplex`, `SimplicialComplex` and `CombinatorialComplex` classes. +TNX supports the construction of topological structures including the ``CellComplex``, ``SimplicialComplex`` and ``CombinatorialComplex`` classes. These classes provide methods for computing boundary operators, Hodge Laplacians and higher-order adjacency operators on cell, simplicial and combinatorial complexes, @@ -49,7 +49,7 @@ TNX was developed by the pyt-team. 1. Dynamic construction of cell, simplicial and combinatorial complexes, allowing users to add or remove objects from these structures after their initial creation. -2. Compatibility with the `NetworkX` and `gudhi` packages, enabling users to leverage the powerful algorithms and data structures provided by these packages. +2. Compatibility with the ``NetworkX`` and ``gudhi`` packages, enabling users to leverage the powerful algorithms and data structures provided by these packages. 3. Support for attaching arbitrary attributes and data to cells, simplices and other entities in a complex, allowing users to store and manipulate a versatile range of information about these objects. diff --git a/tutorials/README.md b/tutorials/README.md index 6fa373f8..d543cdd5 100644 --- a/tutorials/README.md +++ b/tutorials/README.md @@ -1,3 +1,3 @@ # Tutorials -Run these tutorials to get started with toponetx. \ No newline at end of file +Run these tutorials to get started with toponetx.