Command line interface - dev-cuttlefish/cuttlefish GitHub Wiki
The command line interface allows users to (1) open a network in a given file format, (2) apply one of the layouts, and (3) output the network. Using the command line, users can quickly convert from one file format to another.
To print the help information, run Cuttlefish with the "--help" argument as follows:
java -jar cuttlefish.jar --help
The above command prints the following:
$ java -jar cuttlefish.jar --help
usage: java -jar cuttlefish.jar [options]
-g,--gui start the graphical interface
-h,--help prints this message
-i,--input <input file> input file
--in-format <input format> input format: cxf (default), json,
graphml, pajek
-l,--layout <layout> network layout: arf, fixed (default)
weighted-arf, k-core, kamada-kawai,
fruchterman-reingold, iso-m, circle,
tree, radial-tree
-o,--output <output file> output file
--out-format <input format> output format: tikz (default), cxf,
applet, svg, json, cmx, graphml
When Cuttlefish is started without specifying any arguments, Cuttlefish starts the graphical interface. Running the jar file with at least one argument immediately invokes the command line interface.
Some of the arguments have short and long names. For instance, -g is the short name for --gui, -i is the short name for --input, etc. See the output produced by the --help argument above to find out which arguments have short names.
A typical usage of Cuttlefish from the command line interface is the following:
$ java -jar cuttlefish.jar -i in_file.ext --in-format <in format> -l <layout> -o out_file.ext --out-format <out format>
in_file.ext is the path to the input file. <in></in> specifies the format in which the network is stored in the input file, if the input format is not specified, Cuttlefish assumes that the input is in CXF format. <layout></layout> specifies which layout should be applied to the opened network, if no layout is specified Cuttlefish applies the Fixed layout, which is equivalent to not computing any layout. out_file.ext is the file where Cuttlefish writes the output network. Finally, <out></out> specifies the format in which Cuttlefish stores the output network to the output file. Note that all these arguments can be given in any order.
The supported input formats are:
- cxf - this is the native Cuttlefish format, for more details see the CXF format documentation
- graphml - a widely adopted format for storing networks, for more details see documentation on The GraphML File Format
- json - the json format is the same format used when using the Cuttlefish applet in a web browser. For more details see the documentation on the Cuttlefish applet.
- pajek - another popular file format for storing networks, for details see the Pajek wiki page.
- tikz - the tikz format is used to produce figures for papers, see the page about compiling tikz to pdf
- cxf - the native cuttlefish formet, see the CXF format documentation
- applet - this output can be embedded in a web page, for details see the cuttlefish applet tutorial
- svg
- json - the json output is the formatted similarly to the applet output, for details see the cuttlefish applet tutorial
- cmx
- graphml - the graphml output can be used to export network compatible with Gephi, for more details see the The GraphML File Format documentation
To open a network stored in file file.cxf (stored in the cxf format), apply the circle layout and output the network to tikz:
$ java -jar cuttlefish.jar -i file.cxf --in-format cxf -l circle -o output.tex --out-format tikz
Since cxf is the default input format, and tikz is the default output format, the above command is equivalent to:
$ java -jar cuttlefish.jar -i file.cxf -l circle -o output.tex
Both commands produce a file output.tex, which can be compiled using pdflatex, for instance, to obtain a pdf of the network stored in file.cxf. For more information about compiling the tikz files produced by Cuttlefish refer to the Cuttlefish Tikz tutorial. Cuttlefish prints the following output when the commands given above are executed:
$ java -jar cuttlefish.jar -i file.cxf -o output.tikz -l circle [11-12-31] Outputting the network [11-12-31] Exporting to tikz [11-12-31] Opening network: file.cxf [11-12-31] Opened a network with 88 nodes and 113 edges [11-12-31] Setting layout: circle [11-12-31] Layout set [11-12-31] Done [11-12-31] Outputing the network [11-12-31] Exporting to tikz [11-12-31] Done
Iterative layouts are the ones that do not compute the network layout in a single shot, but compute the layout step by step, each step converging to the optimal layout. The ARF and WeightedARF layouts are iterative. When Cuttlefish applies an iterative layout from the command line, it constantly prints how much the layout changed in the last step. For instance, invoking cuttlefish with the ARF layout, it prints the following:
$ java -jar cuttlefish.jar -i file.cxf -o output.tikz -l arf [11-12-31] Outputting the network [11-12-31] Exporting to tikz [11-12-31] Opening network: file.cxf [11-12-31] Opened a network with 88 nodes and 113 edges [11-12-31] Setting layout: arf [11-12-31] Iterative layout, waiting on the layout to converge... [11-12-31] The layout will automatically stop when the change is less than 10 [11-12-31] you can always manually stop the layout by pressing Ctrl+C [11-12-31] Layout change: 120.1297487434
The last line shows the dynamics of the layout. The layout change is given in pixels per node, i.e. the movement of a node in the last computed step. Typically, the iterative layout initially is very dynamic and changes the network a lot, and after converging to the optimal layout it applies only small changes to the network. The iterative layout finishes when the change is less than 10 pixels per node. However, the user can terminate the iterative layout at any time by pressing Ctrl+C, after terminating the layout, Cuttlefish will output the network in the requested format.
If you just need to convert from one format to another, e.g. from Cxf to Graphml, then you should not specify a layout which might be expensive to computer. You should use the Fixed layout which does not slow down the conversion process. Note that the Fixed layout is the default layout used by the command line interface, this means that if you don't use the --layout option, Cuttlefish automatically assumes Fixed layout.