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.
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 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.
- ImportNodes and edges become a checked, memory-mapped bundle.
atlas-graph import - AnalyseRun the standard set: degrees, components, cores, PageRank and more.
atlas-graph analyze - Lay outCompute positions for every node, on the GPU when available.
atlas-graph layout - ExploreZoom from overview to single edges. Search, inspect, colour, filter.
- AskFocus on neighbourhoods, compare groups, time windows and versions.
- 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-graphThe 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.atlasWith 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.atlasThe 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-graphWithout 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.
- 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.
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 verifyaudits 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_idis a hash of the content. Views, sessions and exports record it, so Atlas can warn when something was made from different data.
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:
| Role | What it is | What uses it |
|---|---|---|
| Type | A 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. |
| Weight | A 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). |
| Time | One 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.
- 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 (
+leavesslots). 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
select · Esc clearsOne 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
focus · doi · path · reachA 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
setAny 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
filterTyped 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 itsdataset_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.
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
| Setting | Values | Meaning |
|---|---|---|
invalid_record_policy | reject · drop · null-value | A record that does not parse: fail the import (default), drop and count it, or null the bad value. |
missing_endpoint_policy | reject · drop-edge · placeholder | An edge pointing to an unknown node: fail, drop the edge, or create a placeholder node with null properties. |
duplicate_id_policy | reject · keep-first | Two 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-intervalatlas-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.
Node-link JSON
A single JSON object with nodes and links arrays, as written by networkx and D3, imports directly. Put edge roles under property_types.edge_roles, using the same shape as a manifest's roles. Use --nodelink if a file is misdetected as a manifest.
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.
| Topology | What it plants |
|---|---|
sbm | Communities of --community-size nodes (a stochastic block model). |
core-periphery | A heavy fringe of sources around mega-hubs, shaped like real social data. |
bow-tie | A giant strongly connected core with IN, OUT, tendrils and tubes. |
temporal | Timed edges with community births, merges, splits and a burst. |
bipartite | Two node classes with edges only between them. |
mixed (default), hubs, chain, grid, dense, dag, scc-chain, isolates | Stress 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.atlasSearch 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.
| Setting | Options |
|---|---|
| Color scale | A 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. |
| Transform | auto (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. |
| Palette | ember (the default), ice, ash, viridis, plasma, magma, inferno (all lifted above their near-black ends for the black canvas), or categorical. |
| Categories | 15 colours plus a grey "Other". Communities cycle colours over every community of meaningful size. |
| Top-k in view | colour 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. |
| Simulate | Show the canvas and legend as seen with protan, deutan or tritan vision, to check a colouring. |
| Groups | Mean or max of members' values. |
| Domain | Fixed low and high values, or the data range (domain auto). |
| Size | Size 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-coreTime 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.
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:
| Layer | What it shows |
|---|---|
| Regions | Outlines, 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-graph | At 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. |
| Composite | Mixes the colours of all categories by their local share, so mixed areas show as blends rather than as the majority colour. |
| Bundled | Meta-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.
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.
| Preset | What it does |
|---|---|
| What feeds this node | Reverse personalised PageRank from the node, colour by it, and a degree-of-interest focus on in-edges. |
| Where does its flow go | The same, forwards. |
| Bridges between two groups | Betweenness over two groups of a partition. |
| Nodes like this one | Nearest nodes in the FastRP embedding. |
| What changed since another version | Version comparison against a bundle you pick. |
You can add your own presets; see Write your own question preset.
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
| Option | Effect |
|---|---|
--types a,b | Keep only these edge types (needs a type role). |
--window from,to | Keep edges active in the interval (ISO 8601 or µs; needs a time role). |
--min-weight w | Drop lighter edges (needs a weight role). |
--scope result/column | Restrict to the subgraph induced by a mask, for example decompose/core. |
--scope result/column=k | Restrict to rows equal to k, for example one component (wcc/component=0) or one community. |
--name n | Store 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.
| Analysis | Answers | Notes |
|---|---|---|
| Shape of the graph | ||
degree | How many links each node sends and receives; strength with a weight role. | Standard. |
dist | What 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. |
decompose | Which 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, scc | Weak and strong components, numbered by size. | Standard. |
bowtie | Where 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. |
condensation | How far upstream or downstream is each node, in the DAG of strongly connected components? | For flow, citation and dependency graphs. 5.7 s. |
reciprocity | How often are links returned, corrected for density (ρ), and per node? | 0.7 s. |
| Cohesion and dense structure | ||
cores | Core number and onion layer of each node. Use filter analysis:cores >= k to show the k-core. | 2.5 s. |
klcore | Directed (k,l)-core: at least k in-neighbours and l out-neighbours inside it, plus the frontier. | k, l, frontier_k. |
truss | k-truss number of each edge and node: how many triangles hold it in place. | Edge column. 139 s. |
densest | The densest subgraph, and for directed graphs the densest set of senders and receivers. | Approximation with a guarantee. 805 s. |
triads | Counts 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 | ||
pagerank | Where does a random walker spend its time? | weighted=true uses a tie-strength weight. |
ppr | Where does flow from these seeds go (forward), or what feeds them (reverse)? | Local push: 0.04–0.23 s per query. |
hits | Hubs that point to good authorities, and authorities pointed to by good hubs. | within=<partition> computes per group. 12.5 s. |
katz | Walks of every length arriving at a node. Stays meaningful on near-acyclic graphs. | 9.7 s. |
betweenness | Which 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 | ||
hyperball | Harmonic 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 | ||
leiden | Communities, always connected, with a hierarchy and quality statistics. | Standard. Modularity with resolution, or CPM. warm_start from an earlier version. 20 s. |
leiden_ladder | Communities at several resolutions, to choose a scale. | Counts, quality and NMI per rung. |
leiden_stability | How stable are the communities across seeds? A consensus partition and per-node stability. | 5 runs: 128 s. |
infomap | Communities of directed flow (the map equation). | Capped at 3M nodes; scope to a core. 32 s on the core. |
roles | Is 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. |
mixing | Which groups link to which, against chance; assortativity; per-node local assortativity. | 0.6 s. |
louvain | Sequential Louvain, kept for comparison. | Its communities can be disconnected. |
| Similarity and prediction | ||
fastrp | Node embeddings, for Find similar, atlas-graph similar and cands. | 64 dimensions. 19 s. |
cands | Predict a missing categorical property from the graph (Correct & Smooth). | Reports held-out accuracy. 36.6 s. |
oddball | Which nodes have unusual neighbourhoods, such as stars and near-cliques? | Plot ego_nodes against ego_edges in Charts. 7.3 s. |
| Statistics and time | ||
null | Is a statistic surprising? Degree-preserving random replicas give z-scores for reciprocity, assortativity, rich club and modularity. | 10 replicas: 90 s. |
temporal | How 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. |
maglap | A 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
nullbefore reading a statistic as evidence. - Check the scale and stability of communities. Use
leiden_ladderto see how communities change with resolution, andleiden_stabilityto 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
registersor lowerepsilonwhen 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.
decomposeseparates them so averages describe the part you care about. - Check the higher-order indicator.
temporalreports whether time order constrains paths. If it does, static flow measures such as PageRank and betweenness overstate flows.
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.
| Algorithm | Pick it when | Character |
|---|---|---|
snap-tfdp | You 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. |
multilevel | You 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-ne | The 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-first | You 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>+leavesslot, 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.
| Metric | Asks |
|---|---|
np | Are a node's graph neighbours also its nearest neighbours in the drawing? (NP₁, NP₂) |
global | Do drawn distances follow hop distances? (Spearman ρ, stress) |
trust | Are nearby nodes in the drawing really near in the graph (trustworthiness), and are graph neighbours kept together (continuity)? |
silhouette | Do communities form separate regions? Needs --partition. |
leaves | Are 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.
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
| Export | What 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 1600PNG 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.
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-appOn 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.
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.
- Run
atlas-graph preview nodes.csvandatlas-graph preview edges.csv, and note the proposed types. - Write
graph.jsonas in Import tables. Declarekindas categorical, and inrolessettype, thecountweight and theseentime withobserved-first. - Import, then check what was declared and repaired:
atlas-graph import graph.json --out data/mine.atlas atlas-graph info data/mine.atlas - 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.
- Run
decomposeandcores(both are in the standard set). - In the Analysis panel, read the core/fringe split in the
decomposestatistics. - Show only the transit core:
filter analysis:decompose/core = 1. Or show a k-core:filter analysis:cores >= 20. - Run expensive analyses on the core only:
atlas-graph analyze data/g.atlas --only betweenness --scope decompose/core. - 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.
- Run
leiden. Check that its disconnected count is 0 and note the modularity. - Run
leiden_ladderwithresolutions=0.25,0.5,1,2,4,8. Choose the resolution where the community count and NMI to the previous rung level off, then runleidenwith thatresolutionand aname. - Run
leiden_stability. Colour byanalysis:leiden_stability/stabilityto see which nodes switch between runs. - Run
nullwithpartition=leidento compare modularity against degree-preserving random graphs. - 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.
- Search for the node and select it.
- Questions ▸ Ask a question… ▸ What feeds this node, then Ask. The seed fills in from the selection.
- The canvas is coloured by reverse personalised PageRank, with a degree-of-interest focus on in-edges. Click +k badges to expand.
- To keep the answer, run
set replace focusand 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.
- 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 - For a map of communities, run
leidenand thenatlas-graph layout data/g.atlas --algorithm community-first. - Compare them:
atlas-graph layout-quality data/g.atlas --layout community-first --metrics np,trust,silhouette --partition leiden. - 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?
- Make sure the bundle has a time role (
atlas-graph info). Otherwise re-import with--time. - Drag across February on the timeline, then click compare: use as baseline.
- Drag across March. Orange edges are new in March, blue edges were only in February, and grey edges were in both.
- Run the same comparison for analyses:
atlas-graph analyze data/g.atlas --only leiden --name leiden_mar --window 2025-03-01,2025-04-01. - For longer histories, run
temporal slice=7dand 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.
- Import the new data as a separate bundle.
- Lay it out anchored to the old one:
atlas-graph layout new.atlas --algorithm snap-tfdp --gpu --anchor-from old.atlas. - Keep community labels comparable:
atlas-graph analyze new.atlas --only leiden --param warm_start=old.atlas:leiden. - 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?
- Run
fastrp. - 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.
- For repeated queries over millions of nodes, build an index:
atlas-graph index data/g.atlas. - 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.
- Shift-drag a lasso around the region.
- Narrow it:
set intersect where subclass = Telegram. - Open View ▸ Charts, choose PageRank on a log axis, and ⇧-drag across the top of the histogram to intersect.
- 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.
- Set up the view in the app, then File ▸ Save view… as
brief. - Render it:
atlas-graph render data/g.atlas --view data/g.atlas/views/brief.json --out brief.svg. - Keep the session file from
derived/sessions/with the figure. It records every step and the fingerprints of the layout and analyses. - Re-render later with the same command; the output is byte-identical as long as the data has not changed.
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 $seedIt 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.atlasThe 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])Keyboard and mouse
| Input | Action |
|---|---|
| Drag · scroll / pinch | Pan · zoom at the pointer |
| Click | Select a node, edge or group |
| Shift-drag · with ⌘ · with ⌥ | Lasso: replace · add to · subtract from the node set |
| F | Fit the whole graph |
| + − | Zoom in or out around the centre |
| ← ↑ → ↓ | Pan |
| N · ⇧N | Degree-of-interest focus, 1 hop · 2 hops |
| C | Centre on the selection |
| Esc | Clear selection and focus |
| E · L | Show or hide edges · labels |
| / or ⌘F | Search |
| ⌘Z · ⇧⌘Z | Undo · 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>.
| Command | Effect |
|---|---|
| Camera | |
look <x> <y> <zoom> | Camera at layout coordinates; zoom relative to fit (1 = whole graph). |
zoom <factor> | Multiply the zoom. |
center <id> · fit | Centre 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> · group | Select 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|all | Clear 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|categorical | Colour palette. |
groups mean|max | How overview groups combine members' colours. |
domain <lo> <hi> · domain auto | Fix the colour domain or use the data range. |
top-k <k>|off | Colour only the k (≤ 12) largest categories in view. |
cvd-sim none|protan|deutan|tritan | Simulate a colour-vision deficiency. |
classes equal-interval|quantile|jenks <n> · classes custom <break>… · classes off | Cut a numeric colour into classes (2–12), or set the inner breaks by hand; off returns to a continuous ramp. |
label-field <property>|none | Choose the label property. |
node-px · size-range <min> <max> · edge-width · edge-alpha | Drawing sizes and opacity. |
edge-norm none|length|out-degree | Edge 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 off | Draw only edges active in [from, to). |
baseline <from> <to> · baseline off | Difference map against a baseline window. |
edge-types <type>… · edge-types all | Draw only these edge types. |
set replace|add|sub|intersect <source> · set clear | Sources: 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 off | Pin the lens (canvas fractions, radius in points). |
similar <node> · suggest <node> | Similar nodes · suggested links. |
profile <field> <group> · profile off | Community profile. |
compare <bundle> · compare off | Version 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 · redo | Pause · 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.
| Command | Does | Key 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 |
generate | Seeded 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 · verify | Manifest summary · full integrity audit. | |
analyze | Run and store analyses. | --only --param k=v --types --window --min-weight --scope --name --list --experimental |
layout | Compute 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 |
layouts | List layouts or switch the active one. | --activate <slot> |
layout-quality | Score a layout. | --metrics --partition --sample --k --out |
similar <node> | Nearest nodes in the FastRP embedding. | --k --groups |
index | HNSW index over the embedding. | --scope --m --ef |
suggest <node> | Two-hop link suggestions. | --k |
diff <older> <newer> | What changed between versions. | --json |
render | PNG or SVG of a view, headless. | --out --view --script --format --width --height --color --zoom --focus --center |
share | Offline browser viewer. | --out --scope --view --script --max |
export | GEXF 1.3 or GraphML of the whole graph. | --format --color --size --analyses --types --window |
export-positions | Positions as CSV. | --out |
snapshot | Quick CPU raster of a layout. | --size --edges |
gpu-report · bench · bench-view | GPU capabilities · benchmarks. |
Environment variables
| Variable | Effect |
|---|---|
ATLAS_SCRIPT | Atlas Script to run when the app starts. |
ATLAS_SCREENSHOT=out.png | Save 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=1 | Quit after saving. |
ATLAS_STATE_OUT=state.txt | With a screenshot, also write the final view state. |
ATLAS_APP | Path to atlas-app for Python's atlas_graph.show. |
Bundle files
| Path | Holds |
|---|---|
manifest.json | Schema, edge semantics, counts, file inventory with checksums, provenance, repairs. |
topology/src, dst | Edge endpoints, one row per edge. |
topology/out.*, in.* | Out- and in-adjacency. |
topology/sym.* | The symmetric projection. |
topology/etype, weight, t0, t1 | Role 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.jsonl | Import 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
.atlasfolder 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=truefor Leiden, or--deterministicfor 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.