Cross-source API

Browse, download and cache network datasets.

Each repository lives in its own subpackage:

• netgamut.snap – the Stanford Large Network Dataset Collection, 109 datasets. Large, well known, and skewed to social, web and technological systems.

• netgamut.netzschleuder – networks.skewed.de, 286 networks tagged by domain, including the biological, transport and multilayer networks SNAP has none of.

• netgamut.konect – KONECT, the Koblenz Network Collection, 300 networks described in one fixed vocabulary of format, edge type and loops. A network Netzschleuder or SNAP also holds is listed there but used from the other source here, so nothing is counted twice.

• netgamut.ogb – Open Graph Benchmark, 12 datasets whose node categories are named rather than left as anonymous codes.

• netgamut.pyg – the PyTorch Geometric corpus, 99 datasets: citation, web, social and heterophilous graphs.

• netgamut.paths – curated path data (flight itineraries, navigation trails) plus the conversion into second-order state networks for Infomap’s memory model, which no edge list can express.

• netgamut.ahorn – the Aachen Higher-Order Repository of Networks, 83 hypergraphs and simplicial complexes. Its unit is a set of nodes rather than a pair, so it returns a Hypergraph rather than a Network.

Metadata for every source ships inside the package, so browsing is offline and instant; only load() touches the network, and it caches into a shared user-level directory so a dataset is fetched once per machine.

Beyond the datasets, netgamut.generate samples synthetic benchmark networks with planted communities from any blueprint in the pool (requires the generate extra).

Every network – downloaded or generated, first-order, state or multilayer – converts and writes the same way: to_networkx(), to_infomap(), and to_pajek(directory) / to_link_list(directory), which return the path of the file they wrote.

All sources are mapped onto one domain vocabulary, so a comparison can span kinds of system rather than kinds of provenance:

import netgamut

netgamut.domains()
# {'Social': 201, 'Informational': 68, 'Biological': 36, ...}

for dataset in netgamut.search(domain="Biological", max_nodes=1000):
    print(dataset.source, dataset.name)

Please cite the datasets you use – each source’s records carry the reference its site asks for.

netgamut.search(query='', *, domain=None, source=None, directed=None, max_nodes=None, min_nodes=None, max_edges=None, min_edges=None, loops=None, node_metadata=None, node_attribute=None, weighted=None, bipartite=None, temporal=None, multilayer=None, signed=None, multigraph=None, unknown=False)

Search every source at once, filtering on the shared domain vocabulary.

Only the fields every source agrees on are accepted here. For anything source-specific – SNAP’s ground-truth partitions, Netzschleuder’s subtypes, OGB’s loadability, PyG’s class – use that source’s own search().

Size filters exclude datasets whose size the source does not publish rather than assuming anything: most PyG entries and the largest OGB ones have no counts. loops does the same with datasets no source has checked for self-links (see Match.loops), and node_metadata with datasets whose catalog cannot say (see Match.node_metadata), and so do weighted, bipartite, temporal, multilayer, signed and multigraph (see Match.weighted and the rest). With unknown=True a dataset passes every filter its source cannot answer instead, so search(weighted=False, unknown=True) keeps the networks no catalog calls weighted. node_attribute finds datasets with a per-node column of that name, case-insensitively, among the names each catalog knows – node_attribute="gender" for something to score a partition against.

A network held by both KONECT and Netzschleuder or SNAP appears once, from the other source; source="konect" lists KONECT’s copy too.

Raises:

KeyError – Unknown domain or source.

netgamut.load(name, *, source=None, **kwargs)

Download a dataset by name, searching every source.

Pass source to disambiguate. Without it, a name present in more than one source is an error rather than an arbitrary choice – except that KONECT’s copy of another source’s network defers to that source.

Raises:

KeyError – No source has name, or several do and source was omitted.

netgamut.domains()

Dataset counts per domain, summed over every source.

A dataset listed under two domains counts once in each, and a network held by two sources counts once.

netgamut.sources()

The available data sources.

class netgamut.Match(source, dataset)

One dataset found by a cross-source query.

Keeps the source alongside the record, because the two catalogs use different names for the same idea and a few names appear in both.

property node_metadata: bool | None

Whether Network.nodes() returns per-node attributes; None if unknown.

Each source answers from its own catalog, before any download: KONECT and Netzschleuder from their file listings and analyses, SNAP from its label files, OGB and PyG from their class labels. AHORN keeps node lines inside the dataset file, so it cannot say.

property node_attributes: tuple[str, ...] | None

The per-node columns the source’s catalog can name, None if unknown.

Exact for Netzschleuder, KONECT and SNAP. OGB names only its extra files (year, species) and PyG none, since their other column names come with the download; nodes() returns those too.

property loops: bool | None

Whether any node links to itself, where some source has checked.

KONECT checks every network; for another source’s network, KONECT’s check is used when it holds the same edge list. None means unknown.

property weighted: bool | None

Whether links carry weights; None where the source cannot say.

From Netzschleuder’s tags, KONECT’s edge type, SNAP’s graph type and AHORN’s catalog. OGB, PyG and the path data cannot say.

property bipartite: bool | None

Whether links only join two kinds of node; None where the source cannot say.

KONECT and SNAP say so in their catalogs. For Netzschleuder it is the site’s structural check, no odd cycle, which every two-mode network passes and so do a few trees and grids.

property temporal: bool | None

Whether links carry timestamps; None where the source cannot say.

From Netzschleuder’s Temporal and Timestamps tags, KONECT’s timestamp column, SNAP’s graph type and AHORN’s catalog.

property multilayer: bool | None

Whether Netzschleuder publishes it as a multilayer or multiplex network.

None for every other source, whose catalogs do not say.

property signed: bool | None

Whether links are positive or negative; None where the source cannot say.

From Netzschleuder’s Signed tag, KONECT’s edge type and SNAP’s graph type.

property multigraph: bool | None

Whether some pair of nodes links more than once; None if the source cannot say.

From Netzschleuder’s Multigraph tag and KONECT’s edge type.

property key: str

"<source>/<name>" – unique across sources.

load(**kwargs)

Download this dataset via its own source.

to_dict()

A JSON-serialisable summary, the same shape for every source.

Holds the fields search() filters on plus what a reader needs to choose and cite a dataset: its description, citations, its page at the source (url) and, where the catalog records it, the original publisher (upstream_url). weighted, bipartite, temporal, multilayer, signed and multigraph are the properties of the same names, None where the source cannot say. duplicate_of is the key of the network a KONECT copy defers to (see netgamut.konect.duplicates()), else None. subgraph_count is how many networks the name holds: a Netzschleuder entry can hold several, the first few named in subgraphs, and the statistics describe the first, which load() fetches by default. Other sources hold one and name none.

netgamut.DOMAINS

Built-in immutable sequence.

If no argument is given, the constructor returns an empty tuple. If iterable is specified the tuple is initialized from iterable’s items.

If the argument is a tuple, the return value is the same object.

Cache

netgamut.cache_dir()

Return the root cache directory, creating it if necessary.

netgamut.set_cache_dir(path)

Point the cache at path for the rest of this process.

Passing None restores the default lookup. Returns the directory now in effect.

netgamut.cache_info()

Summarise what is currently cached on this machine, across all sources.

netgamut.clear_cache(name=None, *, source=None)

Delete cached downloads and return the number of bytes reclaimed.

With name, clears just that dataset; with source, everything from that source; with neither, the whole cache including any refreshed catalogs. The catalogs shipped inside the package are never touched.

netgamut.CACHE_ENV_VAR = 'NETGAMUT_CACHE_DIR'

str(object=’’) -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to ‘utf-8’. errors defaults to ‘strict’.

class netgamut.CacheInfo(path, bytes, datasets, refreshed_catalogs=())

A summary of the local cache.

datasets: dict[str, CachedDataset]

Keyed "<source>/<name>", so the two sources stay distinguishable.

refreshed_catalogs: tuple[str, ...]

Sources with a refreshed catalog in the cache shadowing the bundled one.

class netgamut.CachedDataset(source, name, files, bytes)

What is on disk for one dataset.