regrank aims to implement a suite of regularized models to infer the hierarchical structure in a directed network.

Docs · Discussions · Examples

This is the software repository behind the paper:

• Tzu-Chi Yen and Stephen Becker, Regularized methods for efficient ranking in networks, in preparation.

Installation

RegRank relies on powerful Python libraries with deep C++ dependencies, such as Ax (ft. PyTorch & BoTorch, for hyperparameter search), CVXPY (ft. OSQP/ECOS/SCS, for convex optimization), and graph-tool (ft. BOOST & CGAL, for graph analysis). These packages cannot be installed by pip alone.

Therefore, the recommended installation strategy is a hybrid approach: 1. Use Conda to create a stable environment and install these heavy, compiled dependencies. 2. Use uv (a fast package manager written in Rust) to install regrank and its Python dependencies.

We recommend Miniforge or Mambaforge for a minimal, conda-forge-centric setup. Follow these steps to install and use regrank as a library in your projects.

```bash

1. In a new dir, create a conda environment with Python.

conda create -n regrank -c conda-forge python=3.11 -y

2. Activate the new environment.

conda activate regrank

3. Install PyTorch (a dependency for Ax), CVXPY, and graph-tool.

Using conda for PyTorch is more robust, especially on macOS.

conda install -c pytorch pytorch torchvision conda install -c conda-forge graph-tool python-graphviz cvxpy sage ecos # docs todo

4. Install regrank using uv.

(If you don't have uv yet: pip install uv)

uv pip install regrank ```

Example

```python

Import the library

import regrank as rr

Load a data set

g = rr.datasets.usairtraffic()

Create a model

model = rr.SpringRank(method="annotated")

Fit the model: We decided to analyze the state_abr nodal metadata,

We may inspect g.list_properties() for other metadata to analyze.

result = model.fit(g, alpha=1, lambd=0.5, goi="state_abr")

Now, result["primal"] should have the rankings. We can compute a summary.

summary = model.computesummary(g, "stateabr", primal_s=result["primal"]) ```

Let's plot the rankings, via rr.plot_hist(summary). Note that most of the node categories are regularized to have the same mean ranking.

We provided a summary via rr.print_summary_table(summary).

  +-------+-------+--------+-----------------------------------------+--------+---------+
  | Group | #Tags | #Nodes | Members                                 |   Mean |     Std |
  +-------+-------+--------+-----------------------------------------+--------+---------+
  | 1     |     5 |    825 | CA, WA, OR, TT, AK                      |  0.047 | 1.1e-02 |
  | 2     |     4 |    206 | TX, MT, PA, ID                          | -0.006 | 4.2e-03 |
  | 3     |    43 |   1243 | MI, IN, TN, NC, VA, IL, CO, WV, MA, WI, | -0.035 | 4.3e-03 |
  |       |       |        | SC, KY, MO, MD, AZ, PR, LA, UT, MN, GA, |        |         |
  |       |       |        | MS, HI, DE, NM, ME, NJ, NE, VT, CT, SD, |        |         |
  |       |       |        | IA, NV, ND, AL, OK, AR, NH, RI, OH, FL, |        |         |
  |       |       |        | KS, NY, WY                              |        |         |
  | 4     |     1 |      4 | VI                                      | -0.072 | 0.0e+00 |
  +-------+-------+--------+-----------------------------------------+--------+---------+

The result suggests that states such as CA, WA, or AK are significantly more popular than other states.

Data sets

We have a companion repo, regrank-data, which stores the data sets used in the paper. These data can be loaded via the regrank.datasets submodule, and will load into a graph-tool graph object. See the docs for more description.

• PhD_exchange
• Parakeet
• Austrian internal migrations: Network of migrations between municipalities in Austria, from 2002 to 2022.
• U.S. air traffic: Yearly snapshots of flights among all commercial airports in the United States from 1990 to today.

Development Notes

We use pytest to ensure the consistency and correctness during development. The test suite uses CVXPY's SCS solver to compare results. One may optionally use other solvers but they must be installed independently. See CVXPY's installation guide.

If you want to contribute to regrank (thank you!), we recommend setting the enviroment by (1) Git clone this repository and navigate into it; (2) Follow Steps 1 to 3 as above; (3) Install regrank in "editable" mode along with its development dependencies, via uv pip install -e ".[dev]".

Use pre-commit run --all-files for pre-commit checks.

License

regrank is open-source and licensed under the GNU Lesser General Public License v3.0. This means that you are welcome to include this library in your own projects, whether they are open-source or proprietary. The main idea is to allow you to use the library's functionality freely, while ensuring that any improvements made directly to regrank itself are shared back with the community -- through a legal mechanism called "weak copyleft".

Acknowledgments

TCY wants to thank Perplexity.ai and gemini-2.5-pro-preview-06-05.