CompleX Group Interactions (XGI) provides an ecosystem for the analysis and representation of complex systems with group interactions.

Last update: Dec 28, 2022

Related tags

Overview

XGI

CompleX Group Interactions (XGI) is a Python package for the representation, manipulation, and study of the structure, dynamics, and functions of complex systems with group (higher-order) interactions.

Installation

XGI runs on Python 3.7 or higher.

To install the latest version of XGI, run the following command:

pip install xgi

To install this package locally:

Clone this repository
Navigate to the folder on your local machine
Run the following command:

pip install -e .["all"]

If that command does not work, you may try the following instead

pip install -e .\[all\]

Getting Started

To get started, take a look at the tutorials illustrating the library's basic functionality.

Documentation

For more documentation, see our Read The Docs page.

Contributing

Contributions are always welcome. Please report any bugs that you find here. Or, even better, fork the repository on GitHub and create a pull request (PR). We welcome all changes, big or small, and we will help you make the PR if you are new to git (just ask on the issue and/or see our contributing guidelines).

How to Cite

We acknowledge the importance of good software to support research, and we note that research becomes more valuable when it is communicated effectively. To demonstrate the value of XGI, we ask that you cite XGI in your work. Currently, the best way to cite XGI is to go to our repository page (if you haven't already) and click the "cite this repository" button on the right sidebar. This will generate a citation in your preferred format, and will also integrate well with citation managers.

Code of Conduct

Our full code of conduct, and how we enforce it, can be read in our repository.

License

Released under the 3-Clause BSD license (see LICENSE.md)

Nicholas Landry [email protected]

Leo Torres [email protected]

Iacopo Iacopini [email protected]

Maxime Lucas [email protected]

Giovanni Petri [email protected]

Alice Patania [email protected]

The XGI library has copied or modified code from the HyperNetX and NetworkX libraries, the licenses of which can be found in our license file

Funding

The XGI package has been supported by NSF Grant 2121905, "HNDS-I: Using Hypergraphs to Study Spreading Processes in Complex Social Networks".

Other resources

This library may not meet your needs and if this is this case, consider checking out these other resources:

HyperNetX: A package in Python for representing, analyzing, and visualizing hypergraphs.
SimpleHypergraphs.jl: A package in Julia for representing, analyzing, and generating hypergraphs.
hyperG: A package in R for storing and analyzing hypergraphs
NetworkX: A package in Python for representing, analyzing, and visualizing networks.

Comments

Interface of NodeView
NodeView supports accessing the edge ids that contain a node in three different ways:

H = some_hypergraph() H.nodes[1] == H.nodes(1) == H.members(1) # -> True

I find this unpythonic. I'd much rather there was a single way of doing things if at all possible. If there was exactly one way of accessing the edges that contain a node, which would you prefer? If anyone can argue that we should support two (or more) ways of doing the same thing, I'm all ears.

Related to #20.
opened by leotrs 21
Fix #224 uid counter initialisation
fixed #224 counter initialisation in add_edges_from and add_simplices_from

fixed H.copy() so that it does not throw an error for string IDs

added tests for all
opened by maximelucas 10
Compress edges
Implement way of collapsing identical elements. Right now, IDView.duplicates() simply chooses the lowest ID as the non-duplicate edge, but there are several ways of

weighting the collapsed nodes/edges:

Leave the resulting single node/edge unweighted

Weighting the resulting single node/edge by its original multiplicity

labeling the node/edge:

Give the new node/edge the smallest id of the duplicates

Give the new node/edge a tuple ID where the tuple are the nodes/edges that were compressed.

Give the new node/edge a completely new ID This would affect the duplicates method and potentially require another method.

Something along these lines is the collapse_identical_elements in HyperNetX.
opened by nwlandry 10
Add function to get list of edges (not edge ids)
Currently,

H.edges # EdgeView([3, 2, 4, 9])

outputs edge ids, not edges as list of member nodes. It's often useful to access edges as list of member nodes. One current way is list(H._edge.values()) but it's long and hidden.

Should we have a two views?

EdgeIdView (to replace current EdgeView): for ids

H.edges_id # EdgeIdView([3, 2, 4, 9])

EdgeView:for list of member nodes

H.edges # EdgeView([[0], [3, 4], [4], [4]])
opened by maximelucas 10
Add node and hyperedge labels in the plotting functions
Update the old docstrings.

Added the functions draw_node_labels and draw_hyperedge_labels.

Updated Tutorial 5 - Plotting.ipynb to show the new functionalities. I also added an example to show how to plot a hypergraph with only hyperedges of a certain order.

So far the labels can be only dict. Thus, we should implement the .items() function for NodeStat and EdgeStat.

So far, the hyperedges labels are only drawn for Hypergraph and not for SimplicialComplex. Could you please give me some feedback whether it would make sense to add this functionality for SimplicialComplex as well?

So far, I did not introduce any check for the node_labels and hyperedge_labels because I think the raised errors (from python) are already explicative. Let me know if I should improve them.
opened by mcontisc 9
Docs spiff up
Added a short blurb on the landing page. This was a feedback I received from someone who looked at the page and told me they have no idea what the library was even for!

Added a reference that seemed relevant.

Updated python version to 3.11.

Fixes #185.
opened by leotrs 9
Normalize edge "order" and "size"

The words "order" and "size" are used throughout the codebase to refer to the number of nodes in an edge (where order = size-1). I'd suggest we choose one and remove all instances of the other. For example, we have H.edge_size but H.edges_of_order.

opened by leotrs 9
Add functions to get largest connected component
Graph generators may sometimes return hypergraphs with isolated nodes (e.g. ER hypergraph with small p). In these cases, and others, it is usual to obtain the largest component. Ideally, we would like to do something like this:

G = xgi.erdos_renyi_hypergraph(n, m, p).largest_component() G = xgi.erdos_renyi_hypergraph(n, m, p).remove_isolates()
opened by leotrs 9
Add ability to specify hyperdegree order

The current functionality only specifies the number of hyperedges to which a node belongs. In principle, one should be able to specify a hyperedge size or list of sizes and it returns the number of hyperedges of that size of which that node is a part.
enhancement

opened by nwlandry 9
Repeated hyperedges are not merged and transformed in weighted hyperedges
When I create the hypergraph

H = xgi.Hypergraph([[1, 2], [1, 2], [1, 2, 4]])

the hyperedge (1, 2) is considered twice in the incidence matrix, even if it is recognized to be duplicated by running duplicate_edges().

Similarly, the hypergraph

H = xgi.Hypergraph([[1, 2], [2, 1], [1, 2, 4]])

considers the hyperedge (1, 2) different from (2, 1) and it will create two different columns in the incidence matrix. This time, it is not recognized to be duplicated.

In my experience, I would consider the hyperedge (1, 2) once with weight 2 for both cases.

Thus, is this a desired feature of the class or a bug in the code?
opened by mcontisc 7
Fix drawing
This fixes #137 and #140. Among other things, user can specify

node size, node line color, node face color, node line width, edge line width, and edge color as dictionaries, iterables, or strings.

edge face color as a colormap, dictionary, iterable or string.

The draw function is now modularized into draw_xgi_nodes, draw_xgi_hyperedges, and draw_xgi_complexes as well as a few helper functions. In addition, nodes are now drawn with scatter not Circle objects.
opened by nwlandry 7
Simple way to list available datasets on XGI-data

I'm not sure if this goes here or in the XGI-data repo directly, but it would be useful to have a simple function list the possible datasets that one can download, without having to go and check the index.json file in xgi-data.

opened by lordgrilo 0
testing long outputs from external file?

I wonder if we're getting to the point where some of these longer test outputs should be read in from a file to declutter the tests, but I think that's a future discussion. Can you make it an open issue?

Originally posted by @nwlandry in https://github.com/ComplexGroupInteractions/xgi/pull/257#discussion_r1053499570

opened by maximelucas 0
Use tox?

Hello, I see you don't use https://tox.wiki/en/latest/, I'm happy to setup a PR to use it if you are interested. It is then very easy to run locally tests/linting/formating.

For example, in the repo locally, one can do tox -e format to run black/isort, etc... or tox -e lint to check lint (or other formatting checks) pass, or tox -e py to run pytest, etc...

Then tox can be called from github actions directly for CI.

opened by arnaudon 6
Update simplicial kuramoto module
remove non-necessary extra dimension for theta0 and omega

allow use of scipy solve_ivp integrator for better precision

use random default theta0 and omega, so it does not crash if user does not specify anything (which is allowed from function signature)

added Sakaguchi-kuramoto model following https://github.com/arnaudon/simplicial-kuramoto (with and without orientation preserving)
opened by arnaudon 1
Cannot add attributes to existing edges

I want to add attributes to edges after I have created a hypergraph with H = xgi.Hypergraph(incoming_data=hyperedge_list) and I do not think it is possible right now (please correct if I am wrong).

Note that this issue is only relevant when the hypergraph is constructed first, then edge attributes added later. I could instead create an empty hypergraph and add edges one at a time with the relevant attributes (this is what I will do for now). In fact this would save me looping over the edges a second time after construction. However, in my particular use case I would prefer the semantics I describe because I think (1) they are more clear/general and (ii) would allow me to add attributes without constructing a new hypergraph. But the functionality is not sctrictly necessary.

It is possible to add or update attributes of existing nodes with H.add_node(existing_node, **attr), since per the docs

If node is already in the hypergraph, its attributes are still updated.

However, the same does not work for edges, because H.add_edge(existing_edge_members, **attr) creates a multi-edge, and H.add_edge(edge_id, **attr) fails because H.add_edge expects an iterable representing a hyperedge as its first argument, not an edge ID.

The simplest fix I can think of is to allow H.add_edge to accept an edge ID, check if the edge exists and if so modify provided attributes, or raise an error if the edge ID is not present. However, I think that overloads add_edge in a confusing way (already the case with add_node), so it may be better to define new functions for attribute addition/updates, i.e.,

H.update_node_attributes(node, **attr) and H.update_edge_attributes(edge_id, **attr),

with the edge function accepting an edge ID rather than the hyperedge itself. These functions might return an error if the node/edge does not exist and/or a warning if the attribute does not already exist for the node/edge, both of which could be managed with boolean arguments to the functions. This setup pushes the multi-edge issue onto the user, since whether multi-edges should have the same attributes is generally ambiguous.

I think this is related to discussions in #126 and #175.

opened by tlarock 4

Releases(v0.5.1)

v0.5.1(Dec 9, 2022)
draw() now correctly plots simplicial complexes with the max_order keyword #248 (@maximelucas).

Changed the add_simplex method to be non recursive #247 (@maximelucas).

Added tests for the SimplicialComplex class #245 (@maximelucas).

Made all draw functions available from xgi #246 (@maximelucas).

Added an indent to make hypergraph json files more readable #242 (@maximelucas).

Improved the efficiency of the uid update function #239 (@nwlandry).

Added the ability to display the node and hyperedge labels in draw() #234 (@mcontisc).

Fixed the uid counter initialisation #225 (@maximelucas).

Added the ability to pickle hypergraphs #229 (@nwlandry).

Made random_hypergraph() and random_simplicialcomplex() faster #213 (@maximelucas).

Fixed a bug in dynamical_assortativity() #230 (@nwlandry).

Removed all random decorators #227 (@nwlandry).

Modified unique_edge_sizes() so that the list of sizes is now sorted #226 (@nwlandry).

Added the merge_duplicate_edges() function to merge multi-edges #210 (@nwlandry).

Partial speed-up of draw function #211 (@iaciac).

Added a simplicial synchronization function #212 (@Marconurisso).

Sped up the add_simplices_from() method #223 (@maximelucas).

Updated the add_simplices_from() method to match add_hyperedges_from() #220 (@maximelucas).

Source code(tar.gz)
Source code(zip)
v0.5.0(Nov 8, 2022)
Fixed #214, added a powerset() function, added a subfaces() function, and added examples of these functions (#209).

Refactored the NodeStats and EdgeStats classes to be more efficient (#209).

Implemented set operations for NodeView and EdgeView (#208).

Addressed #180 with density() and incidence_density() functions (#204 and #207).

Added the << operator to "add" two hypergraphs together (#203).

Improved the documentation (#202).

Added Python 3.11 to the test suite (#201).

Added an option to fill only some cliques with probabilities ps to xgi.flag_complex() (#200).

Fixed Issue #198 (#199).

Refactored load_xgi_data() to call dict_to_hypergraph() and fixed a bug in dict_to_hypergraph() (#193).

Added num_edges_order() to get the number of edges of a given order and added an order parameter to the degree_counts() function (#192).

Fixed #182 and #186 by adding a max_order argument to draw() and load_xgi_data() (#173) .

Made draw() faster by refactoring _color_arg_to_dict() and _scalar_arg_to_dict() (#173).

Contributors: @leotrs, @maximelucas, and @nwlandry
Source code(tar.gz)
Source code(zip)
v0.4.3(Sep 19, 2022)
Hypergraph.has_edge is now IDView.lookup, Hypergraph.duplicate_edges is now IDView.duplicates, and utilities.convert_labels_to_integer is now function.convert_labels_to_integer (#150).

Added some unit tests for the convert module, the function module, and the classic generators module. Fixed for minor bugs encountered while writing tests and added documentation to Read The Docs for the drawing module. (#153)

Fixed a bug in remove_node_from_edge() (#154).

Implemented computation of moments for NodeStat and EdgeStat (#155).

Implemented weak and strong node removal as per issue #167 (#156).

Added a dynamics module and created a Kuramoto model synchronization function (#159).

Added a cleanup method that removes artifacts specified by the user: multi-edges, singletons, isolates. It also can convert all labels to consecutive integers (#161).

Modified the duplicates() method to not include the first instance of the node/edge in the list of duplicates (#161).

Converted all instances of edges to sets from lists in response to issue #158 (#162).

Added lambda function default arguments for $f$, $g$, $\varphi$, $\psi$ as defined by Tudisco and Higham. Default behavior is identical as before. Fixes #132 (#165).

Added sum() as a stats method (#168).

Added a benchmarking suite for the core hypergraph data structure using airspeed velocity (#170).

Fixed issue #171 (#172)

Contributors: @nwlandry, @leotrs, and @saad1282
Source code(tar.gz)
Source code(zip)
v0.4.2(Aug 8, 2022)
Keyword arguments are now consistent in the draw() function (#148).

Notebooks are now formatted with black and the requirements have been updated to reflect this (#148).

Contributors: @nwlandry
Source code(tar.gz)
Source code(zip)
v0.4.1(Aug 4, 2022)
Added the ability to color nodes and edges in xgi.draw() by value, iterable, or NodeStat/EdgeStat (#139, #142, and #143).

Fixed the distortion of the node aspect ratio with different figure sizes in Issue #137.

Moved the isolates() and singletons() method from the Hypergraph class to the NodeView and EdgeView classes respectively (#146).

Fixed Hypergraph.copy() to not use the subhypergraph method (#145).

filterby() now accepts NodeStat and EdgeStat objects instead of just strings (#144).

Removed edit-mode install to run the Github Actions test suite (#136).

Added unit tests (#147).

Contributors: @nwlandry, @leotrs, and @maximelucas
Source code(tar.gz)
Source code(zip)
v0.4(Jul 6, 2022)
Added the stats package which implements NodeStat, EdgeStat and related functionality. This package now handles computation of edge size and degree (#120).

Removed the EdgeSizeView and DegreeView classes (#120).

Changed all imports to be relative in the xgi package (#121).

Added an assortativity module (#122).

Improved the performance of accessing edge members (#124).

Added more operations for node and edge attributes besides "eq" (#125).

Added a function to convert all node and edge labels to integers and store the old labels as properties (#127).

Renamed the egonet method to `edge_neighborhood (#129).

Moved the neighbors method in the Hypergraph class to the IDView class so that node and edge neighbors are now supported (PR #129).

Added a centrality module and added these methods to nodestats.py and edgestats.py (#130).

Moved the load_xgi_data method to the readwrite module (#130).

Added a generator for sunflower hypergraphs (#130).

Added a Jupyter notebook as a quickstart guide (#131 and #134).

Fixed a bug in the barycenter_spring_layout and weighted_barycenter_spring_layout methods to handle non-integer node IDs (#133).

Added an isort configuration file so it no longer sorts the __init__.py files (#134).

Contributors: @leotrs, @nwlandry, and @iaciac
Source code(tar.gz)
Source code(zip)
v0.3.1(Jun 7, 2022)
Refactored the subhypergraph methods

Moved functions no related to the core Hypergraph data structure to functions.py

Removed unnecessary duplicated functions (n_bunch_iter, get_edge_data, and has_node)

Refactored the members() method as well as the NodeView and EdgeView classes for significant speedup.

Github Actions now tests the docstrings and tutorial notebooks

The add_edges_from method now supports different input formats.

Fixed various bugs in the generative models module.

A method for double edge swaps is now implemented.

Contributors: @leotrs and @nwlandry
Source code(tar.gz)
Source code(zip)
v0.3(Apr 29, 2022)
Added the ability to convert to and from a NetworkX bipartite graph.

Removed the shape property from Hypergraph and renamed the number_of_nodes() and number_of_edges() methods to the num_nodes and num_edges properties, respectively.

Added random seed decorator as in NetworkX.

Added a SimplicialComplex class.

Added order and weighted arguments to the incidence_matrix and adjacency_matrix functions.

Added an intersection_profile function.

Added a laplacian function with argument order and a multiorder_laplacian function.

Fix: Return an empty array rather than a 1x1 zero array when appropriate.

Fix: Ensured that the incidence matrix is always has dimensions num_nodes x num_edges.

Added 2 generators of random (maximal) simplicial complexes, and toy star-clique generator

Extensively rewrote the documentation, updating the content and format on Read The Docs.

Added an egonet function to get the edges neighboring a specified node.

Added functions to visualize hypergraphs and simplicial complexes.

Added the ability to get nodes and edges of given degrees/sizes respectively.

Extended the members() function to be able to get different data types and to either get a single edge or all edges.

Added the load_xgi_data function to load datasets from the xgi-data repository.

Added two additional tutorials: a tutorial on visualizing higher-order networks and a case study replicating a recent paper.

Changed the API of degree_histogram and added degree_counts based on #23.

Refactored the IDDegreeView class and changed the API. Added the ability to specify order and the datatype.

Added an abstract class IDDict to handle data validation.

Contributors: @iaciac @leotrs @lordgrilo @maximelucas @nwlandry @tlarock
Source code(tar.gz)
Source code(zip)
v0.2(Feb 8, 2022)
H[attr] now accesses hypergraph attributes

H.nodes[id] now accesses attributes, not bipartite neighbors

Removed the__call__() functionality from H.nodes and H.edges

H.nodes.memberships(id) and H.edges.members(id) now access the bipartite neighbors

Created base classes for the Node/Edge Views and Degree/Edge Size Views to inherit from.

Removed the NodeDataView and EdgeDataView.

Updated the list of developers

__getitem__() in the NodeView and EdgeView are now in a try-except block for greater efficiency.

Removed the name attribute and fixed methods and tests to match.

Fixed the erdos_renyi_hypergraph(), chung_lu_hypergraph(), and dcsbm_hypergraph() methods such that the number of nodes will always match the number the user specifies, even if the resulting hypergraph is disconnected.

Changed the construction method from reading in a Pandas DataFrame to using the add_node_to_edge() method for a 2x speedup.

Added some basic unit tests for the generative models.

Added the dual keyword for the read_bipartite_edgelist() method.

Added small functions to the Hypergraph class

Added generator of random hypergraph

Added functions for finding and removing isolates

Refactored the has_edge() method in the Hypergraph class.

Contributors: @leotrs @maximelucas @nwlandry
Source code(tar.gz)
Source code(zip)
v0.1.4(Dec 12, 2021)
Removed networkx dependency

Renamed HypergraphError to XGIError

General code cleanup

Added a bunch of tests

Source code(tar.gz)
Source code(zip)
v0.1.3(Dec 3, 2021)
Added manifest file to fix pip install error

Source code(tar.gz)
Source code(zip)
v0.1.2(Dec 3, 2021)
Fixed an issue users reported with the pip install.

Source code(tar.gz)
Source code(zip)
v0.1.1(Dec 1, 2021)
Fixed bug in the unique_edge_sizes function

Automated the import of necessary packages from the requirements file

Added documentation to the PyPi page

Source code(tar.gz)
Source code(zip)
v0.1(Nov 17, 2021)

Initial Release
Source code(tar.gz)
Source code(zip)

Owner

Complex Group Interactions

CompleX Group Interactions (XGI) provides an ecosystem for the analysis and representation of complex systems with group interactions.

GitHub Repository https://xgi.readthedocs.io/en/latest/

CompleX Group Interactions (XGI) provides an ecosystem for the analysis and representation of complex systems with group interactions.

Related tags

Overview

XGI

Table of Contents:

Installation

Getting Started

Documentation

Contributing

How to Cite

Code of Conduct

License

Funding

Other resources

Comments

Releases(v0.5.1)

v0.5.1(Dec 9, 2022)

v0.5.0(Nov 8, 2022)

v0.4.3(Sep 19, 2022)

v0.4.2(Aug 8, 2022)

v0.4.1(Aug 4, 2022)

v0.4(Jul 6, 2022)

v0.3.1(Jun 7, 2022)

v0.3(Apr 29, 2022)

v0.2(Feb 8, 2022)

v0.1.4(Dec 12, 2021)

v0.1.3(Dec 3, 2021)

v0.1.2(Dec 3, 2021)

v0.1.1(Dec 1, 2021)

v0.1(Nov 17, 2021)

Owner

Complex Group Interactions

3D Vision functions with end-to-end support for deep learning developers, written in Ivy.

A python script and steps to display locations of peers connected to qbittorrent

A set of three functions, useful in geographical calculations of different sorts

A concise grammar of interactive graphics, built on Vega.

RockNext is an Open Source extending ERPNext built on top of Frappe bringing enterprise ready utilization.

clock_plot provides a simple way to visualize timeseries data, mapping 24 hours onto the 360 degrees of a polar plot

A custom qq-plot for two sample data comparision

Simple and fast histogramming in Python accelerated with OpenMP.

Data visualization using matplotlib

I'm doing Genuary, an aritifiacilly generated month to build code that make beautiful things

HM02: Visualizing Interesting Datasets

coordinate to draw the nimbus logo on the graffitiwall

CLAHE Contrast Limited Adaptive Histogram Equalization

Streamlit-template - A streamlit app template based on streamlit-option-menu

A tool to plot and execute Rossmos's Formula, that helps to catch serial criminals using mathematics

script to generate HeN ipfs app exports of GLSL shaders

A program that analyzes data from inertia measurement units installed in aircraft and generates g-exceedance curves.

Python script for writing text on github contribution chart.

Here are my graphs for hw_02

Missing data visualization module for Python.