{"id":19456796,"url":"https://github.com/aidos-lab/orchid","last_synced_at":"2025-04-25T05:31:07.049Z","repository":{"id":175218166,"uuid":"537089105","full_name":"aidos-lab/orchid","owner":"aidos-lab","description":"Ollivier-Ricci Curvature for Hypergraphs: A Unified Framework (ICLR 2023)","archived":false,"fork":false,"pushed_at":"2023-06-14T08:34:33.000Z","size":761,"stargazers_count":18,"open_issues_count":0,"forks_count":4,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-03T16:52:33.336Z","etag":null,"topics":["curvature","graphs","hypergraphs","iclr2023"],"latest_commit_sha":null,"homepage":"https://arxiv.org/abs/2210.12048","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aidos-lab.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-09-15T15:25:10.000Z","updated_at":"2025-02-10T09:35:02.000Z","dependencies_parsed_at":null,"dependency_job_id":"95eed416-c848-437a-ad80-a15101425f2e","html_url":"https://github.com/aidos-lab/orchid","commit_stats":null,"previous_names":["aidos-lab/orchid"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aidos-lab%2Forchid","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aidos-lab%2Forchid/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aidos-lab%2Forchid/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aidos-lab%2Forchid/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aidos-lab","download_url":"https://codeload.github.com/aidos-lab/orchid/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250760696,"owners_count":21482851,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["curvature","graphs","hypergraphs","iclr2023"],"created_at":"2024-11-10T17:18:29.982Z","updated_at":"2025-04-25T05:31:07.043Z","avatar_url":"https://github.com/aidos-lab.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Orchid 🌸 – Ollivier-Ricci Curvature for Hypergraphs: A Unified Framework\n\n\u003ctable\u003e\n    \u003ctr\u003e\n        \u003ctd\u003e\n            This repository provides a Julia library and a command-line interface that implements the \u003ci\u003eOllivier-Ricci Curvature for Hypergraphs in Data\u003c/i\u003e (Orchid) Framework. \u003cbr/\u003e\u003cbr/\u003e\n            This project is based on the research paper \u003ca href=\"https://doi.org/10.48550/arXiv.2210.12048\"\u003eOllivier-Ricci Curvature for Hypergraphs: A Unified Framework\u003c/a\u003e, published at ICLR 2023. \u003cbr/\u003e\u003cbr/\u003e\n            The full reproducibility package, including the data that can be shared, is available on \u003ca href=\"https://doi.org/10.5281/zenodo.7624573\"\u003eZenodo\u003c/a\u003e. \u003cbr/\u003e\u003cbr/\u003e\n            If you find this repository helpful, please consider citing our paper!\n        \u003c/td\u003e\n    \u003ctd\u003e\n        \u003cimg\n  src=\"/orchid_thumbnail.png\"\n  alt=\"Orchid Thumbnail\"\n  style=\"display: inline-block; margin: 0 auto; width: 300px\"\u003e\n        \u003c/td\u003e    \n\u003c/tr\u003e\n\u003c/table\u003e\n\n```bibtex\n@inproceedings{coupette2023orchid,\n    title     = {Ollivier-Ricci Curvature for Hypergraphs: A Unified Framework},\n    author    = {Corinna Coupette and Sebastian Dalleiger and Bastian Rieck},\n    booktitle = {The Eleventh International Conference on Learning Representations (ICLR)},\n    year      = {2023},\n    url       = {https://openreview.net/forum?id=sPCKNl5qDps},\n    doi       = {10.48550/arXiv.2210.12048}\n}\n```\n\n## Installation\n\n### Julia Library\n\nTo install the Orchid Julia library:\n```julia-repl\njulia\u003e using Pkg\njulia\u003e Pkg.add(url=\"https://github.com/aidos-lab/orchid.git\")\n```\nAlternatively, we can install Orchid from the command line:\n```sh\njulia -e 'using Pkg; Pkg.add(url=\"https://github.com/aidos-lab/orchid.git\")'\n```\n\n### Command-Line Interface\nTo use the command-line interface, we additionally need `bin/orchid.jl` and its dependencies.\n```sh\ngit clone https://github.com/aidos-lab/orchid\njulia -e 'using Pkg; Pkg.add(path=\"./orchid\"); Pkg.add.([\"ArgParse\", \"JSON\", \"Glob\", \"CodecZlib\"])'\n```\n\n## Usage\n\n### Julia REPL\n\nAssuming the hypergraph resides in variable `X`:\n\n```julia-repl\njulia\u003e using Orchid\njulia\u003e hypergraph_curvatures(DispersionUnweightedStar, AggregationMax, X, 0.01)\n\nhelp?\u003e Orchid.hypergraph_curvatures\n```\n\nTo inspect the results:\n\n    hypergraph_curvatures\n\n### Arguments\n- `disperser`: Dispersion (options: DisperseUnweightedClique, DisperseWeightedClique, or DisperseUnweightedStar – Orchid paper: μ)\n- `aggregator`: Aggregation (options: AggregateMean, AggregateMax, or (AggregateMean, AggregateMax) – Orchid paper: AGG)\n- `input`: Incidence-matrix or edge-list encoding of the hypergraph\n- `alpha`: Self-dispersion weight (smoothing parameter corresponding to the laziness of the random walk – Orchid paper: α)\n- `cost`: Cost computation strategy (options: CostOndemand^, CostMatrix)\n\n    ^ useful for very large hyper graphs.\n\n### Command-Line Interface \n\nTo use the command-line interface:  \n\n```sh\nchmod +x bin/orchid.jl\nbin/orchid.jl --help\nbin/orchid.jl --aggregation mean --dispersion WeightedClique -i data/toy.ihg.tsv -o results/toy.orc.json \nbin/orchid.jl --aggregation max --dispersion UnweightedStar --alpha 0.1 -i data/toys.chg.tsv -o results/toys.orc.json\n```\n\nThe first execution might take some time.\n\n### Bash Scripts\n\nFor convenience, we provide bash scripts to perform the curvature computations in the configurations reported in the ICLR paper for the shareable datasets used in the paper as well as (for illustration) for tiny toy data. \nBoth scripts compute curvatures with alpha in {0.0,0.1,0.2,0.3,0.4,0.5} for all combinations of dispersion and aggregation:\n\n- `reproduce.sh`: Computation for `{dblp,ndc-ai,ndc-pc}.ihg.tsv` and `{dblp-v,mus,sha,stex,syn_hcm,syn_hcm-hsbm,syn_hnmp,syn_hsbm}.chg.tsv`; results are stored to `results` folder as gzip-compressed JSON files.\n- `reproduce_toy.sh`: Computation for `toy.ihg.tsv` and `toys.chg.tsv`; results are stored to `results` folder as uncompressed JSON files.\n\nNote that `reproduce.sh`, when run as-is, will consume considerable computational resources. \nThe easiest way to restrict computation to smaller datasets or some parts of our configuration space is to redefine some of the arrays at the top of the script.\n\n## Experiments\n\nTo evaluate our curvature results, we require additional python packages.\nWe recommend installing these into a virtual environment, the classic option being [venv](https://docs.python.org/3/library/venv.html).\n```sh\npip install -r experiments/requirements.txt\n```\n\nFor our clustering, MMD, and kPCA experiments on collections of hypergraphs, we first compute their curvatures.\n```sh\nbin/orchid.jl --aggregation mean --dispersion WeightedClique -i data/syn_hcm-hsbm.chg.tsv.gz -o results/syn_hcm-hsbm.orc.json.gz \n```\nThen, we evaluate the collection of curvatures using the tools in `experiments/`.\n```sh\npython experiments/graph-clustering.py -k 2 -i results/syn_hcm-hsbm.orc.json.gz -o gc/syn_hcm-hsbm.gc.json.gz \npython experiments/kpca.py -k 2 -i results/syn_hcm-hsbm.orc.json.gz -o kpca/syn_hcm-hsbm.kpca.json.gz \npython experiments/mmd.py -i results/syn_hcm-hsbm.orc.json.gz -o mmd/syn_hcm-hsbm.mmd.json.gz \n```\n\nFor our node-clustering experiments with individual hypergraphs, we proceed similarly, now computing curvatures before we cluster the nodes.\n```sh\nbin/orchid.jl --aggregation mean --dispersion WeightedClique -i data/dblp.ihg.tsv.gz -o results/dblp.orc.json.gz\npython experiments/node-clustering.py -k 2 -i results/dblp.orc.json.gz -o nc/dblp.nc.json.gz\n```\n\nTo produce the files containing the competing local features, which can be input to the experiment scripts in place of the curvature files:\n\n```sh\npython experiments/features.py -i data/sha.chg.tsv.gz -o features/sha.chg.json.gz\n```\n\n## Data Formats used by the Command-Line Interface\n\n### Inputs\n\nThe data underlying our experiments are provided in a concise tsv format which allows us, inter alia, to store an entire hypergraph collection in *one* file.  \nThe files encoding *individual hypergraphs* end with `ihg.tsv[.gz]`.  \nThe files encoding *collections of hypergraphs* end with `chg.tsv[.gz]`.  \nNodes are assumed to be consecutive, *one-indexed* integers.\n\n#### Individual hypergraphs (ihg): {name}.ihg.tsv.gz\n\nEach row is a hyperedge, with the identifiers of nodes occurring in the hyperedge separated by `\\t` characters.\n\nExample (`data/toy.ihg.tsv`):\n```sh\n1   2   3   4   5\n2   3\n5   7   3   6\n```\n\n#### Collections of hypergraphs (chg): {name}.chg.tsv.gz\n\nJust like the format for individual hypergraphs, \nexcept that now the *first* identifier in each row identifies the hypergraph to which the hyperedge belongs.\n\nExample (`data/toys.chg.tsv`): \n```sh\n2   1   2   3   4   5\n2   2   3\n2   5   7   3   6\n0   1   2   4\n0   1   3   5\n0   1   4   6\n0   6   4   2   5\n```\n\nNote that Orchid will treat the hypergraphs in the order in which their unique identifiers appear in the input, so in the example above, the hypergraph with ID 2 will occur before the hypergraph with ID 0 in the results.  \nThe example also illustrates that we do not assume the hypergraph identifiers to be one-indexed or consecutive.\n\n### Outputs\n\nCurvature files are (optionally: gzip-compressed) JSON files of the form:\n\n```sh\n[\n  {\n    \"node_curvature_neighborhood\":[...],\n    \"directional_curvature\":[\n      [...i values...],\n      [...j values...],\n      [...k values...]\n    ],\n    \"node_curvature_edges\":[...],\n    \"edge_curvature\":[...],\n    \"aggregation\":\"Orchid.AggregateMax\",\n    \"dispersion\":\"UnweightedStar\",\n    \"input\":\"../data/toys.chg.tsv\",\n    \"alpha\":0.1\n  },\n  {\n    ...\n  }\n]\n```\n\nThat is, we provide a list of JSON objects, one for each input hypergraph.  \nIf the input is an individual hypergraph, the list will just have one entry.  \nIf the input is a collection of hypergraphs, the list will contain the hypergraphs in the order they were found in the input file. \n\n## Disclaimer\n\nWe refactored the entire code base and introduced the {ihg,chg}.tsv[.gz] data format after ICLR 2023. \nThe material results are the same, but there might be small deviations in details.\n\n## Contributing\n\nContributions to Orchid are welcome.  \nIf you find any issues or have suggestions for improvements, please open an issue or submit a pull request in the GitHub repository: https://github.com/aidos-lab/orchid\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faidos-lab%2Forchid","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faidos-lab%2Forchid","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faidos-lab%2Forchid/lists"}