Atlas · User guide

Everything Atlas does,
and how to do it.

Every concept and feature, from importing your first table to scripting a reproducible figure, with step-by-step recipes for common tasks.

For bundle format v2

Part 1Start here

What Atlas is

Atlas is for researchers, investigators and analysts who work with large directed property graphs. In these graphs, nodes and edges carry typed properties, and the direction of an edge matters: who links to whom, who reposts which channel, who pays or cites whom. A graph of 40 million nodes and 93 million edges opens in seconds on a single workstation and stays interactive at every zoom level.

Atlas has four parts that share one data format and one command language:

  • The desktop app (atlas-app): a GPU canvas linked to search, an inspector, styling, filters, analysis and layout panels, and analytical windows.
  • The command-line tool (atlas-graph): import, analyse, lay out, compare, render and export without a window. Use it for batch work and pipelines.
  • Atlas Script: a small command language. It drives the app, records every session, and lets the CLI reproduce a view.
  • The Python package (atlas_graph): bundles as zero-copy Arrow arrays, plus analyses, layouts and imports from pyarrow tables.
A drawing is a map, not evidence

A force-directed layout helps you find your way. It does not prove that two nearby nodes are related, belong to one community or are connected by a path. Ask the inspector and the analyses: they answer from the graph itself. Atlas prints this reminder under every layout for the same reason.

The workflow

Most work follows the same six steps. You can stop at any step, and every step is available in the app, the CLI and Python.

  1. ImportNodes and edges become a checked, memory-mapped bundle. atlas-graph import
  2. AnalyseRun the standard set: degrees, components, cores, PageRank and more. atlas-graph analyze
  3. Lay outCompute positions for every node, on the GPU when available. atlas-graph layout
  4. ExploreZoom from overview to single edges. Search, inspect, colour, filter.
  5. AskFocus on neighbourhoods, compare groups, time windows and versions.
  6. ShareSave views and sessions; export data, images, GEXF or an offline viewer.

Install and quick start

Atlas is a free app for Macs with Apple Silicon. Download it from the Atlas page, or install it with Homebrew. A GPU is used for drawing and, when you ask for it, for layouts. Analyses run on the CPU.

brew install gerulata/tap/atlas-graph

The fastest way to see Atlas work is to generate a graph with planted communities. Then analyse it, lay it out and open it:

atlas-graph generate --topology sbm --nodes 100000 --edges 400000 --community-size 500 --out data/sbm.atlas
atlas-graph verify  data/sbm.atlas            # full integrity audit
atlas-graph analyze data/sbm.atlas            # the standard analyses
atlas-graph layout  data/sbm.atlas --gpu      # multilevel layout, large levels on the GPU
atlas-app     data/sbm.atlas

With your own data, preview a table first, then import a manifest that describes your files (see Import tables):

atlas-graph preview nodes.csv                       # sampled columns, proposed types and roles
atlas-graph import graph.json --out data/mine.atlas
atlas-graph analyze data/mine.atlas && atlas-graph layout data/mine.atlas --algorithm snap-tfdp --gpu
atlas-app data/mine.atlas

The app can do all of this too: File ▸ Import… (or drop the files on the window), then the Statistics and Layout tabs.

The Mac app

Requirements. A Mac with Apple silicon and macOS 13 Ventura or later. Memory sets the size of graph you can work with: a graph of 10 million nodes and 30 million edges opens with about 4 GB, and importing and laying it out took up to 13 GB.

Installing. Open the disk image and drag Atlas to Applications, or install it with Homebrew, which also puts the command-line tool atlas-graph on your PATH:

brew install gerulata/tap/atlas-graph

Without Homebrew, the command-line tool is inside the app, at /Applications/Atlas.app/Contents/MacOS/atlas-graph. To try Atlas before you have data of your own, choose File ▸ Open sample dataset. A dataset bundle is a document on a Mac: double-click a .atlas bundle in Finder to open it (Show Package Contents shows its files).

Updating. Atlas checks for a new version once a day, after asking you on its second launch, and installs it when you agree. Atlas ▸ Check for Updates… checks now; with Homebrew, brew upgrade works too.

Your files. Preferences and your presets are in ~/Library/Application Support/com.gerulata.atlas, and the log and any crash reports in ~/Library/Logs/com.gerulata.atlas (Help ▸ Show log folder). To uninstall, move Atlas to the Trash and delete those two folders, or run brew uninstall --zap gerulata/tap/atlas-graph. Your bundles stay where you keep them.

Problems. Help ▸ Report a problem… copies a short description of your Mac, its GPU and the open dataset (no data from it) to the clipboard and opens the support page.

The app window

The graph fills the window, on black, and the panels float over it as frosted glass: everything that controls the canvas is on the left, and everything about the current item is on the right. Fitting, centring and zooming with the keys use the free area between the panels.

Atlasdataset name · counts · search · panel toggles
Controlstabs: Layout · Style · Filter · Statistics · Data
Canvasdrag to pan, scroll to zoom, click to select, Shift-drag to lasso; legend and zoom controls float on it
Inspectorthe selected node, edge or group; focus, paths, profile. Charts dock beside it.
Bottom paneltabs: Nodes, or the hits of the search in the top bar, with their properties · Timeline, edges per time bucket (time role only)
OVERVIEW · what is drawn, aggregated or omitted · frame time sparkline
  • Menus. On macOS they are in the system menu bar; elsewhere, in the top bar. File opens (⌘O), imports, saves and exports. Edit has undo, redo and session history. View shows or hides the controls, inspector, bottom panel (or opens it on its timeline), legend and canvas controls, and opens Charts, Communities, Arrangement and Communities over time. Questions runs question presets and version comparison.
  • Top bar. The window has no title bar: drag the top bar's empty part to move the window, and double-click it to zoom. The search field on the right (/ or ⌘F) searches IDs, labels and text fields; the three buttons beside it show or hide the controls, the bottom panel and the inspector.
  • Left panel. Five tabs. Layout lists computed layouts and computes new ones. Style sets colour, size, edges, labels, the community layer and the lens. Filter holds predicates and edge types; its badge counts what is applied. Statistics shows the graph's overview, runs the analysis catalogue and shows results. Data describes the bundle and its layout, and lists running and recent jobs.
  • Canvas. The legend floats at the bottom left (its i explains the mapping). The controls at the bottom right zoom, fit, switch the lasso tool and toggle edges and labels. Drop a bundle on the window to open it, or CSV / JSONL tables to import them.
  • Bottom panel. Two tabs. Nodes lists the nodes, or the hits of a search, with their first properties; click a row to select it. Timeline, with a time role, shows the edges active per time bucket; drag across it to set the time window. Drag the panel's top edge to resize it.
  • Status bar. It reports the drawing mode (Overview when groups are shown, Detail otherwise), how many nodes are drawn individually (across the whole window, including under the panels) and how many are inside groups, how edges are drawn, and anything omitted. Read it whenever you are unsure what you are looking at. On the right, a sparkline of recent frame times against the 60 fps budget, with the 95th percentile.
Part 2Concepts

Dataset bundles

A bundle is a folder whose name ends in .atlas. Import writes it once. After that, Atlas only adds to it: analysis results, layouts, saved views and session logs.

  • Fast to open. Topology and properties are memory-mapped arrays and Arrow files, so a 40M-node bundle opens in about 3 seconds without being read into memory.
  • Checked. Every array file carries a checksum in its header. atlas-graph verify audits checksums, value ranges, the agreement of the in- and out-adjacency, the ID index and the property shards.
  • Safe to write. Every write goes to a staging folder and is swapped in atomically. A failed import never replaces an existing bundle.
  • Identified by content. The dataset_id is a hash of the content. Views, sessions and exports record it, so Atlas can warn when something was made from different data.
Format version

This version writes and reads bundle format v2. Bundles from before v2 are refused with a message to re-import: run atlas-graph import or atlas-graph generate again on the source data.

The full file list is in Bundle files.

Edge roles: type, weight, time

Edge properties are just data until you give them a role. Atlas never guesses a role from a column name. Three roles can be declared at import, and every analysis, filter and layout reads them:

RoleWhat it isWhat uses it
TypeA categorical, text, boolean or integer property naming the relation, for example mentions or reposts.The edge-type filter, --types on analyses and exports, edge-types in scripts.
WeightA number, plus what it measures: count, similarity or strength (tie strengths), or distance or cost (lengths).Tie strengths weight PageRank, HITS, Katz and communities; parallel edges sum. Lengths keep the shortest parallel edge. Path measures turn a strength into a length with a recorded transform (1/w by default).
TimeOne timestamp (start) or two (start, end), plus what they record: event, valid-interval, observed-first, observed-interval or unknown.The timeline and time window, the difference map, --window, temporal analytics and time-respecting reachability.

Why the time semantics matter. A crawler's first-seen time is not the moment a relationship began. When times are observed-* or valid-interval, temporal results such as reachability are labelled upper bounds. An event is active at its time; an interval is active while it overlaps the window.

The symmetric projection. Every import also writes an undirected version of the graph: each non-loop edge links both endpoints, and parallel and reciprocal edges merge into one entry with a multiplicity. Community detection, cores, triangles, embeddings and layouts read it, so they never need to rebuild it.

Analyses and results

Every analysis comes from one catalogue that the app, the CLI, Atlas Script and Python all share. Running one stores a result in the bundle under derived/analysis/<name>/.

  • A result has one or more columns, each numeric, categorical, a partition (communities) or a mask (yes or no per node). Most columns are per node; some are per edge, such as truss numbers or burst scores.
  • It can also hold small tables, such as a CCDF or community events, and headline statistics. When a null model has been run, a statistic also records its null mean, spread and z-score.
  • Provenance records the analysis, parameters, seed, node scope, edge selection, Atlas version and wall time.

You use a result by name wherever a column is expected: analysis:pagerank means the result's first column, and analysis:degree/in_strength names a column. Colour, size, filters, node sets, analysis scopes and layout options all accept these. To keep variants side by side, store them under different names with --name (CLI) or name= (script).

Layouts and slots

A layout is a position for every node. Each one is stored in a slot, named after its algorithm (snap-tfdp), its variant (snap-tfdp+leaves) or a name you choose with --slot. A bundle keeps every slot, and one of them is active: it opens by default.

Switch slots in the Layout panel, with layout <slot> in a script, or with atlas-graph layouts --activate <slot>. The two most recently shown layouts stay in memory, so switching between them is instant. Computing a layout replaces only its own slot.

Most algorithms are stochastic: running one again gives a different drawing of the same graph. Fix the seed to repeat a result, and compare layouts with quality metrics rather than by eye.

What the canvas draws

Atlas never draws 40 million discs at once. Each time the view moves, it decides in the background what to draw for every part of the screen. The status bar always says what it chose.

Overview groups + aggregate edges Closer groups where dense, else nodes Bright Ledger Detail original nodes, edges, labels
The same data at three zoom levels. The node-or-group boundary follows density, so sparse areas show real nodes even in the overview.
  • Groups are cells of a spatial index: everything drawn inside one small area of the screen. They are drawn as a soft density glow in their members' colour. Dense cores glow brighter. A group is not a community or a cluster; the inspector calls it an "overview group (spatial cell)". The Style panel sets whether a group shows the mean or the max of its members' values. Max keeps hubs and outliers visible.
  • Individual nodes are drawn wherever few enough are in reach, and everywhere once at most 500 000 nodes are in view. In a sparse view, nodes grow up to 3.5× to stay visible.
  • Edges are drawn as originals while the area's edges fit a budget of 1 million. Beyond that, Atlas draws aggregate connections: exact directed edge counts between cells about 12 px wide, with width growing with the count. If even these overflow the screen, the shortest edges or strongest connections are kept and the rest are counted as "omitted".
  • Fan glyphs appear in layouts with stripped leaves (+leaves slots). A hub's leaf disc that is under about 24 pt across is drawn as one translucent disc with a "+N" count. Zoom in to see the leaves.
  • Edges blend from the source's colour to the target's, so you can see direction and which groups an edge connects. Changes of representation crossfade instead of popping.

You can zoom in until single coordinate steps are a few pixels apart, about 25 000× the fit-all view on a 40-million-node graph.

Selection, focus, node set, filter

Atlas has several ways to single out nodes. They are separate on purpose, and they combine. Knowing which is which explains most of what the canvas does.

Selection

Click · select · Esc clears

One node, edge or overview group. The inspector shows it, and its own edges and neighbours are highlighted (up to 4 000 edges for a hub) without dimming the rest.

Focus

N · focus · doi · path · reach

A neighbourhood, a path or a reachable set drawn as an overlay above everything else. Context edges fade only where focus edges cross them.

Node set

Shift-drag lasso · charts · matrix · set

Any number of nodes that you build and combine with replace, add, subtract and intersect. Members get a halo; groups holding members get a ring.

Display filter

Filter tab · filter

Typed predicates that hide nodes failing them, and their edges. The time window and edge-type choices hide edges only.

Search hits are a fifth, lighter scope: they are marked and labelled on the canvas. When you export a subgraph, Atlas uses the first of these that exists: focus, then node set, then the selected node's neighbourhood, then the display filter, then the search hits.

Script, sessions and provenance

Every change you make to what is shown is recorded as an Atlas Script command, whether it came from a widget, a shortcut, a script or undo. This happens automatically, and it gives you four things:

  • Undo and redo (⌘Z / ⇧⌘Z) over view state: layout, camera, style, filters, search, selection, node set and focus. Computed analyses and layouts are results, so they stay.
  • A session log in <bundle>/derived/sessions/, headed with the dataset and its dataset_id. Camera moves and slider drags are recorded once they settle.
  • Replay. Running a session file reproduces its final view, in the app or in atlas-graph render.
  • Fingerprints. Each layout and analysis is identified by the checksums of its arrays. Sessions, saved views and image sidecars record them, and loading a view warns when something has changed since it was saved.
Part 3Getting data in

Import tables

The main import format is a table set: a JSON manifest that points to a nodes table and an edges table (CSV or JSONL) and declares types, roles and error policies. Start with atlas-graph preview on each table to see sampled values and proposed types.

{
  "format": "property-graph-table-set",
  "format_version": 1,
  "directed": true,
  "missing_endpoint_policy": "reject",
  "nodes": {
    "path": "nodes.csv", "format": "csv",
    "id": {"field": "id", "type": "utf8"},
    "label": "label",
    "null_tokens": ["NULL"],
    "properties": {
      "label":     {"type": "utf8"},
      "platform":  {"type": "categorical"},
      "followers": {"type": "int64"},
      "verified":  {"type": "bool"}
    }
  },
  "edges": {
    "path": "edges.csv", "format": "csv",
    "source": "source", "target": "target",
    "properties": {
      "kind":   {"type": "categorical"},
      "count":  {"type": "int64"},
      "seen":   {"type": "timestamp", "unit": "s"}
    },
    "roles": {
      "type":   "kind",
      "weight": {"field": "count", "kind": "count"},
      "time":   {"start": "seen", "semantics": "observed-first"}
    }
  }
}

Property types

bool, int64, uint64, float32, float64, utf8 (text), categorical (a small set of repeated values, stored as codes), and timestamp with a unit (s, ms, us or ns) and optional tz. Timestamps may also be ISO 8601 text, such as 2026-11-04T08:15:00Z, 2026-11-04 08:15:00.25 or 2026-11-04; without an offset they are UTC.

Atlas keeps null, empty text and NaN apart, keeps 64-bit integers exact (including values above 253), and keeps original node IDs exactly as given.

Error policies

SettingValuesMeaning
invalid_record_policyreject · drop · null-valueA record that does not parse: fail the import (default), drop and count it, or null the bad value.
missing_endpoint_policyreject · drop-edge · placeholderAn edge pointing to an unknown node: fail, drop the edge, or create a placeholder node with null properties.
duplicate_id_policyreject · keep-firstTwo nodes with one ID: fail, or keep the first.

Every repair is counted in the manifest and listed in diagnostics/import.jsonl. The Dataset panel shows them under import repairs.

Roles from the command line

These flags replace any roles that the source declares:

atlas-graph import graph.json --out data/mine.atlas \
  --edge-type kind --weight count:count --time seen:observed-first
# an interval: --time start:end:valid-interval

atlas-graph info <bundle> prints the declared semantics. Large edge tables are joined to node IDs in memory or, when they don't fit, by an external sort-merge join (--join auto|hash|external).

The import wizard

File ▸ Import… accepts either a manifest or node-link file, or a nodes table plus an edges table. With tables, you get a provisional preview and then choose:

  • the role of each column: node ID, edge source and target, or property;
  • each property's type and the null tokens;
  • the edge roles: type, weight and its kind, and time and its semantics;
  • the error policies.

If the import is rejected, the wizard reopens with the reason and confirms that nothing was published.

Synthetic graphs

atlas-graph generate writes seeded graphs with known structure. They are useful for learning Atlas, testing a workflow, and checking that an analysis finds what was planted.

TopologyWhat it plants
sbmCommunities of --community-size nodes (a stochastic block model).
core-peripheryA heavy fringe of sources around mega-hubs, shaped like real social data.
bow-tieA giant strongly connected core with IN, OUT, tendrils and tubes.
temporalTimed edges with community births, merges, splits and a burst.
bipartiteTwo node classes with edges only between them.
mixed (default), hubs, chain, grid, dense, dag, scc-chain, isolatesStress shapes for layout and rendering.

Generated edges carry a type, an integer weight and times, with their roles declared. --format csv|jsonl|node-link writes interchange files instead of a bundle, which is handy for testing an import.

Graphs from vectors

If you have embeddings instead of edges, atlas-graph knn turns them into a graph. It reads an Arrow IPC or Parquet table with a vector column and links each row to its k nearest neighbours. The other columns become node properties, the similarity becomes a similarity weight, and the result is laid out with graph NE.

atlas-graph knn docs.parquet --vector embedding --id doc_id --k 10 --metric cosine --out data/docs.atlas
Part 4Exploring in the app

Search and the inspector

Press / or ⌘F and type. An exact ID or ID prefix matches at once. Text and categorical fields, labels first, are then searched by case-insensitive substring in the background. Hits are listed in the table under the canvas, marked on the canvas and labelled. Click a row to go to that node.

The inspector on the right shows the current selection.

  • A node: its exact property values and analysis values, and its in- and out-neighbours, paginated. It also offers focus and degree-of-interest buttons, shortest paths, PPR ("where its flow goes" and "what feeds it"), Find similar, Suggest links, reach out and reach in, Profile its group and make meta-node.
  • An edge: its endpoints and properties.
  • A group: member count, edges inside, out and in, the dominant category's share, the highest-degree members, and zoom into group.

Neighbourhoods and paths

Degree-of-interest focus

Press N (one hop) or ⇧N (two hops) with a node selected. Instead of every neighbour, which can be millions for a hub, you get the 300 most interesting nodes nearby, each connected back to the seed by its path. Interest is PageRank when a result is stored, otherwise degree. Nodes in the node set get a bonus, and distance counts against a node.

A node with hidden neighbours carries a +k badge. Click it, or run expand <node>, to show its 20 most interesting hidden neighbours, even beyond the hop limit.

Exact neighbourhoods

The inspector and focus out|in|both <hops> show every node within k hops, up to 20 000 nodes. Direction matters: out follows edges, in walks them backwards.

Shortest paths

path <from> <to> or the inspector finds the shortest directed path and shows it as the focus. The search is bounded. "Not found within budget" means the search stopped early, which is different from "no path".

Time-respecting reachability

With a time role, reach out and reach in focus on the nodes a node can reach, or that can reach it, along paths whose edges follow each other in time. Paths start at the time window if one is set. The title says "upper bound" when times are observations rather than events.

Colour, size and labels

In the Style panel, choose a source for colour and for size: in-degree or out-degree, a node property, or an analysis column. A bundle with a Leiden result opens coloured by community.

SettingOptions
Color scaleA continuous ramp, or classes, one palette colour each: equal interval (equal widths on the transform), quantile (equal counts), Jenks natural breaks (classes as uniform inside as possible) or custom breaks. The field opens an editor with the values' minimum, mean and maximum, a histogram on a linear or log axis coloured as the canvas draws it, and one row per class with its range and node count. Drag a break's handle under the histogram or type a bound to make the breaks custom; Add break splits the widest class, × merges a class into the one above. A value at a break belongs to the class above it.
Transformauto (log for heavy-tailed values such as degree or PageRank, sqrt for skewed ones; the legend says which and why), linear, log, sqrt, quantile. It shapes the continuous ramp, equal intervals and Jenks. On log, values ≤ 0 draw at the low end and are counted.
Paletteember (the default), ice, ash, viridis, plasma, magma, inferno (all lifted above their near-black ends for the black canvas), or categorical.
Categories15 colours plus a grey "Other". Communities cycle colours over every community of meaningful size.
Top-k in viewcolour only the largest in view: only the k (4–12, default 8) largest categories in the current view get a colour, and the rest are grey. The ranking follows the camera. These colours stay distinguishable under protan, deutan and tritan colour-vision deficiencies.
SimulateShow the canvas and legend as seen with protan, deutan or tritan vision, to check a colouring.
GroupsMean or max of members' values.
DomainFixed low and high values, or the data range (domain auto).
SizeSize maps to disc area, between a minimum and the max diameter; node size px sets the default.

The legend draws the active palette with ticks, or each class with its range and count, and states the population, nulls, the aggregation rule and any automatic choice.

Edge drawing

  • Edges, arrowheads, labels: toggles, also on E and L.
  • Tapered edges are wedges, three times the edge width at the source narrowing to a point at the target: a direction cue that reads better than arrowheads in dense areas. Each wedge carries the ink of a plain edge, so tapering does not brighten the drawing.
  • Edge ink: per edge (every edge equal), ÷ length (long edges fade so they don't dominate), or ÷ out-degree (each source's fan shares one unit of ink).
  • With a highlight, fade only the edges it crosses (on by default): context edges stay visible and fade only where the highlighted edges run over them.
  • Edge width and opacity: overlapping edges add up gradually, so dense bundles stay distinguishable instead of saturating.

Filters, time and edge types

Display filter

In the Filter tab, add conditions with Add condition, then Apply. A predicate is a field, an operator and a value. The field can be a node property, indeg, outdeg or analysis:<result>[/<column>]. The operators are = != < <= > >= contains is-null not-null. Predicates are exact and typed. They use three-valued logic, so a null never passes > 5 or != 5. Nodes that fail are hidden, together with their edges.

filter subclass = Telegram
filter analysis:cores >= 20        # the 20-core

Time window and timeline

With a time role, the Timeline tab of the panel under the canvas (View ▸ Timeline) shows how many edges are active in each time bucket. Drag across it to draw only the edges active in that window; it snaps to buckets. Edges without a time are never in a window. In a script: window 2025-02-01 2025-03-01.

Difference map

Click Use as baseline to keep the current window, then choose another window. Edges are coloured blue if active only in the baseline, grey if active in both, and orange if active only in the new window. Aggregate connections are coloured by their share of change.

Edge types

With a type role, a switch per type in the Filter tab hides edges of types that are off. While any type is off, edges with no type are hidden too.

One definition everywhere

The time window and edge types use the same edge selection as atlas-graph analyze --window/--types. "Active in a window" means the same on the canvas, in an analysis, in the status bar counts and in exports.

The node set and charts

The node set collects nodes from many views so you can combine, inspect and export them.

  • Lasso: Shift-drag on the canvas. On its own it replaces the set; with ⌘ it adds and with ⌥ it subtracts.
  • Predicates and ranges: set replace where analysis:leiden = 3, set sub range indeg 0 2.
  • From other scopes: set add search, set intersect focus, set replace filter, set add nodes <id> <id>.
  • From windows: matrix cells, alluvial bars, similar-node lists and community profiles all have "node set = these" actions.

Members drawn individually get a halo. A group that holds members gets a ring whose opacity grows with their share. The set is undoable, replays from the session log, and is the export scope when no focus is active. Make meta-node turns it into a named disc on the canvas (see Seeing communities).

Charts

View ▸ Charts opens a histogram and a binned scatterplot of any numeric node column: degrees, numeric properties and analysis columns, each on a linear or log axis. Both are full charts with ticks, gridlines and axis titles, and fill the panel's width (drag its edge to widen it). Whole-number columns such as degrees get one bar per whole value where the axis has room, and ticks without fractions. Hover a bar for its range and count, or the scatterplot for a crosshair with both values and the count in that cell; the ⇅ button swaps its axes. Both cover the nodes that pass the display filter. The node set is overlaid in white on its own scale, so its shape compares with the whole population even when it is small. Drag across a chart to set the node set to that range: plain replaces, ⌘ adds, ⌥ subtracts, ⇧ intersects. Nulls, and values ≤ 0 on a log axis, are counted and shown.

Seeing communities

When you colour by a partition (Leiden, components) or a categorical property, the Style panel offers a community layer on top of the canvas:

LayerWhat it shows
RegionsOutlines, tints and labels for the area each community dominates in the view, computed from a sample of the visible nodes once the camera settles.
Meta-graphAt overview zoom (up to 1.5× the fit view), each community becomes one disc at its members' centroid, sized by member count. Lines between discs show edge counts, with an arrow where one direction carries most of them. Zoom in to see members again.
CompositeMixes the colours of all categories by their local share, so mixed areas show as blends rather than as the majority colour.
BundledMeta-graph connections bend towards the centres of super-communities. Each direction is its own lane, with its own width and arrowhead.

Meta-nodes. In the inspector, make meta-node (or meta-node <name>) keeps the current node set as a named disc at its members' centroid. Edge counts between meta-nodes are shown in both directions. A meta-node stores the set commands that define it, so it undoes and replays.

Diffuse communities

In force layouts, a community's members can be spread across the map, so meta-graph discs overlap. The community-first layout keeps communities apart.

Community windows

Communities window

View ▸ Communities needs colouring by a partition or category. Its charts fill the window, so resize it to see more detail. It has three tabs:

  • Matrix: the k (4–80) largest communities as rows (senders) and columns (receivers), ordered so similar communities sit together. Each cell compares observed edges with the number expected from the communities' volumes: blue is below expected, orange is above. Click a cell or label to set the node set to those communities (⌘ adds). Double-click the diagonal to look inside.
  • Sankey: for a categorical property, the flow of edges from nodes with each value into each of the 12 largest communities, and from each community out to each value.
  • Inside one: the adjacency matrix of one community of up to 3 000 members. Dense blocks and chains sit near the diagonal. Rows send. Hover names the pair; click selects the row's node.

Community profile

With a node selected, Profile its group (or profile analysis:leiden 3) opens a summary of that community:

  • size, internal edges, edges out and in, internal density compared with the graph's, and conductance;
  • its top partner communities in each direction;
  • the most over-represented value of each categorical property;
  • mean stability (from leiden_stability) and first and last activity (with a time role);
  • members by degree.

Generated captions summarise it, and each caption states the numbers it rests on, for example "Internal density is 9× the graph's (1.12e-3 vs 1.20e-4)". Buttons set the node set to the members or zoom to them.

Hive and BioFabric

View ▸ Arrangement draws a bounded subgraph with fixed rules instead of forces, so the same subgraph always gives the same picture. The scope is the node set, else the focus, else the 200 largest communities, up to 2 000 nodes (the highest-degree ones).

  • Hive: three axes, for nodes that only send, both send and receive, or only receive within the subgraph. Position along an axis is degree rank, and curves are coloured by source.
  • BioFabric: each node is a horizontal line, and each edge is a vertical segment between two lines, so nothing overlaps.

Lenses

A lens is a circle under the pointer that shows what is underneath in a different way. Choose a mode in the Lens section of the Style tab, or pin the lens in place with lens-at.

  • Raw edges: the original nodes and edges, even where the canvas shows aggregates.
  • Category: one category or community in focus, everything else faded.
  • Fisheye: magnifies the nodes and edges inside the circle.

Over 40 000 nodes or 30 000 edges, the lens shows a uniform sample and its caption states the rate.

Communities over time

Run the temporal analysis (it needs a time role), then open View ▸ Communities over time. Each time slice shows its 12 largest communities as bars, with ribbons for members that move between consecutive slices. A community keeps its colour while most of its members stay together, so births, merges and splits show as colour changes. Click a bar to set the node set to its members.

Comparing versions

When you have two bundles of the same graph from different dates, File ▸ Compare with earlier version… (or compare <bundle>) matches nodes by original ID. The Version comparison window reports:

  • nodes and distinct directed edge pairs added and removed;
  • rising and falling nodes, by the change in their in-degree z-score;
  • Leiden communities across the versions, as a table with their NMI;
  • every statistic both versions store.

On the canvas, edges that are new since the earlier version are orange, and the rest are grey. Removed edges have no place in the newer layout, so they are only counted. atlas-graph diff <older> <newer> [--json report.json] writes the same report from the command line.

Similar nodes and link suggestions

After running fastrp, the inspector's Find similar lists the 20 nodes with the most similar neighbourhoods. Each row shows the cosine score, the number of shared neighbours, and whether the match is in the same community. A warning appears when many matches tie, as the leaves of one hub do. node set = these collects them.

Suggest links ranks two-hop nodes by Adamic–Adar and resource allocation and draws them as dashed lines. On the command line: atlas-graph similar, atlas-graph suggest, and atlas-graph index to build an HNSW index for fast repeated queries.

Question presets

Questions ▸ Ask a question… lists presets that answer common questions with a short script. Node parameters fill in from the selection.

PresetWhat it does
What feeds this nodeReverse personalised PageRank from the node, colour by it, and a degree-of-interest focus on in-edges.
Where does its flow goThe same, forwards.
Bridges between two groupsBetweenness over two groups of a partition.
Nodes like this oneNearest nodes in the FastRP embedding.
What changed since another versionVersion comparison against a bundle you pick.

You can add your own presets; see Write your own question preset.

Part 5Analyses

Running analyses

There are four ways to run the same catalogue:

atlas-graph analyze data/g.atlas                                    # the standard set
atlas-graph analyze data/g.atlas --only pagerank --param weighted=true
atlas-graph analyze --list                                          # every analysis and its parameters

# Atlas Script, in the app
analyze ppr seeds=ch-bright-ledger direction=reverse name=feeds

# Python
g.run("leiden", resolution=2)

In the app, the Analysis panel lists the catalogue with each analysis's parameters, runs it as a background job with progress and cancel, and shows the stored results with their statistics. Distribution fits show their CCDF, and null models show observed values against the null.

The standard set is degree, dist, decompose, wcc, scc, bowtie, reciprocity, cores, pagerank and leiden.

Narrowing what an analysis sees

OptionEffect
--types a,bKeep only these edge types (needs a type role).
--window from,toKeep edges active in the interval (ISO 8601 or µs; needs a time role).
--min-weight wDrop lighter edges (needs a weight role).
--scope result/columnRestrict to the subgraph induced by a mask, for example decompose/core.
--scope result/column=kRestrict to rows equal to k, for example one component (wcc/component=0) or one community.
--name nStore under another name, to keep variants side by side.

Nodes outside a scope get no label or a score of 0. The scope and edge selection are recorded in the result's provenance.

The catalogue

Grouped by the question each analysis answers. Timings are for a graph of 40 million nodes and 93 million edges on a Mac Studio with Apple M2 Ultra and 64 GB of memory.

AnalysisAnswersNotes
Shape of the graph
degreeHow many links each node sends and receives; strength with a weight role.Standard.
distWhat do the degree distributions look like? CCDFs with power-law, log-normal and cutoff fits, and likelihood-ratio verdicts.Never just says "scale-free". 0.7 s.
decomposeWhich nodes are core and which are fringe? Roles (source, sink, transit, isolated), the transit core, the 2-core, leaves by hub, and groups with identical neighbours.On a 40-million-node graph, 96.6% of nodes are sources. 1.3 s.
wcc, sccWeak and strong components, numbered by size.Standard.
bowtieWhere does each node sit relative to the giant strongly connected component: in it, feeding it, fed by it, in tendrils or tubes?Plus signed hop distance to the core. 2.1 s.
condensationHow far upstream or downstream is each node, in the DAG of strongly connected components?For flow, citation and dependency graphs. 5.7 s.
reciprocityHow often are links returned, corrected for density (ρ), and per node?0.7 s.
Cohesion and dense structure
coresCore number and onion layer of each node. Use filter analysis:cores >= k to show the k-core.2.5 s.
klcoreDirected (k,l)-core: at least k in-neighbours and l out-neighbours inside it, plus the frontier.k, l, frontier_k.
trussk-truss number of each edge and node: how many triangles hold it in place.Edge column. 139 s.
densestThe densest subgraph, and for directed graphs the densest set of senders and receivers.Approximation with a guarantee. 805 s.
triadsCounts of the 16 directed triad classes, with optional z-scores against a null.Exact up to exact-limit edges, sampled above. Scope to a core.
Importance and flow
pagerankWhere does a random walker spend its time?weighted=true uses a tie-strength weight.
pprWhere does flow from these seeds go (forward), or what feeds them (reverse)?Local push: 0.04–0.23 s per query.
hitsHubs that point to good authorities, and authorities pointed to by good hubs.within=<partition> computes per group. 12.5 s.
katzWalks of every length arriving at a node. Stays meaningful on near-acyclic graphs.9.7 s.
betweennessWhich nodes lie on many shortest paths?Adaptive sampling, within ε of exact. Scope to a core on large graphs (138 s on the core of a 40-million-node graph).
Distance and reach
hyperballHarmonic centrality, how many nodes each node reaches in h hops and in total, the distance distribution and the effective diameter.Approximate (about 13% per node at 64 registers). 6.8 s.
Communities
leidenCommunities, always connected, with a hierarchy and quality statistics.Standard. Modularity with resolution, or CPM. warm_start from an earlier version. 20 s.
leiden_ladderCommunities at several resolutions, to choose a scale.Counts, quality and NMI per rung.
leiden_stabilityHow stable are the communities across seeds? A consensus partition and per-node stability.5 runs: 128 s.
infomapCommunities of directed flow (the map equation).Capped at 3M nodes; scope to a core. 32 s on the core.
rolesIs a node a hub inside its community, a connector between communities, or peripheral? Within-group z and participation.In- and out-variants for directed graphs. 2.2 s.
mixingWhich groups link to which, against chance; assortativity; per-node local assortativity.0.6 s.
louvainSequential Louvain, kept for comparison.Its communities can be disconnected.
Similarity and prediction
fastrpNode embeddings, for Find similar, atlas-graph similar and cands.64 dimensions. 19 s.
candsPredict a missing categorical property from the graph (Correct & Smooth).Reports held-out accuracy. 36.6 s.
oddballWhich nodes have unusual neighbourhoods, such as stars and near-cliques?Plot ego_nodes against ego_edges in Charts. 7.3 s.
Statistics and time
nullIs a statistic surprising? Degree-preserving random replicas give z-scores for reciprocity, assortativity, rich club and modularity.10 replicas: 90 s.
temporalHow does the graph change over time slices? Per-slice metrics, community events, rising nodes, change points, bursts, and whether time order matters for paths.slice=7d. Needs a time role.
maglapA direction-aware spectral embedding.Experimental: needs --experimental; up to 100 000 nodes.

Reading results with care

  • Compare with chance. A modularity of 0.83 means more when the null model gives 0.06. Run null before reading a statistic as evidence.
  • Check the scale and stability of communities. Use leiden_ladder to see how communities change with resolution, and leiden_stability to see which nodes move between runs. Resolution 1 is a default, not a finding.
  • Know which numbers are estimates. HyperBall, betweenness and sampled triads report their error. Increase registers or lower epsilon when the tail matters.
  • Mind upper bounds. Temporal results from observed or interval times are labelled as upper bounds.
  • Split core and fringe. In heavy-tailed graphs, most nodes are one-link sources. decompose separates them so averages describe the part you care about.
  • Check the higher-order indicator. temporal reports whether time order constrains paths. If it does, static flow measures such as PageRank and betweenness overstate flows.
Part 6Layouts

Choosing an algorithm

Compute layouts in the Layout panel, with atlas-graph layout --algorithm …, or with compute <algorithm> in a script. Large ones use the GPU with --gpu or the panel's GPU toggle.

AlgorithmPick it whenCharacter
snap-tfdpYou want a fast, good default for a large graph.Tight, well-separated clusters; low memory; GPU. Ignores weights. 42.7 s on a 40-million-node graph.
multilevelYou need edge weights, deterministic output per seed, or even spacing.Classic spring-electrical with coarsening; large levels on the GPU. --repulsion linear|fa2 weights repulsion by degree.
graph-neThe graph is fairly uniform and local cluster separation matters most.Graph t-SNE style. On heavy-tailed graphs the fringe crowds into a halo.
community-firstYou want a map where communities stay apart and their neighbours are near.Lays out the community graph, then each community inside its disc. Best local quality on a 40-million-node graph; global distances inside the map are not kept. 116 s. --hyperbolic gives focus + context.

Run stochastic layouts with several seeds before drawing conclusions from their shape.

Leaves and connectors

In social and web graphs most nodes are leaves: they have one link. A force layout spends almost all its effort on them, and they bury the structure. Strip leaves (--strip-leaves) takes them out of the force problem. The core is laid out first, then each hub's leaves are placed as a sunflower disc beside it, pointing away from the hub's other neighbours. Strip connectors (--strip-connectors) does the same for groups of nodes with identical neighbour sets, placing them at the centre of their neighbours.

  • The result is stored in a separate <algorithm>+leaves slot, so you can compare it with the plain layout.
  • --leaf-order <property|analysis:…> sorts leaves from the disc centre outwards, so an attribute reads as rings.
  • On the canvas, small leaf discs become fan glyphs.
  • On a 40-million-node graph, 89.5% of nodes leave the force problem, and SNAP-tFDP drops from 42.7 s to 12.7 s.

Stable layouts and constraints

Stay close to an earlier layout

When you lay out a new version of a graph, people expect things to stay where they were. --anchor-from <bundle> (or stay close to the current layout in the panel) matches nodes by original ID and starts from the old positions. Afterwards it rotates, scales and shifts the result onto the old drawing. --anchor-weight (0–1, default 0.8) sets how strongly, and . anchors to the bundle's own layout. The remaining difference is recorded in the layout's metadata.

Soft constraints

  • Radius by role (community-first, --radial out-share|depth): inside each community disc, sources move to the rim and sinks to the centre, or upstream nodes to the rim.
  • Category regions (any algorithm, --category-regions <property>, --category-strength): each category moves towards its own place on a ring and contracts, so categories read as regions.

Measuring layout quality

atlas-graph layout-quality <bundle> --layout <slot> scores a layout on samples. Every metric is scale-invariant, so slots compare directly.

MetricAsks
npAre a node's graph neighbours also its nearest neighbours in the drawing? (NP₁, NP₂)
globalDo drawn distances follow hop distances? (Spearman ρ, stress)
trustAre nearby nodes in the drawing really near in the graph (trustworthiness), and are graph neighbours kept together (continuity)?
silhouetteDo communities form separate regions? Needs --partition.
leavesAre leaves hidden under other nodes, and how far are they from their hub?

On a 40-million-node graph, stripping leaves trades local fidelity for global order and less overlap: NP₂ falls from 0.205 to 0.052, Spearman ρ rises from 0.475 to 0.566, and leaf occlusion falls from 0.904 to 0.736.

Part 7Save and share

Views

File ▸ Save view… (or saveview <name>) stores the camera, layout, style, filters, time window and edge types as <bundle>/views/<name>.json. A view remembers its layout and the fingerprints of what it read. Loading it warns, rather than refusing, if the data, layout or an analysis has changed since. atlas-graph render and atlas-graph share both accept --view.

Undo, history and replay

  • Edit ▸ Undo / Redo (⌘Z / ⇧⌘Z) step through view states.
  • Edit ▸ Session history… lists the recorded commands. Copy them, save them as a script, or re-run one.
  • File ▸ Save session as script… writes the session; File ▸ Run script… runs any script file.
  • A session opens with the commands that produce its starting view, so a replay starts from the same place.

Exports

ExportWhat you get
Subgraph
File menu · exportsub
The current scope as a re-importable table set: nodes.csv and edges.csv with every property (\N for null), a typed manifest.json, and provenance.json with the source, scope, counts and any truncation.
Graph
File menu · export-graph · atlas-graph export
GEXF 1.3 or GraphML for Gephi, Cytoscape or networkx, with every property, the shown positions, colours and sizes, and every analysis as a node column. Edges follow the time window and type filter.
Image
File menu · export-image
The view at 2× as a PNG, rendered in tiles, with a JSON sidecar recording what it shows.
Positions
File menu · export-positions
CSV of original ID, x and y, with a metadata sidecar.

Headless rendering

atlas-graph render draws a view without a window. A saved view and then a script set the layout, camera, style, filters, time window and edge types, as the app would. Commands that only make sense interactively, such as selection, panels, lenses and jobs, are skipped and listed.

atlas-graph render data/g.atlas --view data/g.atlas/views/brief.json --out fig.svg
atlas-graph render data/g.atlas --script session.atlas-script --out fig.png --width 2400 --height 1600

PNG is the GPU render with level of detail. SVG writes groups as soft discs, edges as lines, individual nodes as circles, and the legend. Both are deterministic: the same view and script give byte-identical files.

Offline share bundles

atlas-graph share writes a folder that anyone can open in a browser, with no server, internet connection or installation:

atlas-graph share data/g.atlas --view data/g.atlas/views/brief.json --out share/brief/
# scopes: view (default), all, or an analysis scope such as leiden/community=3 or decompose/core

It contains the positions, colours and sizes as the app maps them, the edges between the included nodes, labels and the legend. In the viewer, drag to pan, scroll to zoom, F fits, V returns to the saved view, and hovering shows a label. Scopes over --max (1 million) nodes or edges are sampled uniformly, and the subtitle says so.

Python

The atlas_graph Python package (pip install atlas-graph) reads bundles without copying them, runs analyses and layouts, and imports from your own Arrow tables.

import atlas_graph, pyarrow.compute as pc

g = atlas_graph.open("data/mine.atlas")
src, dst = g.src(), g.dst()              # pyarrow arrays over the mapped files, no copy
off, nbr, eid = g.csr("in")              # in-adjacency
pr = g.analysis("pagerank")              # a stored result column, no copy
ids = g.node_ids()                       # copied; properties too (categoricals as dictionaries)

g.run("leiden", resolution=2, name="leiden_r2")
slot = g.layout("snap-tfdp", seed=3)
print(g.quality(slot))

# from your own tables
b = atlas_graph.from_arrow(nodes, edges, "data/new.atlas", id="id", source="src", target="dst", weight="count")
atlas_graph.show(nodes, edges)           # temporary bundle, laid out, opened in atlas-app

On a graph of 93 million edges, the edge arrays reach Python in 0.13 s. show finds the app through $ATLAS_APP or the PATH.

Part 8How-to guides

Recipes

Each recipe is a complete path from a question to an answer. Replace the example IDs and file names with your own.

1Import two CSV files with edge rolesYou have nodes.csv and edges.csv with a relation column, a count and a first-seen date.
  1. Run atlas-graph preview nodes.csv and atlas-graph preview edges.csv, and note the proposed types.
  2. Write graph.json as in Import tables. Declare kind as categorical, and in roles set type, the count weight and the seen time with observed-first.
  3. Import, then check what was declared and repaired:
    atlas-graph import graph.json --out data/mine.atlas
    atlas-graph info data/mine.atlas
  4. Run the standard analyses and a layout, then open the bundle: atlas-graph analyze data/mine.atlas; atlas-graph layout data/mine.atlas --algorithm snap-tfdp --gpu.

If the import is rejected, the message names the record and rule. Fix the data, or relax the policy, for example to "missing_endpoint_policy": "drop-edge".

2Find the core of a heavy-tailed graphMost nodes have one link, and you want to study the part that matters.
  1. Run decompose and cores (both are in the standard set).
  2. In the Analysis panel, read the core/fringe split in the decompose statistics.
  3. Show only the transit core: filter analysis:decompose/core = 1. Or show a k-core: filter analysis:cores >= 20.
  4. Run expensive analyses on the core only: atlas-graph analyze data/g.atlas --only betweenness --scope decompose/core.
  5. For the layout, strip the fringe: atlas-graph layout data/g.atlas --algorithm snap-tfdp --gpu --strip-leaves --strip-connectors.
3Find communities you can defendYou need communities that are real, stable and at the right scale.
  1. Run leiden. Check that its disconnected count is 0 and note the modularity.
  2. Run leiden_ladder with resolutions=0.25,0.5,1,2,4,8. Choose the resolution where the community count and NMI to the previous rung level off, then run leiden with that resolution and a name.
  3. Run leiden_stability. Colour by analysis:leiden_stability/stability to see which nodes switch between runs.
  4. Run null with partition=leiden to compare modularity against degree-preserving random graphs.
  5. Open View ▸ Communities: the matrix shows which communities link more than expected. Use Profile its group to describe one, with its captions.
4Answer "what feeds this node?"You want the sources whose flow, directly or indirectly, ends up at one node.
  1. Search for the node and select it.
  2. Questions ▸ Ask a question… ▸ What feeds this node, then Ask. The seed fills in from the selection.
  3. The canvas is coloured by reverse personalised PageRank, with a degree-of-interest focus on in-edges. Click +k badges to expand.
  4. To keep the answer, run set replace focus and export with File ▸ Export subgraph.

The same in a script: analyze ppr seeds=<id> direction=reverse name=feeds; color analysis:feeds; doi in 2 300 <id>.

5Get a readable layout of a huge graphThe default drawing is a hairball with a fuzzy halo.
  1. Compute a baseline and a stripped variant:
    atlas-graph layout data/g.atlas --algorithm snap-tfdp --gpu
    atlas-graph layout data/g.atlas --algorithm snap-tfdp --gpu --strip-leaves --strip-connectors
  2. For a map of communities, run leiden and then atlas-graph layout data/g.atlas --algorithm community-first.
  3. Compare them: atlas-graph layout-quality data/g.atlas --layout community-first --metrics np,trust,silhouette --partition leiden.
  4. In the app, switch slots in the Layout panel. Turn on meta-graph or regions in Style to label communities.
6Compare two time windowsWhat is new in March compared with February?
  1. Make sure the bundle has a time role (atlas-graph info). Otherwise re-import with --time.
  2. Drag across February on the timeline, then click compare: use as baseline.
  3. Drag across March. Orange edges are new in March, blue edges were only in February, and grey edges were in both.
  4. Run the same comparison for analyses: atlas-graph analyze data/g.atlas --only leiden --name leiden_mar --window 2025-03-01,2025-04-01.
  5. For longer histories, run temporal slice=7d and open View ▸ Communities over time.
7Compare two versions of a graphYou re-crawled the data and want to know what changed, without the map jumping around.
  1. Import the new data as a separate bundle.
  2. Lay it out anchored to the old one: atlas-graph layout new.atlas --algorithm snap-tfdp --gpu --anchor-from old.atlas.
  3. Keep community labels comparable: atlas-graph analyze new.atlas --only leiden --param warm_start=old.atlas:leiden.
  4. Report: atlas-graph diff old.atlas new.atlas --json changes.json, or open the new bundle and choose File ▸ Compare with earlier version….
8Find look-alikes and fill in missing labelsWhich accounts behave like this one, and what platform are the unlabelled ones on?
  1. Run fastrp.
  2. Select a node and click Find similar in the inspector. Read the shared-neighbour and same-community columns, not just the score. Heed the tie warning.
  3. For repeated queries over millions of nodes, build an index: atlas-graph index data/g.atlas.
  4. To predict a property: atlas-graph analyze data/g.atlas --only cands --param property=subclass. Check the held-out accuracy in its statistics before using the predictions.
9Build a node set and export itYou need the high-PageRank Telegram channels in one region, as CSV.
  1. Shift-drag a lasso around the region.
  2. Narrow it: set intersect where subclass = Telegram.
  3. Open View ▸ Charts, choose PageRank on a log axis, and ⇧-drag across the top of the histogram to intersect.
  4. File ▸ Export subgraph writes the set with every property, a manifest and provenance. Export graph writes GEXF for Gephi.
10Make a reproducible figureA figure for a report that you can regenerate exactly next month.
  1. Set up the view in the app, then File ▸ Save view… as brief.
  2. Render it: atlas-graph render data/g.atlas --view data/g.atlas/views/brief.json --out brief.svg.
  3. Keep the session file from derived/sessions/ with the figure. It records every step and the fingerprints of the layout and analyses.
  4. Re-render later with the same command; the output is byte-identical as long as the data has not changed.
11Send someone an interactive viewA colleague without Atlas needs to pan and zoom around one community.
  1. atlas-graph share data/g.atlas --scope leiden/community=3 --view data/g.atlas/views/brief.json --out share/c3/
  2. Zip the folder and send it. Opening index.html works offline in any modern browser.
12Write your own question presetYour team asks the same question every week.

Save a file such as amplifiers.atlas-preset in the presets folder (Help ▸ Show presets folder; on a Mac, ~/Library/Application Support/com.gerulata.atlas/presets):

# preset: amplifiers
# title: Who amplifies this channel
# question: Which nodes forward the most content from this channel?
# param seed node: the channel
select $seed
analyze ppr seeds=$seed direction=forward name=amplifiers
color analysis:amplifiers
doi out 2 300 $seed

It appears under Questions ▸ Ask a question…. Parameter types are node, text and bundle. Each value is substituted inside its token and the token is quoted whole, so values with spaces are safe.

13Script the app for unattended screenshotsA nightly job should produce the same view of fresh data.
ATLAS_SCRIPT="color analysis:leiden; center ch-bright-ledger; zoom 4; filter subclass = Telegram; wait 10" \
ATLAS_SCREENSHOT=view.png ATLAS_SCREENSHOT_EXIT=1 \
  atlas-app data/mine.atlas

The screenshot is taken once the script has finished and no job is running. It renders offscreen when the window is hidden. For a file without the GPU window, use atlas-graph render --script.

14Analyse a bundle from PythonYou want pandas or numpy on Atlas's results.
import atlas_graph, numpy as np
g = atlas_graph.open("data/mine.atlas")
pr = g.analysis("pagerank").to_numpy(zero_copy_only=False)
top = np.argsort(pr)[-20:][::-1]
ids = g.node_ids().to_pylist()
print([ids[i] for i in top])
Part 9Reference

Keyboard and mouse

InputAction
Drag · scroll / pinchPan · zoom at the pointer
ClickSelect a node, edge or group
Shift-drag · with ⌘ · with ⌥Lasso: replace · add to · subtract from the node set
FFit the whole graph
+ −Zoom in or out around the centre
← ↑ → ↓Pan
N · ⇧NDegree-of-interest focus, 1 hop · 2 hops
CCentre on the selection
EscClear selection and focus
E · LShow or hide edges · labels
/ or ⌘FSearch
⌘Z · ⇧⌘ZUndo · redo a view change
?Show the shortcut list

Atlas Script commands

Commands are separated by ; or newlines, and # starts a comment. Quote arguments that contain spaces: select "id with spaces". The whole script is checked before anything runs, and a mistake is reported with its position. Commands run one per frame and wait for jobs they start, so analyze finishes before the next command runs.

Colour and size sources: none, in-degree, out-degree, analysis:<result>, analysis:<result>/<column>, a property name, or prop:<name>.

CommandEffect
Camera
look <x> <y> <zoom>Camera at layout coordinates; zoom relative to fit (1 = whole graph).
zoom <factor>Multiply the zoom.
center <id> · fitCentre on a node, keeping the zoom · fit the whole graph.
Selection, focus and search
select <id>Select a node by original ID.
select-edge <row> · select-group <cell> · groupSelect an edge, an overview group, or the largest group in view.
focus out|in|both <hops> [id]Exact k-hop neighbourhood.
doi out|in|both <hops> <keep> [node]Degree-of-interest focus with "+k" badges.
expand <node>Show a node's 20 most interesting hidden neighbours.
path <from> <to>Shortest directed path as the focus.
reach out|in [node]Time-respecting reachability.
search <text>Search; takes the rest of the line.
clear selection|focus|filters|search|path|allClear part of the view.
Style
color <source> · size <source>Map node colour or size.
scale … · size-scale …auto, linear, log, sqrt or quantile.
palette ember|ice|ash|viridis|plasma|magma|inferno|categoricalColour palette.
groups mean|maxHow overview groups combine members' colours.
domain <lo> <hi> · domain autoFix the colour domain or use the data range.
top-k <k>|offColour only the k (≤ 12) largest categories in view.
cvd-sim none|protan|deutan|tritanSimulate a colour-vision deficiency.
classes equal-interval|quantile|jenks <n> · classes custom <break>… · classes offCut a numeric colour into classes (2–12), or set the inner breaks by hand; off returns to a continuous ramp.
label-field <property>|noneChoose the label property.
node-px · size-range <min> <max> · edge-width · edge-alphaDrawing sizes and opacity.
edge-norm none|length|out-degreeEdge ink normalisation.
show|hide <layer>edges, arrows, labels, taper, crossing-dim, contours, meta-graph, composite, bundling; panels charts, communities, arrangement, alluvial.
Filters, time and sets
filter <field> <op> <value>Add a display filter predicate.
window <from> <to> · window offDraw only edges active in [from, to).
baseline <from> <to> · baseline offDifference map against a baseline window.
edge-types <type>… · edge-types allDraw only these edge types.
set replace|add|sub|intersect <source> · set clearSources: lasso x y x y x y…, where <field> <op> <value>, range <field> <lo> <hi>…, nodes <id>…, search, focus, filter.
meta-node <name> · meta-node-remove <name>Keep the node set as a named meta-node, or remove one.
Tools and windows
lens off|raw|fisheye|category [<group>]Lens mode.
lens-at <fx> <fy> <radius> · lens-at offPin the lens (canvas fractions, radius in points).
similar <node> · suggest <node>Similar nodes · suggested links.
profile <field> <group> · profile offCommunity profile.
compare <bundle> · compare offVersion comparison.
Jobs, layouts and files
analyze <id> [name=value…]Run an analysis; name= stores it under another name.
compute <algorithm> [seed=<n>] [params=<json>]Compute a layout: multilevel, snap-tfdp, graph-ne or community-first.
layout <slot>Switch to a computed layout.
saveview <name> · loadview <name>Save or load a view.
exportsub <dir>Export the current subgraph scope as a table set.
export-graph <file.gexf|file.graphml>Export as GEXF or GraphML.
export-image <file.png> · export-positions <file.csv>Image at 2× · positions.
wait <frames> · undo · redoPause · step through view history.

Command-line tool

Run atlas-graph <command> --help for every option. Commands that read a layout take --layout <slot> and default to the active one.

CommandDoesKey options
preview <file>Sample a CSV or JSONL table and propose types and roles.
import <manifest|node-link>Build a bundle.--out --edge-type --weight f:kind --time s[:e]:sem --join --nodelink
generateSeeded synthetic graph.--topology --nodes --edges --community-size --seed --format
knn <table>Vectors to a k-nearest-neighbour graph.--vector --id --k --metric --no-layout
info · verifyManifest summary · full integrity audit.
analyzeRun and store analyses.--only --param k=v --types --window --min-weight --scope --name --list --experimental
layoutCompute a layout and make it active.--algorithm --gpu --seed --strip-leaves --strip-connectors --leaf-order --slot --anchor-from --anchor-weight --communities --hyperbolic --radial --category-regions --repulsion --weight --deterministic
layoutsList layouts or switch the active one.--activate <slot>
layout-qualityScore a layout.--metrics --partition --sample --k --out
similar <node>Nearest nodes in the FastRP embedding.--k --groups
indexHNSW index over the embedding.--scope --m --ef
suggest <node>Two-hop link suggestions.--k
diff <older> <newer>What changed between versions.--json
renderPNG or SVG of a view, headless.--out --view --script --format --width --height --color --zoom --focus --center
shareOffline browser viewer.--out --scope --view --script --max
exportGEXF 1.3 or GraphML of the whole graph.--format --color --size --analyses --types --window
export-positionsPositions as CSV.--out
snapshotQuick CPU raster of a layout.--size --edges
gpu-report · bench · bench-viewGPU capabilities · benchmarks.

Environment variables

VariableEffect
ATLAS_SCRIPTAtlas Script to run when the app starts.
ATLAS_SCREENSHOT=out.pngSave the window once the script is done and no job is running.
ATLAS_SCREENSHOT_AFTER=<s>Wait at least this long first (default 3).
ATLAS_SCREENSHOT_EXIT=1Quit after saving.
ATLAS_STATE_OUT=state.txtWith a screenshot, also write the final view state.
ATLAS_APPPath to atlas-app for Python's atlas_graph.show.

Bundle files

PathHolds
manifest.jsonSchema, edge semantics, counts, file inventory with checksums, provenance, repairs.
topology/src, dstEdge endpoints, one row per edge.
topology/out.*, in.*Out- and in-adjacency.
topology/sym.*The symmetric projection.
topology/etype, weight, t0, t1Role arrays, when declared.
ids/Original node IDs and the sorted index used for exact lookup.
props/Node and edge properties as Arrow IPC shards.
derived/analysis/<name>/Analysis results.
derived/layout/<slot>/Positions, status and metadata; active.json names the active slot.
derived/index/Embeddings and HNSW indexes.
derived/sessions/Session logs as Atlas Script.
views/Saved views.
diagnostics/import.jsonlImport repairs and rejected records.

Glossary

Aggregate connection
An exact count of directed edges between two small screen cells, drawn instead of the edges themselves.
Bundle
A .atlas folder holding one imported graph and everything derived from it.
CCDF
Complementary cumulative distribution: the share of nodes with a value at least x.
Connector group
Nodes with identical neighbour sets.
Core / fringe
Nodes that both send and receive (core) versus one-way sources, sinks and leaves (fringe).
DOI
Degree of interest: a score that picks the most informative neighbours to show.
Fan glyph
One disc standing for a hub's leaves while they are too small to see.
Group
A spatial cell of the canvas drawn as one density glow. Not a community.
Leaf
A node with exactly one neighbour.
Meta-node
A named node set drawn as one disc with its connections.
NMI
Normalised mutual information: how much two partitions agree, from 0 to 1.
Node set
The collection of nodes you build with lassos, predicates and windows.
Null model
Random graphs with the same degrees, used to judge whether a statistic is surprising.
PPR
Personalised PageRank: random walks that restart at chosen seeds.
Role
The meaning given to an edge property: type, weight or time.
Slot
A named stored layout.
Symmetric projection
The undirected version of the graph that Atlas writes at import.

Limits and caveats

  • Bundles are static: you cannot edit topology in place. Import a new version and compare.
  • Layout positions are navigational. Proximity is not evidence of a link, a community or a path.
  • Stochastic layouts and parallel Leiden differ between runs. Use seeds, deterministic=true for Leiden, or --deterministic for SNAP-tFDP when you need exact repeats.
  • SNAP-tFDP ignores edge weights; use multilevel when weights matter.
  • Some analyses are meant for a core or bounded scope on very large graphs: betweenness, triads with nulls, Infomap (capped at 3M nodes) and the experimental magnetic Laplacian (100 000 nodes).
  • Temporal results from observed or interval times are upper bounds.
  • Louvain communities can be disconnected; use Leiden.
  • Right-to-left text in labels is not shaped.
  • Edges removed between versions are counted but cannot be drawn in the newer layout.