anvi-script-gen-pan-graph-video
Table of Contents
Render an MP4 'growth' animation of a pangenome graph directly from a pan-graph-db by recomputing the graph's layout for growing genome subsets through the same PangraphInteractive backend anvi-display-pan-graph uses..
🔙 To the main page of anvi’o programs and artifacts.
Authors
Requires
Provides
This program does not seem to provide any artifacts. Such programs usually print out some information for you to see or alter some anvi’o artifacts without producing any immediate outputs.
Usage
No one has described the usage of this program :/ If you would like to contribute, please see previous examples here, and feel free to add a Markdown formatted file in that directory named “anvi-script-gen-pan-graph-video.md”. For a template, you can use the markdown file for anvi-gen-contigs-database. THANK YOU!
Command line interface
The following is the list of parameters and their descriptions in the latest version of anvi-script-gen-pan-graph-video.
The code that generates this web page ensures that this information is the latest available in 9-dev (eunice). Which means, in some cases the information in this section (generated automatically) might be more comprehensive or up-to-date compared to the descriptions above (written by humans).
Command line usage
anvi-script-gen-pan-graph-video [-h] -p PAN_GRAPH_DB [--component COMPONENT] [--genomes-of-interest GENOMES_OF_INTEREST] [--exclude-genomes EXCLUDE_GENOMES] [--max-num-genomes-to-render MAX_NUM_GENOMES_TO_RENDER] [--inset-flanks LEFT_NODE,RIGHT_NODE] [--inset-aspect INSET_ASPECT] [--inset-graph-nodes-cover-window-dynamically] [--show-rarefaction] [--rarefaction-iterations RAREFACTION_ITERATIONS] [--resolution RESOLUTION] [--rotation-offset-deg ROTATION_OFFSET_DEG] [--outer-radius-fraction OUTER_RADIUS_FRACTION] [--inner-radius-fraction INNER_RADIUS_FRACTION] [--graph-height-fraction GRAPH_HEIGHT_FRACTION] [--backbone-gap-px BACKBONE_GAP_PX] [--track-height-px TRACK_HEIGHT_PX] [--supersample SUPERSAMPLE] [--main-graph-node-size MAIN_GRAPH_NODE_SIZE] [--main-graph-node-color MAIN_GRAPH_NODE_COLOR] [--main-graph-new-node-effect {none,droplets}] [--main-graph-nodes-fly-in] [--main-graph-node-edge-width MAIN_GRAPH_NODE_EDGE_WIDTH] [--main-graph-node-edge-color MAIN_GRAPH_NODE_EDGE_COLOR] [--main-graph-edge-width MAIN_GRAPH_EDGE_WIDTH] [--main-graph-edge-color MAIN_GRAPH_EDGE_COLOR] [--main-graph-edge-opacity MAIN_GRAPH_EDGE_OPACITY] [--inset-graph-level-height INSET_GRAPH_LEVEL_HEIGHT] [--inset-graph-node-size INSET_GRAPH_NODE_SIZE] [--inset-graph-node-color INSET_GRAPH_NODE_COLOR] [--inset-graph-new-node-effect {none,droplets}] [--inset-graph-node-edge-width INSET_GRAPH_NODE_EDGE_WIDTH] [--inset-graph-node-edge-color INSET_GRAPH_NODE_EDGE_COLOR] [--inset-graph-edge-width INSET_GRAPH_EDGE_WIDTH] [--inset-graph-edge-color INSET_GRAPH_EDGE_COLOR] [--inset-graph-edge-opacity INSET_GRAPH_EDGE_OPACITY] [--genome-track-line-width GENOME_TRACK_LINE_WIDTH] [--genome-track-line-color GENOME_TRACK_LINE_COLOR] [--genome-track-line-opacity GENOME_TRACK_LINE_OPACITY] [--genome-track-line-background GENOME_TRACK_LINE_BACKGROUND] [--rarefaction-all-syngcs-color RAREFACTION_ALL_SYNGCS_COLOR] [--rarefaction-core-syngcs-color RAREFACTION_CORE_SYNGCS_COLOR] [--rarefaction-line-width RAREFACTION_LINE_WIDTH] [--rarefaction-fade-in-at-genome N] [--fps FPS] [--hold-first-seconds HOLD_FIRST_SECONDS] [--seconds-per-genome SECONDS_PER_GENOME] [--dissolve-seconds DISSOLVE_SECONDS] [--hold-last-seconds HOLD_LAST_SECONDS] [--title-kicker TITLE_KICKER] [--title TITLE] [--subtitle SUBTITLE] [--inset-description INSET_DESCRIPTION] [--font {helvetica,avenir}] [-T NUM_THREADS] -o FILE_PATH [--background-color BACKGROUND_COLOR] [--keep-frames-dir KEEP_FRAMES_DIR] [--no-export-stills] [--dry-run] [--no-genome-tracks]
Parameters and their descriptions
-p, --pan-graph-dbPAN_GRAPH_DBrequired- Anvi'o pangenome graph database.
--componentCOMPONENT- Which weakly connected component to render (as named in the pan-graph-db; 'CP_0001' is the largest by default). Default:
CP_0001 --genomes-of-interestGENOMES_OF_INTEREST- Either a comma-separated list of genome names, or a path to a file with one genome name per line. Only these genomes will be rendered, and they will be added to the animation in exactly the order they are listed here, so this is also how you set the order of appearance. Every name must occur in the pan-graph-db, and none may repeat. The default is every genome in the pan-graph-db, in the order already stored there.
--exclude-genomesEXCLUDE_GENOMES- One or more genome names to leave out of everything that follows, as a comma-separated list or a path to a file with one genome name per line. This is applied after --genomes-of-interest, so the two work together: you can ask for a set of genomes in a given order, and still drop a few of them without editing that list.
--max-num-genomes-to-renderMAX_NUM_GENOMES_TO_RENDER- Render only this many genomes instead of every genome that is available. The animation then grows from 1 genome up to this number, following the same order of appearance. Since a full render can take a while, this is a convenient way to see what your output will look like with a handful of genomes first.
--inset-flanksLEFT_NODE,RIGHT_NODE- Two node ids (as they appear in the pan-graph-db) flanking the locus to magnify in an inset panel. Both must be present in every frame you render (i.e. conserved/backbone nodes). Omit to render the whole graph only, with no inset.
--inset-aspectINSET_ASPECT- Width-to-height ratio of the inset panel's frame (not necessarily of the locus drawn inside it). Default 1.436 suits a tall, narrow locus (a 'spire'); a wide, short locus (e.g. a broad hypervariable region) wants a larger value, closer to 4. Default:
1.436 --inset-graph-nodes-cover-window-dynamically- Spread the inset's nodes across the panel's full width in EVERY frame, rather than at one spacing pinned to the finished graph. By default a subgraph that grows as genomes arrive starts out small, nested against the left edge of the panel, and expands rightwards until the last genome fills the panel exactly. Pass this and the spacing between nodes is instead solved fresh for each frame, so the two flanking nodes sit at the panel's edges from the very first frame and what grows between them is the structure alone. The levels keep their pinned height either way, so the subgraph still gains height as it gains genomes.
--show-rarefaction- Draw rarefaction curves for the pangenome in the panel, revealed one genome at a time in step with the genome counter. Two curves are drawn, each with a band of plus/minus one standard deviation around it: the whole pangenome, and the core (the SynGCs present in every one of the subsampled genomes). The curves cover EVERY SynGC in the pan-graph-db rather than only those of the `--component` being drawn, and they are computed over exactly the genomes this video renders, in the order they arrive, so the panel's x axis is the same axis the genome counter is counting along. Cannot be combined with --inset-flanks, which wants the same panel.
--rarefaction-iterationsRAREFACTION_ITERATIONS- How many random subsamples to draw at each genome count when computing the rarefaction curves (default: 100). This is the same parameter `anvi-compute-rarefaction-curves` calls `--iterations`, and the same advice applies: above 100 rarely refines anything, and below 10 leaves the curves visibly lumpy. Only relevant with --show-rarefaction. Default:
100
--resolutionRESOLUTION- Output video resolution as WIDTHxHEIGHT (default: 3840x2160). The panel layout is tuned for 16:9. Default:
3840x2160 --rotation-offset-degROTATION_OFFSET_DEG- Rotates the whole main panel by this many degrees, purely cosmetic (default: 0.0). Default:
0.0 --outer-radius-fractionOUTER_RADIUS_FRACTION- Radius the FINAL frame's hole-plus-tracks-plus-graph is designed to reach exactly, as a fraction of the graph panel's own half-size (default: 0.97, which leaves just enough margin that strokes at the very edge don't get clipped). In other words, how much of the panel the whole drawing fills. The height of the genome-tracks band has no separate knob of its own: given this target, the hole (--inner-radius-fraction) and the graph's share (below), each genome's track height is SOLVED FOR so the three always sum to exactly this radius, with no leftover whitespace and nothing pushed past the edge, regardless of how many genomes are being rendered. The panel itself is also sized to claim the most space it can next to the text/inset column at your --resolution, so raising this is what actually shrinks the remaining margin. Default:
0.97 --inner-radius-fractionINNER_RADIUS_FRACTION- Radius of the empty hole at the very center of the main panel, as a fraction of --outer-radius-fraction (default: 0.15). Default:
0.15 --graph-height-fractionGRAPH_HEIGHT_FRACTION- How far the graph (the backbone ring plus its spires) reaches beyond the tracks, as a fraction of the TOTAL tracks height, which is to say of all genomes' rings stacked together. The default of 0.2 means the graph reaches one-fifth as far beyond the tracks as the tracks themselves reach beyond the hole, keeping the tracks the dominant visual element. Together with --outer-radius-fraction and --inner-radius-fraction this fully determines each track's height (see that flag's help), and raising it gives the graph more relative room at the tracks' expense rather than at the panel's. The spire-climb-per-step is then sized from the FINAL frame's real tallest spire so it lands exactly on that reach. Default:
0.2 --backbone-gap-pxBACKBONE_GAP_PX- Fixed radial gap between the genome-tracks stack and the backbone ring, in pixels (default: half of one track's own height). This is the only distance between the two, and it does not grow with the backbone's own length, which is what makes the backbone hug the tracks at every frame.
--track-height-pxTRACK_HEIGHT_PX- Pixels per y (track/spire) step in the main panel, which is to say how far a spire climbs outward from the backbone per insertion. Setting this replaces the default derivation, which instead sizes the step from the FINAL frame's real tallest spire so it lands exactly on --graph-height-fraction's share of the panel. Use it when you want an exact, resolution-independent pixel value, at the risk of over- or under-shooting the panel edge.
--supersampleSUPERSAMPLE- Render this many times larger than the final resolution and downsample, for antialiasing (default: 2; raise for smoother lines at the cost of render time). Default:
2
--main-graph-node-sizeMAIN_GRAPH_NODE_SIZE- Main-panel node circle radius, in pixels. Default is derived from --resolution and how densely packed the final frame's backbone is.
--main-graph-node-colorMAIN_GRAPH_NODE_COLOR- Main-panel node fill color as a hex code. By default every node keeps the color anvi'o's own state assigned to its type, which is what makes core, accessory and singleton clusters tell each other apart. Passing this OVERRIDES all of them to a single color.
--main-graph-new-node-effectMAIN_GRAPH_NEW_NODE_EFFECT- Mark the nodes that arrive with each genome, in the main panel, with a brief effect, which makes what a genome actually contributed easy to follow. This marks only nodes that are genuinely NEW to the graph; --inset-graph-new-node-effect deliberately casts a wider net, see its own help. 'droplets' sends a filled copy of every new node breaking outwards to 20x its own size and fading as it spreads. The first genome is never marked, since every node in it would be. How long an effect runs for is a property of the effect itself, given as a share of --seconds-per-genome and printed back under 'ASSEMBLING VIDEO'. Default: none. Note that an effect makes every frame of a genome's turn on screen differ from the last, so both the render time and the size of the MP4 go up. Choices:
nonedropletsDefault:none --main-graph-nodes-fly-in- Have the nodes a genome brings with it FLY IN to their places, instead of simply being there in the next frame. Each new node comes in from off-canvas along its own fixed bearing, oversized and shrinking as it goes, and easing to a stop at exactly its true size once it lands. This makes what a genome actually contributed impossible to miss and where in the graph it landed easy to follow, and arriving large is what makes it work at all on a dense pangenome, where a node resolves to a pixel or two across and could not otherwise be followed on its way in. Only genuinely NEW nodes fly; everything already on screen stays put, and edges are drawn in full throughout, so the graph visibly holds a place open for whatever is on its way in. The first genome never flies, since every node in it would be. This is an alternative to --main-graph-new-node-effect rather than a companion to it (asking for both is an error, since the effect would fire where the node is going while the node is still on its way there), though --inset-graph-new-node-effect is unaffected. Default: off. Note that this makes every frame of a genome's turn on screen differ from the last, so both the render time and the size of the MP4 go up; `--num-threads` is the answer to most of that.
--main-graph-node-edge-widthMAIN_GRAPH_NODE_EDGE_WIDTH- Main-panel node outline stroke width, in pixels. Default: one third of --main-graph-node-size.
--main-graph-node-edge-colorMAIN_GRAPH_NODE_EDGE_COLOR- Main-panel node outline color as a hex code (default: '#000000', black). Default:
#000000 --main-graph-edge-widthMAIN_GRAPH_EDGE_WIDTH- Main-panel graph edge (the lines connecting gene-cluster nodes) line width, in pixels. Default is derived the same way as --main-graph-node-size.
--main-graph-edge-colorMAIN_GRAPH_EDGE_COLOR- Main-panel graph edge color as a hex code (default: '#3C3C3C', dark gray). Default:
#3C3C3C --main-graph-edge-opacityMAIN_GRAPH_EDGE_OPACITY- Main-panel graph edge opacity, 0-1 (default: 0.63). Default:
0.63 --inset-graph-level-heightINSET_GRAPH_LEVEL_HEIGHT- How far apart the inset panel's y levels sit, in pixels. A subgraph has as many levels as its topology needs, and the two axes of the panel are scaled independently, so by default the levels are spread across the panel's full height however many of them there are. On a large subgraph that can still leave them close enough together to bury the structure the panel exists to show, which is what this is for: raise it to pull the levels apart, at the cost of the tallest of them reaching past the top of the panel.
--inset-graph-node-sizeINSET_GRAPH_NODE_SIZE- Inset-panel node circle radius, in pixels. Default is derived from how zoomed-in the inset is (wider gaps between backbone positions get bigger nodes).
--inset-graph-node-colorINSET_GRAPH_NODE_COLOR- Inset-panel node fill color as a hex code. Works exactly like --main-graph-node-color, and is separate from it so the magnified panel can carry the type colors while the main panel goes flat, or the other way around.
--inset-graph-new-node-effectINSET_GRAPH_NEW_NODE_EFFECT- The same effects as --main-graph-new-node-effect, in the magnified panel, but triggered on a WIDER set of nodes than that flag's name suggests, so please read on. The main panel marks only nodes that are genuinely new. The inset marks every NON-CORE node the arriving genome puts a gene into, whether that node is new or was already on screen. A genome dropping a gene into a synteny gene cluster that several other genomes already occupy has changed that cluster, and at this magnification that is worth watching, while in the main panel the same rule would mark hundreds of nodes per genome and read as noise. Core nodes are never marked either way: 'core' means every genome in the graph has a gene there, so every genome would light up every core node, which says nothing about any of them. Separate from --main-graph-new-node-effect so the two can be asked for independently, though the timing is shared. Default: none. Choices:
nonedropletsDefault:none --inset-graph-node-edge-widthINSET_GRAPH_NODE_EDGE_WIDTH- Inset-panel node outline stroke width, in pixels. Default: one sixth of --inset-graph-node-size (thinner than the main panel's, since inset nodes are already much larger).
--inset-graph-node-edge-colorINSET_GRAPH_NODE_EDGE_COLOR- Inset-panel node outline color as a hex code (default: '#000000', black). Default:
#000000 --inset-graph-edge-widthINSET_GRAPH_EDGE_WIDTH- Inset-panel graph edge line width, in pixels. Default is derived the same way as --inset-graph-node-size.
--inset-graph-edge-colorINSET_GRAPH_EDGE_COLOR- Inset-panel graph edge color as a hex code (default: '#3C3C3C', dark gray). Default:
#3C3C3C --inset-graph-edge-opacityINSET_GRAPH_EDGE_OPACITY- Inset-panel graph edge opacity, 0-1 (default: 0.55). Default:
0.55 --genome-track-line-widthGENOME_TRACK_LINE_WIDTH- Genome-track synteny-line width, in pixels. Default is derived from each track's own (fixed) height.
--genome-track-line-colorGENOME_TRACK_LINE_COLOR- Genome-track synteny-line color as a hex code. By default each genome keeps the color anvi'o's own state assigned to it. Passing this OVERRIDES every genome to a single color.
--genome-track-line-opacityGENOME_TRACK_LINE_OPACITY- Genome-track synteny-line opacity, 0-1 (default: 0.75). Default:
0.75 --genome-track-line-backgroundGENOME_TRACK_LINE_BACKGROUND- Genome-track background band color as a hex code. By default the background color stored in the pan-graph-db's own state is used (usually a near-white gray).
--rarefaction-all-syngcs-colorRAREFACTION_ALL_SYNGCS_COLOR- Color of the all-SynGCs rarefaction curve, and of its standard-deviation band, as a hex code (default: #1F6FEB). Only relevant with --show-rarefaction.
--rarefaction-core-syngcs-colorRAREFACTION_CORE_SYNGCS_COLOR- Color of the core-SynGCs rarefaction curve, and of its standard-deviation band, as a hex code (default: #D1242F). Only relevant with --show-rarefaction.
--rarefaction-line-widthRAREFACTION_LINE_WIDTH- Width of the two rarefaction curves in pixels. By default it is derived from the output resolution. Only relevant with --show-rarefaction.
--rarefaction-fade-in-at-genomeN- Keep the rarefaction panel (and the line of text above it) off screen until genome N arrives, then fade it in with that genome. Watching a curve draw itself from the very first genome can be a slow start, and this hands you the timing: pass 11 and the first ten genomes are just the graph growing, with the panel arriving alongside the eleventh, already part-drawn. N is the genome the panel comes in WITH, so it is the number the genome counter is showing at that moment. The fade itself lasts --seconds-per-genome: it starts as that genome does and is complete by the end of its turn on screen, so it is slow enough to watch. Nothing else in the column moves when it appears. By default the panel is there from the first genome onward. Only relevant with --show-rarefaction.
--fpsFPS- Frames per second (default: 30). Default:
30 --hold-first-secondsHOLD_FIRST_SECONDS- How long the first genome is held before the animation starts moving (default: 1.5). Default:
1.5 --seconds-per-genomeSECONDS_PER_GENOME- How long each genome's state is held before dissolving to the next (default: 0.45). Default:
0.45 --dissolve-secondsDISSOLVE_SECONDS- Cross-dissolve duration between consecutive genome states (default: 0.2). Default:
0.2 --hold-last-secondsHOLD_LAST_SECONDS- How long the finished graph is held at the end (default: 4.0). Default:
4.0
--title-kickerTITLE_KICKER- Small muted line above the title (default: 'The pangenome graph for'). Pass an empty string to hide it. Default:
The pangenome graph for --titleTITLE- The main title line, set in italic (e.g. a genus name). Defaults to the project name stored in the pan-graph-db.
--subtitleSUBTITLE- An optional line below the title, in regular weight (e.g. a former name). Omit to show no subtitle line at all.
--inset-descriptionINSET_DESCRIPTION- A short line of text shown in the gap between the genome-counter progress bar and the inset panel, in the same font/color as --subtitle. Only shown when --inset-flanks is given. Default: "Subgraph between LEFT_NODE and RIGHT_NODE detailed", with the actual two --inset-flanks node ids filled in. Wraps to fit the text column's width. Pass an empty string to hide it.
--fontFONT- Typeface for all on-screen text (default: helvetica). These are macOS system typefaces. On Linux system anvi'o will set everything in DejaVu Sans instead. DejaVu runs wider so a Linux render will not be pixel-identical to a macOS one. We mostly tested this program on macOS, so if you are running into ugly displays on Linux please let us know and we will work on it. Choices:
helveticaavenirDefault:helvetica
-T, --num-threadsNUM_THREADS- How many frames to rasterize at the same time (default: 1). Drawing a frame is mostly Pillow's C code, which lets go of Python's global interpreter lock while it works, so this genuinely does speed things up, though sublinearly: expect something nearer 3x from 8 threads than 8x. It is the biggest lever you have whenever an effect is switched on, since an effect is what makes every single frame of every genome's turn have to be drawn separately instead of held. There is no point going past the number of CPUs on your machine, and anvi'o will say so if you do. Note that this governs RASTERIZING frames and nothing else: the ffmpeg encode at the end is already parallel of its own accord, since libx264 detects your cores and helps itself to them. Anvi'o deliberately does not pass this number on to ffmpeg, because capping the encoder at this flag's default of one thread measures several times SLOWER than leaving it alone. Default:
1
-o, --output-fileFILE_PATHrequired- Path for the output MP4.
--background-colorBACKGROUND_COLOR- Canvas background color (default: white). Default:
#FFFFFF --keep-frames-dirKEEP_FRAMES_DIR- If given, individual frame PNGs are written here and kept after the video is made (useful for pulling out a still frame). Default: a temporary directory that is deleted when done.
--no-export-stills- By default, this program also writes '<output>-first-frame.{svg,png}' and '<output>-last-frame.{svg,png}' next to the video. Pass this flag to skip that and only write the MP4.
--dry-run- Stop right after the scenes are built and the first/last-frame stills are written, before rasterizing frames or calling ffmpeg, which skips the slow part entirely. Handy while tuning the COSMETICS flags: run with --dry-run, look at '<output>-last-frame.png', adjust, repeat, and only drop --dry-run once it looks right. Incompatible with --no-export-stills, since that would leave nothing to look at.
--no-genome-tracks- Turn off the concentric per-genome presence rings drawn between the empty center and the backbone (one ring per genome currently on screen, showing which of its gene clusters are present at each backbone position).
Additional Resources
Are you aware of resources that may help users better understand the utility of this program? Please feel free to edit this file on GitHub. If you are not sure how to do that, find the __resources__ tag in this file to see an example.