Metadata-Version: 2.4
Name: xgi
Version: 1.0.0
Summary: XGI is a Python package for higher-order networks.
Author-email: XGI Developers <nicholas.landry@virginia.edu>
Maintainer-email: XGI Developers <nicholas.landry@virginia.edu>
License: XGI is distributed with the 3-clause BSD license.
        
        Copyright (C) 2021-2025, XGI Developers
        
        All rights reserved.
        
        Redistribution and use in source and binary forms, with or without
        modification, are permitted provided that the following conditions are
        met:
        
        * Redistributions of source code must retain the above copyright
               notice, this list of conditions and the following disclaimer.
        
        * Redistributions in binary form must reproduce the above
               copyright notice, this list of conditions and the following
               disclaimer in the documentation and/or other materials provided
               with the distribution.
        
        * Neither the names of the XGI Developers nor the names of its
               contributors may be used to endorse or promote products derived
               from this software without specific prior written permission.
        
        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
        "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
        LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
        A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
        OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
        SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
        LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
        DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
        THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
        (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
        OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
        
        
        ---------------------------------
        
        License
        
        Tensor methods for nonuniform hypergraphs
        
        * Tensor methods functionality for the CompleX Group Interactions library
        
        Copyright 2023, 2024 Battelle Memorial Institute
        
        Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
        
        1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
        
        2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
        
        3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
        
        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Project-URL: Documentation, https://xgi.readthedocs.io/en/stable/
Project-URL: Bug Reports, https://github.com/xgi-org/xgi/issues
Project-URL: Source, https://github.com/xgi-org/xgi
Project-URL: PyPI, https://pypi.org/project/xgi/
Project-URL: GitHub Discussions, https://github.com/xgi-org/xgi/discussions
Keywords: networks,higher-order,higher-order network,hypergraph,simplicial complex,network science
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: <3.15,>=3.11
Description-Content-Type: text/markdown
License-File: LICENSE.md
Requires-Dist: numpy>=1.23.5
Requires-Dist: scipy>=1.15
Requires-Dist: pandas>=1.3
Requires-Dist: networkx>=2.7
Requires-Dist: requests>=2.0
Requires-Dist: matplotlib>=3.4
Requires-Dist: xopen>=2.0
Provides-Extra: benchmark
Requires-Dist: pytest>=7.2; extra == "benchmark"
Requires-Dist: pytest-benchmark>=5.0; extra == "benchmark"
Provides-Extra: developer
Requires-Dist: black[jupyter]>=24.3; extra == "developer"
Requires-Dist: isort==5.10.1; extra == "developer"
Requires-Dist: pylint>=3.0; extra == "developer"
Requires-Dist: nbqa; extra == "developer"
Provides-Extra: docs
Requires-Dist: sphinx~=6.0; extra == "docs"
Requires-Dist: sphinx_copybutton; extra == "docs"
Requires-Dist: sphinx-rtd-theme>=1.2; extra == "docs"
Requires-Dist: numpydoc>=1.1; extra == "docs"
Requires-Dist: pillow>=8.2; extra == "docs"
Requires-Dist: matplotlib>=3.3; extra == "docs"
Requires-Dist: sphinx-design; extra == "docs"
Requires-Dist: ipykernel; extra == "docs"
Requires-Dist: nbsphinx; extra == "docs"
Requires-Dist: nbsphinx-link; extra == "docs"
Requires-Dist: pydata-sphinx-theme; extra == "docs"
Requires-Dist: sphinx-gallery; extra == "docs"
Requires-Dist: pyyaml; extra == "docs"
Provides-Extra: release
Requires-Dist: twine>=3.4; extra == "release"
Requires-Dist: build>=1.2.1; extra == "release"
Requires-Dist: wheel>=0.36; extra == "release"
Provides-Extra: test
Requires-Dist: pytest>=7.2; extra == "test"
Requires-Dist: pytest-cov>=4.0; extra == "test"
Requires-Dist: tuna; extra == "test"
Provides-Extra: tutorial
Requires-Dist: jupyter>=1.0; extra == "tutorial"
Requires-Dist: ipython<=8.12.0; extra == "tutorial"
Requires-Dist: seaborn>=0.10; extra == "tutorial"
Provides-Extra: all
Requires-Dist: xgi[benchmark,developer,docs,release,test,tutorial]; extra == "all"
Dynamic: license-file

<p align="center"><img src="https://raw.githubusercontent.com/xgi-org/xgi/main/logo/logo.svg" alt="XGI" width="35%"></img></p>

[![PyPI](https://img.shields.io/pypi/v/xgi?color=forest)](https://pypi.org/project/xgi/) [![Python versions](https://img.shields.io/pypi/pyversions/xgi?color=forest)](https://pypi.org/project/xgi/) [![Test Status](https://github.com/xgi-org/xgi/actions/workflows/test-code.yml/badge.svg)](https://github.com/xgi-org/xgi/actions/workflows/test-code.yml) [![codecov](https://codecov.io/gh/xgi-org/xgi/branch/main/graph/badge.svg?token=BI6TX2WDSG)](https://codecov.io/gh/xgi-org/xgi) [![DOI](https://joss.theoj.org/papers/10.21105/joss.05162/status.svg)](https://doi.org/10.21105/joss.05162) [![pyOpenSci](https://tinyurl.com/y22nb8up)](https://github.com/pyOpenSci/software-review/issues/115) [![Good First Issue](https://img.shields.io/badge/contribute-Good%20First%20Issue-forest)](https://github.com/xgi-org/xgi/issues?q=is%3Aopen+is%3Aissue+label%3A%22Good+First+Issue%22) [![Benchmarks](https://img.shields.io/badge/benchmarks-forest)](https://xgi-org.github.io/xgi/dev/bench/)

Comple**X** **G**roup **I**nteractions (**XGI**) is a Python package for modeling, analyzing, and visualizing [higher-order networks](https://xgi.readthedocs.io/en/stable/higher-order.html): hypergraphs, directed hypergraphs, and simplicial complexes. It covers the whole workflow, from start to finish, with data structures, generative models, measures, datasets, and drawing tools.

<p align="center"><a href="https://xgi.readthedocs.io">Documentation</a> · <a href="https://xgi.readthedocs.io/en/stable/user_guides.html">Tutorials</a> · <a href="https://xgi.readthedocs.io/en/stable/auto_examples/index.html">Gallery</a> · <a href="https://xgi.readthedocs.io/en/stable/xgi-data.html">Datasets</a> · <a href="https://xgi.readthedocs.io/en/stable/using_xgi.html">Projects using XGI</a> · <a href="https://xgi.readthedocs.io/en/stable/contribute.html">Contribute</a></p>

## Install

```sh
pip install xgi
```

For other options (development version, optional dependencies), see the [installation guide](https://xgi.readthedocs.io/en/stable/installing.html).

## Getting started

To get started, take a look at the [tutorials](https://xgi.readthedocs.io/en/stable/user_guides.html) illustrating the library's basic functionality.

An example:

```python
import xgi

# build
hyperedges = [[1, 2, 3], [3, 4, 5], [3, 6], [6, 7, 8, 9], [1, 4, 10, 11, 12], [1, 4]]
H = xgi.Hypergraph(hyperedges)

# analyze
H.edges.size.asnumpy()          # array([3, 3, 2, 4, 5, 2])
H.nodes.filterby("degree", 3)   # nodes 1, 3, 4

# visualize
pos = xgi.barycenter_spring_layout(H, seed=1)
xgi.draw(H, pos=pos)
```

<p align="center"><img src="docs/source/_static/readme_example.png" alt="Drawing of the example hypergraph" width="300"></img></p>

## XGI-DATA

[XGI-DATA](https://xgi.readthedocs.io/en/stable/xgi-data.html) is a curated collection of 50+ real-world higher-order datasets (from face-to-face contacts and emails to coauthorships, legislation, and ecology), which can be loaded in one line with `xgi.load_xgi_data()`.

## Contribute

Contributions of any size are welcome, and we're happy to help! To report a bug or request a feature, [open an issue](https://github.com/xgi-org/xgi/issues/new). For more, see the [contributing guide](https://xgi.readthedocs.io/en/stable/contribute.html).

Join the community on [Zulip](https://xgi.zulipchat.com/join/7agfwo7dh7jo56ppnk5kc23r/) and follow XGI on [Bluesky](https://bsky.app/profile/xgi.bsky.social).

## Cite

We believe that quality software is important for supporting research. To demonstrate the value of XGI, we ask that you cite the XGI [paper](https://doi.org/10.21105/joss.05162) in your work. You can also use the "Cite this repository" button on GitHub.

> Landry, N. W., Lucas, M., Iacopini, I., Petri, G., Schwarze, A., Patania, A., & Torres, L. (2023). XGI: A Python package for higher-order interaction networks. *Journal of Open Source Software*, 8(85), 5162.

<details>
<summary>BibTeX</summary>

```bibtex
@article{Landry_XGI_2023,
    author = {Landry, Nicholas W. and Lucas, Maxime and Iacopini, Iacopo and Petri, Giovanni and Schwarze, Alice and Patania, Alice and Torres, Leo},
    title = {{XGI: A Python package for higher-order interaction networks}},
    doi = {10.21105/joss.05162},
    journal = {Journal of Open Source Software},
    publisher = {The Open Journal},
    year = {2023},
    month = may,
    volume = {8},
    number = {85},
    pages = {5162},
    url = {https://doi.org/10.21105/joss.05162},
}
```
</details>

## License

Released under the [3-Clause BSD license](https://github.com/xgi-org/xgi/blob/main/LICENSE.md).

## Support

<a href="https://www.nsf.gov"><img src="docs/source/_static/nsf-logo.svg" alt="NSF" height=50 align="middle"></img></a> &nbsp; <a href="https://zulip.com"><img src="docs/source/_static/zulip-org-logo.svg" alt="Zulip" height=30 align="middle"></img></a>

See details [here](https://github.com/xgi-org/xgi/blob/main/SUPPORT.md).

Looking for something else? See this [list of other higher-order network software](https://github.com/xgi-org/xgi/blob/main/OTHER_RESOURCES.md).
