# Kelviz v3.3.1 Manual

## Introduction

Kelviz is a graphing application designed to plot and annotate genetic data analysis results for easy review and publication. It is designed for use with Kelvin analysis results, but can make use of any data file that follows roughly the same conventions.

Kelviz works with a figure, which is created by importing output files from Kelvin analyses (or similarly-formatted data files), and consists of one or more plots, each of which may contain one or more lines (one per chromosome per genome), which are organized into line groups (by chromosome) and line sets (by genome). Line groups are displayed side-by-side in Kelviz plots, and multiple line sets can be added to overlap different genomes and/or different analyses. Plots can be laid out virtually anywhere in the figure, and may optionally use the lines from another plot so as to create different views of the same data. Gene marker maps can also be added, displayed as symbols overlaid on chromosome lines.

Kelviz works with figures in its own custom-designed XML file format, GRX, and can also export figures to several common raster and vector image formats such as PNG, TIFF, EPS, SVG, and PDF - either the whole figure at once, or in tabular collages of sub-plots per chromosome group or per line set.

See the v3.3.1 release notes for information as to what's changed with this version of Kelviz.

## Installation Requirements

Kelviz is distributed as a Python source archive (both stand-alone and included with Kelvin), as a OSX app bundle, as a Linux shell script installer, and as a Windows .EXE installer.

The app bundle is tested on systems running Mac OSX 10.6, 10.7, and 10.8 (Snow Leopard, Lion, and Mountain Lion), and is the recommended means of using Kelviz.

The Linux installer and build is tested in commandline mode. The binary should hypothetically work anywhere, although this has not been broadly tested. Run the installer using bash Kelviz-3.3.1.install.sh and it will prompt you for a prefix to install Kelviz into.

The Windows installer and build is not extensively tested but is known to run on Windows XP SP3.

The source package can be used to build stand-alone apps for other platforms (setup files for pyinstaller and py2app/py2exe are provided), and it can also be used to simply run Kelviz directly from the distribution directory (see Running Kelviz, below). The following versions of Python and Python modules are required:

• Python 2.7 (version 3 is not supported)
• matplotlib 1.4 or higher and its prerequisites
• wxPython 3.0 "Classic" or higher and its prerequisites
• Python Imaging Libary (PIL) 1.1.7 ('pillow' should work but has not been tested)

Nearly all these requirements are provided out-of-the-box by Continuum Analytics' Anaconda python distribution. wxPython 3 is not normally included in their default install (as of version 2.1), but can be easily added after installation by running conda install wxpython.

## Running Kelviz

Kelviz can be run directly from the distribution directory by running:

$./kelviz.py  On OSX, simply double-click the app bundle to launch Kelviz via the Finder. On Linux, you can run kelviz (assuming that you installed it to a directory on your PATH) from any prompt. On Windows, you can find Kelviz in the Start menu after installation. In all three cases, command-line options can be specified by running Kelviz from a command line; see that section for details. ## Getting Started - The Main Kelviz Window Upon opening Kelviz, you can expect to see something like this: The notable portions of this screen are indicated here: • Figure: The figure and all plots are displayed here. This is also where you add, edit, and otherwise interact with annotations. • Cursor Position Info: As your mouse pointer hovers over a plot, information about the location it's hovering over is displayed in the status bar, along with any metadata associated with the nearest data point. • Toolbars: There are two toolbars in Kelviz. They are described below. • Comment Box: This is a free-form text box where you can save comments about the figure. This is only visible to Kelviz users who might see your figure in Kelviz GRX format later. • Info Box: Information about annotations in the figure's plots is shown here, including total numbers of annotations in the figure, total annotations per plot, total annotations visible in the current view, and a listing of the visible and not visible annotations. You can have more than one Kelviz window open at the same time and thus work on figures side-by-side. To facilitate this, in the File menu you will find the option Open New Kelviz Window, which starts a new Kelviz window with a blank figure for you to start working on. Loading an existing figure is done by clicking on the Open GRX File toolbar button (illustrated to the right), or by selecting Open GRX File from the File menu. If you prefer to start working on a new or existing figure in place of the figure already loaded, you can do so by going to the Edit menu and selecting Clear Figure. Make sure you save any changes to your existing figure before doing this! When you're at a stopping point (or want to make sure your work won't be lost), you can save your current work by clicking on the Save GRX File toolbar button (illustrated to the right) or by selecting Save GRX File from the File menu. Alternatively, if you don't want to overwrite a GRX file you started with, select Save as GRX File from the File menu and you will be prompted for a new filename. ## Importing Data Adding data to a figure - whether it be a plot from an existing figure, or the first data to be plotted in a figure, or another dataset to supplement what you already have - is done via importing that data into your figure. Data consists either of another Kelviz GRX file (for a figure with plots you want to import), or a Kelvin analysis or some other text file that follows the same conventions (for a dataset). To import a plot from an existing figure, select Import Plot From GRX from the File menu. Enter the name of the GRX you wish to import a plot from. Kelviz will then ask you which plot to import with the following dialog: Simply select the plot (or "All Plots" if you want to import them all) and they will be copied to your figure. To import data with which to create a new plot, start by by clicking on the Import Data From File toolbar button (illustrated to the right) or selecting Import Data From File from the File menu. You will be prompted for a filename. Enter the name of the datafile you wish to import. When doing this, Kelviz will need additional information as to how to import the data, and will prompt you for it via the following dialog: Preview The top of the dialog shows a preview of the first five lines of your datafile (excluding any comments). This is included as an aide to determining which columns you need. Plot to import into Indicates which plot you wish to import the data from this datafile into. You may select an existing plot, or have Kelviz create a new plot for you automatically. Overlap existing data with this dataset Indicates whether or not you want to overlap your plot's existing data with the new data you are importing. If the plot you are importing into already has data stored within, this checkbox will be enabled and checked by default. NOTE: Adding data to a plot that already has it without overlapping existing chromosomes is not fully supported and may have strange side effects. Use this option with caution and discretion only. Replace data in existing lineset Indicates whether or not we want the data we're importing to replace the data in an existing lineset in this figure. You will need to specify the lineset to replace. Position Column Choose which column lists chromosome position. The values in this column will be used as the x-axis values of points. By default, Kelviz will look for a column named "Position", "Pos", "cM", "Kosambi", or "Haldane" (roughly in that order), and if it doesn't find one of those it will default to the second column in the datafile. PPL Column Choose which column lists the PPL values. The values in this column will be used as the y-axis values of points. By default, Kelviz will look for a column named "PPL" (or one of a few variants thereof), and if it doesn't find one it will default to the third column in the datafile. First line is header, not data Indicates that the first line of our data file is a header with column names in it, and therefore should not be used for processing. Turned on by default; if you have a datafile that does not have such a header, you should turn this off. Chromosome Column Choose which column (if any) lists the chromosome each datum is associated with. This determines what line groups our lines will be organized into. By default, Kelviz will look for a column named "Chromosome" or "Chr", and if it doesn't find one of those it will default to the first column in the datafile. If there is no such column, pick "None - newline-divided", and Kelviz will attempt to figure out what chromosomes are in your datafile automatically, checking both for newline-divided sections between data, and for when position values go down instead of up from line to line. There is also an option for "None - single chr file", whereupon you'll be asked to specify what single chromosome this data file represents. Datafile chromosome number This is only relevant if you picked "None - single chr file" for Chromosome column - it lets you specify what chromosome the datafile you're importing has position and PPL data for. Import all chromosomes in file Choose this option to read in and import all chromosomes listed in the file. Import only specified chromosomes Choose this option if the file being imported has information for many chromosomes, but only a subset of those are wanted. Simply list the number of the chromosomes that need to be imported. Separate numbers using commas (e.g. '1, 2, 3') or spaces ('5 8 13'). Name of this set of lines Specifies the name of this line set. This can be left blank if desired; by default it'll take on the filename, or (if it's not "PPL") the name of the PPL column selected. Line set names are used in the plot's Legend. As such, they can include mathematical expressions and other special formatting; see Mathematical Expressions, below. Prefix chromosome number with Attaches a specified prefix to the chromosome numbers. This can be left blank if desired. For example, if a prefix of 'a' is specified, then the chromosome number will be listed as a1, a2, etc. Handy for when you overlap different chromosomes together, and you want their names to be different. Postfix chromosome number with Attaches a specified postfix to the chromosome numbers. This can be left blank if desired. For example, if a postfix of 'a' is specified, then the chromosome number will be listed as 1a, 2a, etc. Handy for when you overlap different chromosomes together, and you want their names to be different. Column(s) with extra data Specifies if there are any columns in the datafile that you want to include as metadata or extra data. This is how you include the marker name or names. Multiple columns should be separated by commas or spaces. Metadata shows up in the window statusbar alongside Cursor Position Info (see Getting Started - The Main Kelviz Window, above), and will also show up by default in annotations of data points with metadata in place of position information (see Annotations, below). Value(s) that indicate missing values Specifies if there are any special values that indicates that a given line represents a missing value. For example, if a 0 is placed in the text box, then any time a 0 is encountered in the indicated PPL column, then that line will be treated as a missing data point, and the line is skipped. Special values can be any combination of numbers, letters, or other characters. The only rule is that special values cannot be or contain a comma. The default value that indicates missing data is ".", so anytime this is encountered in the PPL column, this line is skipped. Multiple special valules can be specified and are separated by spaces or commas. Keep all imported lines the same color Have this option checked to keep imported lines the same color. The default is to have it checked. The color button next to it lets you choose what one color to use for all imported chromosomes. If this is unchecked, each chromosome being imported will each have a different color, and the color box has no effect. ## Modifying Data Presentation ### Data Lines The appearance and presentation of data in Kelviz can be modified after importing. This can be done on a per-lineset (per-genome), per-line (per-chromosome), or figure-wide basis. The most common such operation is to change data presentation on a per-lineset basis, using the Configure Line Sets dialog. This is done by going to the Options menu and selecting Configure Line Sets. Tabs are presented for each plot in your figure, and each such tab presents a row of controls for each lineset in that plot. Name Specifies the name of this particular lineset. Normally set automatically as part of importing data (see Importing Data, above). Line set names are used in the Legend. As such, they can include mathematical expressions and other special formatting; see Mathematical Expressions, below. Color Specifies a color for all lines in this lineset. This is also shown in the Legend. Line Style Specifies the appearance of all lines in this lineset. Possible styles include "solid" (the default), "dotted", "dashed", "none" (do not display the line at all), et cetera. This is also shown in the Legend. Thickness Specifies how thick each line should be drawn, roughly in point/pixel size. The usual default is 1.0. This is also shown in the Legend. Symbol Specifies a symbol shape to use for all lines in this lineset. A symbol is placed for each and every data point plotted on each line. This is also shown in the Legend. Symbol Size Specifies the size desired for each line's symbols (if any). This is also shown in the Legend. Zorder Specifies what order to draw this lineset's lines in, from lowest to highest. For example, a lineset with zorder 3 would be drawn after (and thus on top of) a lineset with zorder 1. By default, these are assigned in the order that the linesets were imported. DELETE Specifies that this lineset is to be removed from the plot. The "Use lines from another plot" controls are used to create plots with the same data as other plots - see Multiple Plots With The Same Data, below, for details. NOTE: If you've customized any of the above properties for individual lines in this lineset, setting properties here WILL override those customizations! Changing lines on a per-individual-line basis can be done via the Configure Individual Lines dialog, reached via the Options menu and selecting Configure Individual Lines. Each and every individual line in the figure is represented, organized by plot and by chromosome. The controls are identical to those found in the Configure Line Sets dialog, above. Alternatively, you may opt to change one or more properties of all lines at once. To do this, the Configure All Lines dialog (reached by going to the Options menu and selecting Configure All Lines) may be used: The controls presented operate similarly to those in the Configure Line Sets dialog, except that they apply to each and every line in each and every plot in the figure. Each control also has a checkbox above it - if you do not want to change this property for every line, uncheck that property's checkbox to disable it. For example, if you want to change the line style of every line in the figure to "dotted" and leave everything else alone, uncheck the checkboxes under "Color", "Thickness", "Symbol", and "Symbol Size", change the "Line Style" drop-down to "dotted", and click OK. ### Horizontal Lines Horizontal lines can be added to or removed from plots using the Add Or Remove Horizontal Lines toolbar button, illustrated to the right, or by going to the Edit menu and selecting Add Or Remove Horizontal Lines. When adding horizontal lines, you will need to provide the Y-value or values where the horizontal line(s) should be located. Multiple horizontal lines can be added if desired; separate the values with commas. You also have the option to set the width of horizontal lines for this plot; the value is specified in points. Removing horizontal lines is done using the checklist at the bottom of the dialog that lists all horizontal lines in the plot by Y-value; put a check mark next to the horizontal lines you want removed and then click OK, and they will be removed. ### Plot Location And Layout In The Figure The locations of plots relative to eachother in Kelviz is controlled via a conceptual "grid" of relatively-sized rows and columns. This layout system, plus details on the figure's size, can be adjusted via the Configure Figure Layout dialog, which can be reached by going to the Options menu and selecting Configure Figure Layout. Layout Preview and Refresh Preview This is a scaled-down preview of what the layout currently looks like, or will currently look like with any adjustments you've made in the dialog. Clicking on Refresh Preview will update the preview to reflect any new changes. Figure Size This controls the size of the figure, and is given in inches. This can be adjusted to taste, or you may have information on desired figure sizes from a publication you are preparing to submit Kelviz-generated figures to. Padding This controls the padding between the edges of the figure and the plots. The number roughly corresponds to increments of 12 points. Image Export DPI This controls the quality level of images exported from Kelviz. This may be specified by a publication you are preparing to submit Kelviz-generated figures to, or it may be adjusted to taste. Minimum Grid Size This is the minimum number of grid "rows" and "columns" that should be in the figure. This may allow you to add in additional "empty" rows and columns as desired. This does not affect the size of the figure in any way - just how its plots are laid out relative to eachother. Row Start, Row End, Column Start, and Column End This is how plot locations are specified - by indicating the numbers of rows and columns that they span across. For example, a plot within a 3x3 grid can take up the leftmost two-thirds of a graph by having having it start in row 0 and column 0, and span to row 3 and column 2 (leaving the third column open for other plots). Create New Plot Clicking this button will add a new plot (and controls for its location) to the window, to be added to the figure once configuration in this dialog is complete. Kelviz will attempt to automatically make space for the new plot by adding rows to the grid and placing the new plot therein. ### Figure and Plot Labels Several labels can and/or are automatically added to your plot to help clarify it, including but not limited to the chromosome numbers along the x-axis, additional x-axis and y-axis labels, and the figure title. These can be changed via the Figure Labels dialog, reached by going to the Options menu and selecting Configure Figure Labels. The dialog is roughly divided into three parts - one for figure-wide options, and then one each for each plot's axes titles and x-axis chromosome numbers. Figure Title This allows you to set a title for the entire figure, displayed at the top center. This can include mathematical expressions and special formatting; see Mathematical Expressions, below. Figure Title Font Size Sets the font size (in points) for the figure title. Use automatic plot titles By default, each plot is given a letter title at its top-left corner (such as "(a)", "(b)", and so forth). There is also the option to specify a custom title for each plot, which will be placed at the top center above the plot. Uncheck this box to enable that option. Use serif fonts in all text in the figure By default, Kelviz uses serif fonts for all figure text; if you prefer the appearance of sans-serif fonts, check this box. The following options are specific to each plot: Plot Title Provided that "Use automatic plot titles", above, is turned off, this allows you to set a title for the current plot, displayed at the top center above said plot. This can include mathematical expressions and special formatting; see Mathematical Expressions, below. X Label, Y Label These allow you to set labels for the plot's X axis (displayed along the bottom of the plot), and the Y axis (displayed vertically to the left of the plot). Both of these can include mathematical expressions and special formatting; see Mathematical Expressions, below. Background Color Sets the background color for each plot in the figure. This does not affect the background color of the margins, which cannot be modified. Additional X-Label Padding Specifies (in points) any additional space desired between the top of the X-axis label (see X Label, above) and the bottom of the graph. Space is always added so that there's room for any tick marks and/or chromosome number labels along the X-axis; this is for any additional space you want to add. Title Text Size Provided that "Use automatic plot titles", above, is turned off, this lets you set the font size (in points) for the plot title. Axis Text Size, Tick Mark Text Size Sets the font size (in points) for the X-axis and Y-axis labels, and for tick mark labels. Show Chromosome Number Labels By default, each group of chromosome lines in every plot is indicated by a series of number labels along the X-axis, in addition to any other tick marks. This gives the option to turn those group numbers off. Line Label Text Size Sets the font size (in points) for chromosome number labels. Use condensed (compact) font An optional condensed font is provided for the display of chromosome number labels for circumstances where they are forced close together; it can be used by checking this box. Prevent line labels from overlapping Specifies whether or not to attempt to prevent chromosome number labels from overlapping; if turned on, they continually shift to the right until they no longer overlap. NOTE: If the Line Label Text Size is set too high and this option is on, this may cause line labels to shift so far left that they run off the edge of the plot. Tweak these options with caution and discretion. Label chromosome 23 as X and Label chromosome 24 as Y By default, chromosomes 23 and 24 are displayed as "X" and "Y" respectively; uncheck these boxes to turn that off. ### Figure and Plot Legends Each plot comes with its own legend, which is automatically generated and includes every visible line set. It is also possible to have a single legend for the entire figure, which includes information from every plot. To configure these, go to the Options menu and select Configure Figure Legends. Show figure-wide legend Enables one legend for the entire figure that includes line and lineset information for all plots. Figure Legend Text Size Sets the font size (in points) for the text of the figure-wide Legend. Legend Location Specifies where the figure-wide legend should be located. There are three options - "center right" and "center left" indicate the right and left edges of the figure respectively, and "in grid" means the legend is inserted into Kelviz's "layout grid" and can have its location be further customized there (see Plot Location and Layout In The Figure, above) NOTE: When using "in grid" positioning, legend size is NOT automatically adjusted for available space. Some experimentation may be necessary. The following options are specific to each plot: Show Legend Indicates whether or not we want this plot to have a Legend. By default, this is turned on if the plot has more than one lineset, and is otherwise turned off. Plots that use another plot's lines (see Multiple Plots With The Same Data, below) by default do not have a Legend, but this can be overridden. Legend Text Size Sets the font size (in points) for the text of this plot's Legend. List Line Sets / List Individual Lines By default, each plot's Legend shows a list of linesets. They are also capable, however, of listing individual lines; this toggles that option. This option also affects the figure-wide legend; toggle it if you want this plot's lines to show up in the figure-wide legend instead of its linesets. Show Legend Frame Toggles the appearance of the legend frame in each plot. This is the white box with a black border that appears behind the Legend; it is turned on by default. Legend Location Specifies where the Legend should be located on each plot. ### Tick Marks Tick marks along each plot's X-axis can be extensively customized. This is done via the Configure Tick Marks dialog, reached by going to the Options menu and selecting Configure Tick Marks. There are three main choices for tick mark placement: Default, Base-Pair, and Custom. Default This tick mark placement scheme is optimized for chromosomes that have positions specified in centimorgans (genetic distance). As the name implies, it is the default placement scheme. Base-Pair This tick mark placement scheme is optimized for chromosomes that have positions specified as physical locations, or base-pair locations. There are two additional options associated with the base-pair scheme: • Use letters: Represents physical locations in abbreviated form in tick mark labels. • Max Number Of Ticks: Restricts the number of tick marks displayed along the X-axis. Customize This allows you to manually create your own tick mark placement scheme. There are several associated options: • Tick mark interval: Sets how far apart consecutive tick marks should be. It can be automatically set by Kelviz, or manually set. • Tick mark location: Tick marks may be placed either at even multiples of the tick interval ("Tick marks are even multiples..."), or they can always start at the first available position and then be offset by the tick interval amount. ("Start tick marks at first location"). Additionally, tick marks may be forced to appear at the first and last positions of each chromosome. • Scientific notation: Scientific notation can optionally be used for viewing very small or very large spans; this toggles whether or not to use it. • Tick mark precision: Determines how many decimal places to use in the tick mark labels. This can be automatically set by Kelviz, or manually set. • Divide tick marks by a number: Allows you to have tick mark labels divided by a common value. For example, if tick marks are placed at 10, 20, and 30 and this box is checked with a value of 10, then the labels that show up will be 1, 2, 3. This is most commonly used in conjunction with the "Add label to each tick mark" option immediately below to use abbreviations in tick mark labels. • Add label to each tick mark: Allows you to append a string (given in the text box) to every label. This is most commonly used in conjunction with the "Divide tick marks by a number" option immediately above to use abbreviations in tick mark labels in the same fashion as the Base-Pair scheme's "Use letters" option. For example, abbreviating tick marks by thousands can be done by setting "Divide tick marks by a number" to 1000 and setting "Add label to each tick mark" to K. ### Multiple Plots With The Same Data Kelviz has the ability to designate plots that use lines and line data from other plots. This allows for multiple presentations of the same dataset in your figure. To do this, one must first create a new, empty plot in the figure (this can be done via the Configure Figure Layout dialog - see Plot Location and Layout In The Figure, above), and then go to that plot's tab in the Configure Linesets dialog. Check the Use lines from another plot checkbox to turn on the option to show another plot's data within this plot as well. You will also need to select the plot whose data you want to share with this plot - all plots that currently have data imported into them will be listed. Plots that use lines and line data from other plots have their own view limits (see Zooms and Views, below), annotations (see Annotations, immediately below), tick mark options (see Tick Marks, immediately above), and horizontal lines (see Horizontal Lines, above). They do not have a Legend. Any data lines and/or marker maps (see Marker Map Overlays, below) are shared with the original "parent" plot, and their appearance must be configured within that plot - you cannot have a line appear to look one way in one plot and look differently in another. ## Annotations Annotations are text labels used to highlight and label data points of interest. Kelviz has several different options for creating and manipulating annotations, and can create them either one at a time or several at a time. By default, annotation text consists of: • the PPL value of the data point (expressed as a percentage) • an '@' symbol • the position of the data point (either in cM, or using a marker name if that has been imported via "Column(s) with extra data") These can be modified; see Modifying Annotation Defaults, below. ### Creating New Annotations New annotations can be quickly created by going into Annotate Point Mode. This is done by clicking the toolbar button illustrated to the right. In Annotate Point Mode, you can click on or near data points in a plot to create annotations for them. To leave Annotate Point Mode, click this button again. Alternatively, you can easily select a peak point or a valley point using one of the Annotate Peak or Annotate Valley modes. These are accessed respectively by clicking one of the toolbar buttons shown to the right. When one of these modes is turned on, you can click and drag to select a region on a plot containing a peak (or valley) that you want annotated. The data point(s) with the highest (or lowest) PPL value within that region will be annotated. NOTE: If you have two peaks with the exact same PPL value within the same selected region, Kelviz has no way of figuring out which of the two peaks you actually want, and so they will both be annotated. The same goes for any valleys. Keep this in mind when making your selection! To leave Annotate Peak or Annotate Valley mode, click the respective button again. Annotations can also be created en masse using the Annotate Threshold function. Access it by clicking the button illustrated to the right, or by going to the Edit menu and selecting Annotate Threshold. You will get a dialog box as follows: You will need to provide a threshold value and a threshold mode. The value is the Y-axis position (PPL value) that will serve as the threshold above or below which annotations will be created. The mode designates whether or not we're creating annotations above or below the threshold, and whether or not we just want peaks (or valleys), the boundaries of a peak, or all data points. ### Modifying Existing Annotations Annotations labels can be moved or edited to include other text. To move an annotation label, you must go into Annotation Movement Mode. This can be done by clicking on the toolbar button illustrated to the right. Once this mode is turned on, you can click on the text of any annotation and drag it to wherever you would like it to be positioned in the plot. When done moving annotations, click on the toolbar button again to turn this mode off. Alternatively, you can opt to use Kelviz's automatic annotation layout functionality. Do this by clicking on the Automatically Layout Annotations toolbar button (illustrated to the right) or by going to the Edit menu and selecting Automatically Layout Annotations. You will get a dialog box as follows: Reset annotations to default positions By default, annotations appear centered slightly above the datapoint that they are annotating. This option allows you to relocate all annotations in the selected plot or plots back to that default location. Automatically lay out annotations Kelviz will analyze the locations of all the annotations currently visible and attempt to place them optimally. WARNING: If you have a lot of annotations, this can take a very long time to complete! For other annotation editing functions, you can right-click on the annotation to get an editing menu, as illustrated below: The Remove Annotation menu option deletes the annotation. Edit Annotation brings up a dialog as illustrated below: Annotation Text and Use automatic text This is the current text of the annotation. Use automatic text toggles whether or not it is automatically generated; turn it off to edit the text to your liking. Annotation text so edited can include mathematical expressions and other special formatting; see Mathematical Expressions, below. Automatically include metadata This only has an effect if "Use automatic text" (above) is checked. If extra data was specified when creating the chromosomes (see Importing Data, above), then instead of showing the annotation position in centiMorgans, your annotation text will show its position using a marker name provided via that extra data. Font Size and Use default font size Changes the font size of the annotation text. Normally the default annotation font size is used; uncheck "Use default font size" to customize it for this particular annotation. Annotation Color and Use default color Changes the color of the annotation text. Normally the default annotation color is used; uncheck "Use default color" to customize it for this particular annotation. Annotation Visibility By default, annotations are always visible so long as the data point they annotate is visible. Optionally - by selecting Visible if we're only viewing the group the annotation is in - annotations can be made to only show up when zoomed into the group their data point is a part of - i.e. you can have an annotation for a data point along chromosome 6 that will only show up when zoomed into the chromosome 6 line group. All annotations can be deleted at once with one command. Go to the Edit menu and select Remove All Annotations. You will be prompted to confirm this action, as it cannot be undone. ### Modifying Annotation Defaults Default options for annotations are managed via the Configure Annotations dialog. To reach it, go to the Options menu and select Configure Annotations. Annotation PPL Precision This option determines the precision of the PPL value in the annotation. If set to "Default", two decimal places are shown, except when the PPL value is less than 0.02, in which case three decimal places are shown. The precision can also be set to a custom number of decimal places. Annotation Position Precision This option determines how many decimal places of precision should be used for the default position text in annotations (given in centiMorgans). This can be overridden by "Use extra data..." below (if your annotations are giving position using marker names instead). Default Annotation Color This determines what the default color of all annotations should be. This can be overridden by "Keep annotations the same color..." below. Keep annotations the same color as its line If checked, the color of annotations will be set the same as the color of the chromosome it is annotating. Useful when there are multiple, overlapping chromosomes. Default Annotation Font Size Sets the font size (in points) used by default for all annotations. Use percentages in annotation text By default, PPL values in annotations are represented as percentages. Unchecking this box will show PPL values in numeric form. (0.02 instead of 2%) Use extra data in place of position in annotation text If extra data was specified when creating the chromosomes (see Importing Data, above), this option will be checked by default. It indicates that instead of showing the position in centiMorgans, your annotations should show positions using marker names provided via that extra data. Annotation display is also subject to some performance-related defaults. To manage these, go to the Options menu and select Performance to reach the Performance dialog. Perform sampling on annotation If large numbers of annotations are present, this option exists to turn on annotation sampling, in which a subset of existing annotations are shown at any given time. (Annotations not displayed are listed without an asterisk in the Info Panel.) NOTE: These options are saved in GRX files and are specific to those; they are restored to defaults with each new GRX file you create in Kelviz. ## Zooms and Views Kelviz allows you to change whatever portion of a plot is displayed by way of panning around and zooming in and out; this can be done via manually entering values, or even interactively. Each "step" along the way - a pause while panning around, each point where one is zoomed in, et cetera - is called a view, and the history of such views is saved so that you can navigate back and forth between them. There is also a home view - a special "zoom out" in which all data points plotted are visible. Viewing options are normally handled through the toolbar, as follows: Home View Return to the "base view" - a view of every plot in which all data points plotted are visible. This affects all plots in the figure! Previous View Go back to the previous view (if any). A new view is set when a zoom or a pan occurs in any plot. Next View Go to the next view (if any). The oppsoite of the Previous View button. Pan Mode When turned on (by pressing this button once), you can pan around within a plot using the left mouse button. If you hold down the x key on the keyboard while dragging with the left mouse button, the plot will only drag horizontally (along the X axis). The y key can be similarly used to only drag vertically (along the Y axis). If you drag with the right mouse button, you can zoom in and out. Click this button again to turn this mode off. Zoom To Region Mode When turned on (by pressing this button once), you can click and drag to select a free-form region on a plot to zoom in. Click this button again to turn this mode off. Zoom To X-Axis Limits Mode When turned on (by pressing this button once), you can click and drag to select a horizontal region in the plot to zoom in to (along the X-axis). The Y-axis limits will be unchanged. Click this button again to turn this mode off. Zoom To Y-Axis Limits Mode When turned on (by pressing this button once), you can click and drag to select a vertical region in the plot to zoom in to (along the Y-axis). The X-axis limits will be unchanged. Click this button again to turn this mode off. Zoom To Chromosome Select a plot and a chromosome with the drop-down boxes, and then click on the magnifying glass icon to only show that chromosome in that plot. A precise view can also be set using the View Limits dialog. Access this by going to the Options menu and selecting Set x-axis, y-axis limits. xmin and xmax Minimum and maximum position values. Both of these require that you also specify a starting (or ending, respectively) chromosome, and the position values must be within the ranges allowed by each chromosome (shown to the right of the controls). The default is to show everything - xmin 0 on chromosome 1, and xmax of the furthest cM position on chromosome 23 (X). ymin and ymax Minimum and maximum PPL values. These are not subject to any value restrictions. The default is a range from 0% to 100% - 0.0 to 1.0. ## Marker Map Overlays Marker Map overlays are an additional means by which marker maps can be displayed in your plots and marker names can be added to your annotations. They show up as symbols overlaid on the lines plotted in your plot. You will likely have the necessary data file as part of your Kelvin analysis - it's the required "map file". Adding a new marker map overlay is done by going to the Insert menu and selecting Overlay Marker Map. You will be prompted for the filename for your marker map, and then presented with the Marker Map File Format dialog to tell Kelviz a little about your marker map. Plot to add markers to Indicates which plot you wish to add this marker map overlay to. Chromosome column Chooses which column (if any) lists the chromosome each datum is associated with. By default, Kelviz will look for a column named "Chromosome" or "Chr", and if it doesn't find one of those it will default to the first column in the datafile. Position Column Chooses which column lists chromosome position. By default, Kelviz will look for a column named "Position", "Pos", "cM", "Kosambi", or "Haldane" (roughly in that order), and if it doesn't find one of those it will default to the second column in the datafile. First line is header, not data Indicates that the first line of our marker map file is a header with column names in it, and therefore should not be used for processing. Turned on by default; if you have a marker map file that does not have such a header, you should turn this off. Marker Map Name Specifies the name of this marker map (for your reference only). This can be left blank if desired; by default it is "Marker Location" Size Specifies the size of the symbols used to display each marker location. Color Specifies a color for each marker symbol. Symbol Specifies the symbol shape to use for all markers being displayed. Column(s) with extra data Specifies if there are any columns in the datafile that you want to include as metadata or extra data. This is how you include the marker name or names. Multiple columns should be separated by commas or spaces. Metadata shows up in the window statusbar alongside Cursor Position Info (see Getting Started - The Main Kelviz Window, above), and will also show up by default in annotations of data points with metadata in place of position information (see Annotations, above). NOTE: Marker map overlays are only added to lines that are currently in the plot at the time they're imported. If you add new data lines after the marker map overlay has been added, they will NOT be overlaid. You will have to delete and readd the marker map if you want them overlaid. Marker map appearance (the size, color, and symbol shape) can be changed after importing by accessing the Configure Marker Map dialog. This is reached by going to the Options menu and selecting Configure Marker Map. Tabs are presented for each plot in your figure, and each such tab presents a row of controls for each marker map present in that plot. The functions of each control are identical to their counterparts in the Marker Map File Format dialog, above. ## Exporting Images Of Figures Images of Kelviz figures can be created at any time using the Export Image function. This can be done by clicking on the Export Figure To Image toolbar button (illustrated to the right), or by going to the File menu and selecting Export Figure To Color Image. You will be prompted for a filename. Images can also be exported as grayscale images; do this by going to the File menu and selecting Export Figure To Grayscale Image. ### Collages Kelviz has the ability to create image collages consisting of tables of subplots, for when you want one plot per lineset (genome) or one per chromosome from a single given plot in the figure. This table layout can also be applied to existing plots in the figure. Collages can be saved as images, or saved as Kelviz GRX files for further tweaking after generation. To create such a collage, go to the File menu and select Create Collage Table From Figure. Collage Type Selects a collage type. The available collage types are "chr" for one plot per chromosome line group in the source plot, "lineset" for one plot per lineset (genome) in the source plot, or "plot" for a collage consisting of multiple existing plots in the figure. Plot Selects the source plot from which chromosome line groups or linesets (for "chr" or "lineset" collage types) are selected. Disabled for "plot" collages. Columns in collage table Specifies the number of columns to arrange the subplots in. Kelviz takes this number and the number of subplots and adds as many rows as needed to make space for all subplots. Use plot autotitles Toggles whether or not automatic titles (such as "(a)", "(b)", "(c)", et cetera) should appear above each plot. If this is disabled, then you will have the option to give each plot its own custom title. If creating a "plot" type collage, this will override any titles those plots may already have! Show only one legend Shows only one figure-wide legend for all subplots, separate from those subplots. If disabled, every subplot will have its own legend (and those legends' positions can be customized on a per-subplot basis). Use "home view" of data Creates each subplot in the collage by first zooming out to a "home view" (in which all data points for that chromosome/genome/plot are made visible). Use current view limits Creates each subplot using the current plot view limits. This is the default behavior, and has subtly different behavior for each collage type. For "lineset" collages, this creates each subplot in the collage by getting the source plot's current X-axis and Y-axis view limits and applying them to each plot. For example, if you've zoomed in to a particular region of interest, that region will be the only portion of each lineset shown in the collage. For chromosome collages, this creates each subplot in the collage by getting the source plot's current Y-axis view limits and the X-axis limits for the chromosome in question, and applying them to each plot. For plot collages, this just arranges each plot with its view limits as is, with no changes. Collage size: Automatically Calculate Indicates that Kelviz should automatically calculate the collage's figure size, based on the figure size. This is the default behavior. Collage size: Calculate using this plot size Indicates that when creating the collage, each individual subplot should be of the specified height X width. The collage's figure size will be adjusted to accommodate plots of this size. Collage size: Set size Indicates that the entire collage should be the specified size. The sizes of subplots will be adjusted to fit within this size. For each (sub)plot, the following additional options are provided: Include this in the collage By default, every possible subplot is included in the collage; uncheck this to exclude the currently selected plot. Title Specifies a custom title for the currently selected plot. Use plot autotitles should be turned off or else this will have no effect! Legend Location Specifies a custom location for the legend in the currently selected plot. Show only one legend should be turned off or else this will have no effect! Custom Y-axis limits Specifies Y-axis view limits for the currently selected plot. ## Mathematical Expressions Any text that shows up in the figure - the figure title, axis titles, annotation labels, et cetera - can use TeX markup to display limited font formatting and mathematical symbols and expressions. Specify this by starting and ending your test with dollar signs. For example, alpha > beta will produce plain text, while $\alpha > \beta\$ will produce the greek letters, as shown:

becomes

You can use several other TeX symbols, such as \infty, \leftarrow, and \sum:

becomes

Other TeX symbols that can be used are listed on the matplotlib website.

To make subscripts and superscripts, use the _ and ^ symbols, respectively:

becomes

For some symbols, using a subscript means the text is placed underneath the symbol, and the superscript is placed above the symbol. This applies to symbols for which that behavior makes sense. Note how braces are used for subscripts or superscripts that are longer than one character:

becomes

The default font is italics. To use a different font, enclose the text you want in a different font in a font command, which essentially means type the font symbol, then the text you want in that font in braces. For example, to write the word 'sin' in a roman font:

becomes

Other fonts include roman \rm, italics \it, calligraphy \cal, and typewriter \tt:

becomes

## Command Line Options

There are command line options available to perform most actions in Kelviz. The syntax is as follows:

Python Script:
./kelviz.py <command1> <args1> <command2> <args2> ...
Alternate: python kelviz.py <command1> <args1> <command2> <args2> ...
OSX App Bundle:
Kelviz.app/Contents/MacOS/kelviz <command1> <args1> <command2> <args2> ...
Windows Application:
%programfiles%\kelviz.exe <command1> <args1> <command2> <args2> ...

If a command appears multiple times, generally the last occurrence will override any subsequent commands, with the notable exception of commands that work with files (-open, -save, -export, -import_data, and so forth).

Commands are performed in the order that they are specified, except in some special cases:

• -open is always performed first.
• -save and -export are always performed last.
• -min_gridsize is always performed near-last - only -save and -export are performed after it.

## Special Arguments

Starting with version 3.0.0, Kelviz allows you to have multiple plots within a single figure. Consequently, many command arguments now have a [plot=<name>] argument as their first possible argument. This indicates that that command expects to be given a reference to a plot that it's supposed to configure. This can be done either by providing the argument plot=<name> as the first argument to that command, or preceding that command with the -plot <name> command (which will also affect all following commands). For both of the above, <name> must be a valid plot name. Valid plot names are the lowercase letters "a" through "z", in order. If a plot is not specified, plot "a" is assumed.

Some commands that require that a plot be specified can take the argument plot=ALL, indicating that the command in question should be applied to every plot in the figure. Each command's documentation will indicate if this is possible.

Command arguments that ask for a lineset_id expect the internal ID of a lineset, but can also (sometimes) work with the name of a lineset. A lineset ID is specified when the data creating that lineset is initially imported and cannot be changed afterward.

Command arguments that ask for a line_id expect a special ID type, but can also (sometimes and unreliably) work with the name of a line. Line IDs consist of the name of the lineset the line is part of followed by __LINE_ followed by the chromosome number of that line.
Example 1: the line for chromosome 13 of lineset Example has the ID Example__LINE_13
Example 2: the line for chromosome X of lineset OtherExample has the ID OtherExample__LINE_23

Command arguments that are column indices start at 1, not 0.

Some command line arguments ask to specify a color. There are three options available to specify color:

1. Some colors are identified by a single letter. All available colors like this are: "b" - blue, "g" - green, "r" - red, "c" - cyan, "m" - magenta, "y" - yellow, "k" - black, "w" - white
2. You can specify colors by a hex value, for example "#0022ff" (Note the "#" instead of "x" for a hex value). If you do this, be sure to put quotes around the color value!
3. You can specify a name of a color in the X11 color set, for example "Turquoise", "PapayaWhip", or "Olive". For a listing of what colors are available, goto http://www.mcfedries.com/books/cightml/x11color.htm. Note that not all colors may work.

## Basic Commands

-version
Prints current Kelviz version and exits (WITHOUT executing other commands).
-help
Opens the Kelviz User's Manual in a web browser and exits (WITHOUT executing other commands).
-open <filename>
Opens an existing GRX (Kelviz figure) file.
Without this, Kelviz will assume we're creating a new figure from scratch.
<filename> -- Path to GRX file.
<filename>
If you specify a GRX file on the command line as the first argument, Kelviz will open it for you as -open above.
<filename> -- Path to GRX file.
-save <filename>
Saves the figure we're working on as a GRX file.
<filename> -- Path to a file. If the .grx extension is not present in at the end of the filename, it is added on automatically.
-noshow
Specifies command-line only operation; does not show the GUI window and exits as soon as all other commands are completed.
-plot <name>
Specifies that all following commands (except any that have plot=<name> as their first argument) are intended to configure the named plot. See "Special Arguments", above.
If the plot does not exist, it will be created.
If this command is omitted, plot "a" is assumed.
<name> - A plot name. Valid plot names are lowercase letters "a" through "z", in order.
-no_warnings
Kelviz normally prints warning messages for Deprecated Commands (see below). Include this option to turn those warning messages off.

## Command Files

Starting with version 2.2.0, Kelviz has a "command files" capability - you can give it text files that consist of one command per line and it will execute them.

Lines in a command file starting with # are ignored.

There are two ways you can take advantage of command files:

• by creating a file called .kelvizcmd in the directory you're executing Kelviz in and putting your commands there,
• by using the -command_file option (see below)

Both can be used simultaneously, and concurrently with other command line options, and you can add multiple command files. The order of precedence is as follows:

• .kelvizcmd commands are added first
• then come -command_file commandfiles (in the order that they're specified on the command line)

Then each command is performed in the order it's specified, subject to the special cases listed above in re: -open, -save, and -export.

-command_file <filename>
Gets commands from a text file containing a list of command line arguments and executes them.
<filename> -- The name of the text file containing the command line arguments.

## Datafile Import Commands

These add new lines and linesets to a plot.

All options that start with -data_ are dependent on a corresponding -import_data command, which they must follow. If you're importing multiple data files (or multiple sets of data from the same file), make sure that each set of -data_ commands only follows its respective -import_data and no other.

-import_plot <filename> <sourceplotname>
Opens a GRX file containing one or more plots and imports that plot into our current figure.
<filename> -- Path to the GRX file from which we are importing our plot.
<sourceplotname> -- The name of the plot we'll be loading from the GRX file.
-import_data [plot=<name>] <filename>
Opens a text file containing chromosome data and either overlaps an existing plot's chromosomes with that data, adds additional chromosomes to an existing lineset (if they don't already exist), or (if we don't have an existing plot) creates a new one with the data.
[plot=<name>] -- Optional; specifies which plot we're importing data into. (See Special Arguments, above.)
<filename> -- Path to the datafile we're importing.
-data_pos_col <column>
Sets the column in our data file that specifies the chromosome position for each datum - the X-axis value in our plots.
If left out, we attempt to guess which column represents the position based on headers in the datafile. The guesses we look for (in priority order) are: position, pos, cm, kosambi, haldane, position1, position2.
If our datafile has NO headers, we assume the second column in the file (if there's three or more columns) or the first (if there's only two).
Used only with -import_data and otherwise ignored. Must come after the -import_data it is intended to configure and no other.
<column> -- Column with chromosome position values (x-axis). Specified by name of column in file (if there's a header line) OR column index number.
-data_ppl_col <column>
Sets the column in our data file that specifies the PPL (or any other probability measure) for each datum - the Y-axis value in our plots.
If left out, we attempt to guess which column represents the PPL based on headers in the datafile. The guesses we look for (in priority order) are: ppl, ppl(ld), ppld|l, ppld
If our datafile has NO headers, we assume the third column in the file (if there's three or more columns) or the second (if there's only two).
Used only with -import_data and otherwise ignored. Must come after the -import_data it is intended to configure and no other.
<column> -- Column with PPL values (x-axis). Specified by name of column in file (if there's a header line) OR column index number.
-data_chr_col <column>
Sets the column in our data file that specifies chromosome numbers for each datum.
If left out, we look for a column named chromosome or chr and use it. If we can't find one of those, we check -data_chr_num (see below). If that's left out, we assume that each blank newline-separated "section" constitutes a new chromosome.
Used only with -import_data and otherwise ignored. Must come after the -import_data it is intended to configure and no other.
<column> -- Column with chromosome numbers. Specified by name of column in file (if there's a header line) OR column index number.
-data_lineset <lineset_id>
Specifies the lineset we want to add this datafile to. By default, Kelviz will create a lineset with the same name as the datafile's filename (or the name of the PPL column if it's not called "PPL"); use this option to override that behavior.
If you specify a lineset ID that already exists, by default Kelviz will replace that lineset's data with the data being imported. If you wish to add to the lineset's data (say, if you're importing a full genome one chromosome at a time), see -data_lineset_replace below.
Used only with -import_data and otherwise ignored. Must come after the -import_data it is intended to configure and no other.
<lineset_id> -- Text ID for the lineset we're adding data to. (See Special Arguments, above.) If the lineset doesn't exist, it will be created. No spaces or special punctuation characters are permitted in this ID!
-data_overlap <on/off>
Forces whether or not we want to overlap existing chromosomes in our plot with the data in this datafile.
Used only with -import_data and otherwise ignored. Must come after the -import_data it is intended to configure and no other.
<on/off> -- Turn this option ON or OFF. Defaults to ON if we're creating a new lineset for an existing plot, and OFF otherwise.
-data_lineset_replace <on/off>
Forces whether or not we want to use the data we're importing to create a new lineset, or replace the data for an existing lineset (specified by -data_lineset above).
When replacing an existing lineset's data, the following options are ignored:
-data_lineset, -data_overlap, -data_chr_prefix, -data_chr_postfix, -data_line_color, -data_color_per_line
Used only with -import_data and otherwise ignored. Must come after the -import_data it is intended to configure and no other.
<on/off> -- Turn this option ON or OFF. Defaults to ON if this data's lineset ID (see -data_lineset above) already exists, and OFF otherwise.
-data_use_header_line <on/off>
Controls whether or not we treat the first line of our data file as a header line (with column names).
Used only with -import_data and otherwise ignored. Must come after the -import_data it is intended to configure and no other.
<on/off> -- Turn this option ON or OFF. Defaults to ON.
-data_chr_num <chr_num>
If our text file only has info about one chromosome (and that's not specified in the text file), this tells Kelviz what chromosome that is.
Used only with -import_data and otherwise ignored. Must come after the -import_data it is intended to configure and no other.
<chr_num> -- Chromosome number this text file has data for. Integer value (1-24) only.
-data_chr_select <chr1> <chr2> ...
Selects only some chromosomes from our datafile to be loaded in.
Used only with -import_data and otherwise ignored. Must come after the -import_data it is intended to configure and no other.
<chrX> -- Series of chromosome numbers to load.
-data_chr_prefix <prefix>
Changes the name of each chromosome line to be imported from our datafile by adding a prefix string before every chromosome number.
Used only with -import_data and otherwise ignored. Must come after the -import_data it is intended to configure and no other.
<prefix> -- Prefix for each chromosome number.
-data_chr_postfix <postfix>
Changes the name of each chromosome line to be imported from our datafile by adding a postfix string after every chromosome number.
Used only with -import_data and otherwise ignored. Must come after the -import_data it is intended to configure and no other.
<postfix> -- Postfix for each chromosome number.
-data_metadata_cols <column1> <column2> ...
Designates columns in our datafile that contain metadata associated with each point.
Used to specify marker names for each point when moving the cursor over the plot and when creating annotations.
Used only with -import_data and otherwise ignored. Must come after the -import_data it is intended to configure and no other.
<columnX> -- Series of columns that contain metadata we want to include. Specified by name of column in file (if there's a header line) OR column index number.
-data_line_color <color>
Indicates what color we want the line or lines we're importing from this datafile to be. Can be overridden by -lineset_color and -line_color options if they appear!
If omitted, then Kelviz will assign a color or colors by cycling through a list of predefined colors; see -data_cycle_color_by_lines below.
Used only with -import_data and otherwise ignored. Must come after the -import_data it is intended to configure and no other.
<color> -- The color desired for the line(s).
-data_color_per_line <on/off>
Kelviz has a list of predefined colors it automatically cycles through when colors are not designated for new lines. By default, it assigns a single color for every line in the dataset you're importing. If you're importing multiple lines, you can turn this option ON to have Kelviz assign new colors for each and every line imported in this dataset.
Can be overridden by -data_line_color, -lineset_color, and -line_color options if they appear!
Used only with -import_data and otherwise ignored. Must come after the -import_data it is intended to configure and no other.
<on/off> -- Turn this option ON or OFF. Defaults to OFF.
-data_missing_value_tokens <token1> <token2> ...
Specifies certain values that indicate missing data. If any of these values are found in the ppl column, the line will be skipped.
Tokens cannot contain a comma or any whitespace.
Multiple tokens can be specified.
The string "." is already included by default.
Used only with -import_data and otherwise ignored. Must come after the -import_data it is intended to configure and no other.
<tokenX> -- Series of numbers or strings of any kind indicating what data values indicate lines to be skipped.

## Plot Line and Lineset Modification Commands

These change lines and linesets that already exist in a plot.

All of these commands require that a plot be specified and/or a lineset_id or line_id be specified; see Special Arguments (above) for information on these arguments.

-use_other_plot_lines [plot=<name>] <plot>
Specifies that this plot should use the same data lines as another plot. Used to create alternate views of the same data within a figure.
[plot=<name>] -- Optional; specifies the plot that will be displaying data lines from another plot. (See Special Arguments, above.)
<plot> -- The name of the plot whose lines will be reused in another plot. Valid plot names are the lowercase letters "a" through "z", in order.
-lineset_name [plot=<name>] <lineset_id> <name>
Gives a name to this lineset. Names are used in the Legend.
[plot=<name>] -- Optional; specifies which plot the lineset is in. (See Special Arguments, above.)
<lineset_id> -- Text ID for the lineset we're configuring. (See Special Arguments, above.)
<name> -- The name. (Be sure to put quotes around it!)
-lineset_color [plot=<name>] <lineset_id> <color>
Changes the color of all chromosome lines in a lineset.
[plot=<name>] -- Optional; specifies which plot the lineset is in. (See Special Arguments, above.)
<lineset_id> -- Text ID for the lineset we're configuring. (See Special Arguments, above.)
<color> -- The color desired for the lines.
-lineset_linestyle [plot=<name>] <lineset_id> <style>
Sets the line style of all chromosome lines in a lineset.
[plot=<name>] -- Optional; specifies which plot the lineset is in. (See Special Arguments, above.)
<lineset_id> -- Text ID for the lineset we're configuring. (See Special Arguments, above.)
<style> -- The style desired for the lines.
Valid styles: solid, dashed, dotted, dash-dot, steps, no line.
Default is solid.
-lineset_thickness [plot=<name>] <lineset_id> <thickness>
Changes the thickness of all chromosome lines in a lineset.
[plot=<name>] -- Optional; specifies which plot the lineset is in. (See Special Arguments, above.)
<lineset_id> -- Text ID for the lineset we're configuring. (See Special Arguments, above.)
<thickness> -- How thick the chromosome lines should be. Integer values only. Default is 2.
-lineset_symbol [plot=<name>] <lineset_id> <symbol>
Changes the symbol that represents each data point for all chromosome lines in a lineset.
[plot=<name>] -- Optional; specifies which plot the lineset is in. (See Special Arguments, above.)
<lineset_id> -- Text ID for the lineset we're configuring. (See Special Arguments, above.)
<symbol> -- Name of the symbol type. (Be sure to put quotes around the name!)
Valid symbols: no symbol, caret down, caret left, caret right, caret up, circle, diamond, hexagon 1, hexagon 2, horizontal line, octagon, pentagon, pixel, plus, point, square, star, thin diamond, tick down, tick left, tick right, tick up, tripod down, tripod left, tripod right, tripod up, triangle down, triangle left, triangle right, triangle up, vertical line, x
Default is no symbol.
-lineset_symbol_size [plot=<name>] <lineset_id> <size>
Changes the size of the symbol for all chromosome lines in a lineset.
[plot=<name>] -- Optional; specifies which plot the lineset is in. (See Special Arguments, above.)
<lineset_id> -- Text ID for the lineset we're configuring. (See Special Arguments, above.)
<size> -- Size of the symbol (approximately the radius in pixels). Integer values only. Default is 6.
-lineset_zorder [plot=<name>] <lineset_id> <order>
Sets what priority this lineset has when it comes time to draw linesets. A lineset with a higher z-order is drawn on top of linesets with lower z-order values.
[plot=<name>] -- Optional; specifies which plot the lineset is in. (See Special Arguments, above.)
<lineset_id> -- Text ID for the lineset we're configuring. (See Special Arguments, above.)
<order> -- Order in which to draw this line. Integer values only. Default is in sequence from first lineset imported to last.
-line_name [plot=<name>] <line_id> <name>
Gives a name to this line. Names are used along the x-axis (this can be controlled with -show_line_names, below), and (with the -legend_show_linesets option) optionally in the Legend.
By default, the name of a line is set to the chromosome number it's associated with. You can and will have multiple lines with the same name as a result.
[plot=<name>] -- Optional; specifies which plot the line is in. (See Special Arguments, above.)
<line_id> -- Text ID of the line we're configuring. (See Special Arguments, above.)
<name> -- The name. (Be sure to put quotes around it!)
-line_color [plot=<name>] <line_id> <color>
Changes the color of a line. This can be overridden by -lineset_color if it's specified!
[plot=<name>] -- Optional; specifies which plot the line is in. (See Special Arguments, above.)
<line_id> -- Text ID of the line we're configuring. (See Special Arguments, above.)
<color> -- The color desired for the line.
-line_linestyle [plot=<name>] <line_id> <style>
Sets the line style of a line. This can be overridden by -lineset_linestyle if it's specified!
[plot=<name>] -- Optional; specifies which plot the line is in. (See Special Arguments, above.)
<line_id> -- Text ID of the line we're configuring.
<style> -- The style of the line.
Valid styles: solid, dashed, dotted, dash-dot, steps, no line.
Default is solid if the lineset the line is part of hasn't been changed and is equal to that lineset's style otherwise.
-line_thickness [plot=<name>] <line_id> <thickness>
Changes the thickness of a line. This can be overridden by -lineset_thickness if it's specified!
[plot=<name>] -- Optional; specifies which plot the line is in. (See Special Arguments, above.)
<line_id> -- Text ID of the line we're configuring. (See Special Arguments, above.)
<thickness> -- How thick the line should be. Integer values only. Default is 2.
-line_symbol [plot=<name>] <line_id> <symbol>
Changes the symbol that represents each data point on the line. This can be overridden by -lineset_symbol if it's specified!
[plot=<name>] -- Optional; specifies which plot the line is in. (See Special Arguments, above.)
<line_id> -- Text ID of the line we're configuring. (See Special Arguments, above.)
<symbol> -- Name of the symbol type. (Be sure to put quotes around the name!)
Valid symbols: no symbol, caret down, caret left, caret right, caret up, circle, diamond, hexagon 1, hexagon 2, horizontal line, octagon, pentagon, pixel, plus, point, square, star, thin diamond, tick down, tick left, tick right, tick up, tripod down, tripod left, tripod right, tripod up, triangle down, triangle left, triangle right, triangle up, vertical line, x
Default is no symbol if the lineset the line is part of hasn't been changed and is equal to that lineset's symbol otherwise.
-line_symbol_size [plot=<name>] <line_id> <size>
Changes the size of the symbol for a line. This can be overridden by -lineset_symbol_size if it's specified!
[plot=<name>] -- Optional; specifies which plot the line is in. (See Special Arguments, above.)
<line_id> -- Text ID of the line we're configuring. (See Special Arguments, above.)
<size> -- Size of the symbol (approximately the radius in pixels). Integer values only. Default is 6 if the lineset the line is part of hasn't been changed and is equal to that lineset's symbol size otherwise.
-hline [plot=<name>] <num1> <num2> ...
Creates horizontal line(s) in the plot.
Can be specified multiple times; will create new horizontal lines each time.
[plot=<name>] -- Optional; specifies which plot we're creating a horizontal line in. (See Special Arguments, above.)
<numX> -- Series of y-values (PPL values) of the line(s) to be added.

## Figure Modification and Configuration Commands

These change options that affect the entire figure.

-comment <comment>
Specifies a comment or comments in the "comment box" that shows up on the side of the figure in the GUI.
If there are existing comments, they will be overwritten by what you specify with this option!
<comment> -- The comments. (Be sure to put quotes around them!)
-figure_title <title>
Sets the title of the figure. Will appear above the figure.
<title> -- Figure title. (Be sure to put quotes around it!)
-figure_title_text_size <size>
Indicates a font size for the figure title.
<size> -- Font size, in points. Integer values only. Default is 14.
-plot_autotitles <on/off>
Toggles whether or not we want to specify titles for each plot or if we want plot titles to be automatically generated (as "(a)", "(b)", "(c)", etc.).
<on/off> -- Turn this option ON or OFF. Defaults to ON.
-serif_fonts <on/off>
Toggles whether or not we want to display all text in the figure using a serif font instead of the usual sans-serif font.
<on/off> -- Turn this option ON or OFF. Defaults to OFF.
-show_figure_legend <on/off>
Toggles the figure-wide legend on or off. The figure-wide legend is shown separate from all other plot(s), and contains the legend entries from all of them.
This option overrides -show_legend by automatically disabling all plot- specific legends!
<on/off> -- Turn this option ON or OFF. Defaults to OFF.
-figure_legend_location <loc>
Specifies a location for the figure-wide legend.
<loc> -- The desired legend location. (Be sure to put quotes around it!)
Valid locations: center left, center right, in grid.
Default is center right.
-figure_legend_text_size <size>
Indicates a font size for the figure legend.
<size> -- Font size, in points. Integer values only. Default is 14.
-figure_legend_gridloc <rowstart> <rowend> <colstart> <colend>
Specifies, using Kelviz's layout grid, where the figure legend is to be located relative to the plots in the graph.
This only applies if -figure_legend_location is set to in grid!
NOTE: Legend size is NOT automatically adjusted for available space. Some experimentation may be necessary.
<rowstart> -- Row that the legend should start in in the layout grid. Integer values only.
<rowend> -- Row that the legend should end in in the layout grid. Integer values only.
<colstart> -- Column that the legend should start in in the layout grid. Integer values only.
<colend> -- Column that the legend should end in in the layout grid. Integer values only.
-ann_ppl_precision <precision>
Specifies the amount of PPL precision to display in annotations.
By default, two decimal places are used (i.e. "7%"), except when the PPL is less than .02 (2%), in which case it will show up to three decimal places (i.e. 1.2%)
<precision> -- The precision level to use. The keyword default can be used to set default precision mode as described above; otherwise, integer values only.
-ann_pos_precision <num>
Specifies how many decimal places to show for the position number in the text of an annotation.
<num> -- Number of decimal places to show. Default is 0.
-ann_show_percent <on/off>
Toggle whether or not to use percentage values for the PPL in annotation text (i.e. do we represent a PPL of 0.05 as "0.05" (OFF) or "5%" (ON)).
<on/off> -- Turn this option ON or OFF. Defaults to ON.
-ann_same_color <on/off>
Toggle whether or not annotation text should be the same color as the line it is associated with. The alternative is that all annotations are a single default color (see -ann_default_color, below).
<on/off> -- Turn this option ON or OFF. Defaults to OFF.
-ann_default_color <color>
Changes the color used by default for annotation text.
This can be overridden on a per-annotation basis! (See -ann_color, below)
<color> -- The desired default annotation color. Default is "black".
-ann_default_fontsize <size>
Changes the font size used by default for annotation text.
This can be overridden on a per-annotation basis! (See -ann_fontsize, below)
<size> -- Font size, in points. Integer values only. Default is 12.
-ann_use_metadata <on/off>
If metadata has been loaded (see -data_metadata_cols above or -markermap_metadata_cols below), this toggles whether or not to use that metadata in place of the position in annotation text.
<on/off> -- Turn this option ON or OFF. Defaults to ON.
-figure_size <width> <height>
Specifies the desired size of the figure, in inches.
<width> -- Width of the figure, in inches. Defaults to 10.
<height> -- Height of the figure, in inches. Defaults to 8.
-figure_padding <padding>
Specifies the padding the figure should have around the edge. Padding is done in increments of 12 points.
<padding> -- The desired amount of padding. Defaults to 1.
-min_gridsize <rows> <cols>
Specifies the minimum number of rows and columns to be used in Kelviz's layout grid. This can be overridden if each plot takes up more rows and columns than are provided for here.
<rows> -- Number of rows. Integer values only. Default is 1.
<cols> -- Number of columns. Integer values only. Default is 1.
-export_dpi <dpi>
Sets the DPI of any images we want to export of this figure.
<dpi> -- DPI (dots per inch) value for exported images. Integer values only. Defaults to 300.

## Plot Modification And Configuration Commands

These change options that affect a single plot or multiple plots.

-plot_title [plot=<name>] <title>
Sets the title of the given plot. Will appear above and to the left of the plot.
[plot=<name>] -- Optional; specifies which plot we're changing the title for. Can change all plots simultaneously with plot=ALL. (See Special Arguments, above.)
<title> -- Plot title. (Be sure to put quotes around it!)
-plot_title_text_size [plot=<name>] <size>
Indicates a font size for the plot title.
[plot=<name>] -- Optional; specifies which plot we're changing the title font size for. Can change all plots simultaneously with plot=ALL. (See Special Arguments, above.)
<size> -- Font size, in points. Integer values only. Default is 12.
-xlabel [plot=<name>] <label>
Sets a label for the x-axis for the specified plot(s).
[plot=<name>] -- Optional; specifies which plot we're changing the x-axis label for. Can change all plots simultaneously with plot=ALL. (See Special Arguments, above.)
<label> -- x-axis label. (Be sure to put quotes around it!)
-ylabel [plot=<name>] <label>
Sets a label for the y-axis for the specified plot(s).
[plot=<name>] -- Optional; specifies which plot we're changing the y-axis label for. Can change all plots simultaneously with plot=ALL. (See Special Arguments, above.)
<label> -- y-axis label. (Be sure to put quotes around it!)
-axis_text_size [plot=<name>] <size>
Specifies a font size of the x and y-axis labels for the specified plot(s).
[plot=<name>] -- Optional; specifies which plot we're changing the axis label font size for. Can change all plots simultaneously with plot=ALL. (See Special Arguments, above.)
<size> -- Font size, in points. Integer values only. Default is 12.
-xlabel_padding [plot=<name>] <padding>
Specifies additional padding to be put in between the X-axis label and the bottom of the plot(s).
[plot=<name>] -- Optional; specifies which plot we're adding xlabel padding to. Can change all plots simultaneously with plot=ALL. (See Special Arguments, above.)
<padding> -- Padding amount, in points. Integer values only. Default is 0.
-bgcolor [plot=<name>] <color>
Set the background color for the specified plot(s).
This is the color within the plot (where our plotted data is), not outside of the figure (where labels are).
[plot=<name>] -- Optional; specifies which plot we're changing the background color for. Can change all plots simultaneously with plot=ALL. (See Special Arguments, above.)
<color> -- Background color. Default is "white" (#FFFFFF)
-show_legend [plot=<name>] <on/off>
Forces the legend for the specified plot(s) to be turned on or off.
This can be overridden by -show_figure_legend, above!
[plot=<name>] -- Optional; specifies which plot we're turning the legend on or off for. Can change all plots simultaneously with plot=ALL. (See Special Arguments, above.)
<on/off> -- Turn this option ON or OFF. Defaults to OFF if there's only one lineset and ON if we have more than one lineset.
-show_legend_frame [plot=<name>] <on/off>
Toggles a frame around the specified plot(s)' legend.
[plot=<name>] -- Optional; specifies which plot we're toggling the legend frame for. Can change all plots simultaneously with plot=ALL. (See Special Arguments, above.)
<on/off> -- Turn this option ON or OFF. Defaults to ON.
-legend_show_linesets [plot=<name>] <on/off>
Sets whether or not the specified plot(s)' legend lists linesets (ON) or list individual lines (OFF).
[plot=<name>] -- Optional; specifies which plot we're changing the legend listing for. Can change all plots simultaneously with plot=ALL. (See Special Arguments, above.)
<on/off> -- Turn this option ON or OFF. Defaults to ON.
-legend_location [plot=<name>] <loc>
Specifies where the legend should be located on the specified plot(s).
[plot=<name>] -- Optional; specifies which plot we're changing the legend location for. Can change all plots simultaneously with plot=ALL. (See Special Arguments, above.)
<loc> -- The desired legend location. (Be sure to put quotes around the name!)
Valid locations: upper right, upper left, upper center, lower right, lower left, lower center, center left, center right, center.
Default is upper right.
-legend_text_size [plot=<name>] <size>
Indicates a font size for the legend.
[plot=<name>] -- Optional; specifies which plot we're changing the legend font size for. Can change all plots simultaneously with plot=ALL. (See Special Arguments, above.)
<size> -- Font size, in points. Integer values only. Default is 14.
-show_line_names [plot=<name>] <on/off>
Toggles whether or not to show the chromosome number labels along the X-axis of the plot.
[plot=<name>] -- Optional; specifies which plot we're toggling the chromosome number labels for. Can change all plots simultaneously with plot=ALL. (See Special Arguments, above.)
<on/off> -- Turn this option ON or OFF. Defaults to ON.
-label_text_size [plot=<name>] <size>
Indicates a font size for the chromosome number labels along the X-axis of the plot.
[plot=<name>] -- Optional; specifies which plot we're changing the label font size for. Can change all plots simultaneously with plot=ALL. (See Special Arguments, above.)
<size> -- Font size, in points. Integer values only. Default is 12.
-use_condensed_line_name_font [plot=<name>] <on/off>
The chromosome number labels along the X-axis of the plot have the option to use a condensed font so that they fit into the plot; this toggles that option.
[plot=<name>] -- Optional; specifies which plot we're toggling the condensed font option for. Can change all plots simultaneously with plot=ALL. (See Special Arguments, above.)
<on/off> -- Turn this option ON or OFF. Defaults to OFF.
-chr23_rename_X [plot=<name>] <on/off>
Toggles whether or not lines associated with chromosome 23 will receive the name "X" by default (instead of "23").
[plot=<name>] -- Optional; specifies which plot we're toggling the rename option for. Can change all plots simultaneously with plot=ALL. (See Special Arguments, above.)
<on/off> -- Turn this option ON or OFF. Defaults to ON.
-chr24_rename_Y [plot=<name>] <on/off>
Toggles whether or not lines associated with chromosome 24 will receive the name "Y" by default (instead of "24").
[plot=<name>] -- Optional; specifies which plot we're toggling the rename option for. Can change all plots simultaneously with plot=ALL. (See Special Arguments, above.)
<on/off> -- Turn this option ON or OFF. Defaults to ON.
-plot_gridloc [plot=<name>] <rowstart> <rowend> <colstart> <colend>
Specifies, using Kelviz's layout grid, where the plot is to be located relative to any other plots.
[plot=<name>] -- Optional; specifies which plot we're changing the location of. (See Special Arguments, above.)
<rowstart> -- Row that the plot should start in in the layout grid. Integer values only.
<rowend> -- Row that the plot should end in in the layout grid. Integer values only.
<colstart> -- Column that the plot should start in in the layout grid. Integer values only.
<colend> -- Column that the plot should end in in the layout grid. Integer values only.
-xlimits [plot=<name>] <xmin_chr> <xmin_pos> <xmax_chr> <xmax_pos>
This takes two sets of chromosome names and positions along those chromosomes for the limits; the first set is xmin, and the second set is xmax.
[plot=<name>] -- Optional; specifies which plot we're changing view limits for. Can change all plots simultaneously with plot=ALL. (See Special Arguments, above.)
<xmin_chr> -- Name of the chromosome that the minimum X position should appear along.
<xmin_pos> -- The minimum X value, specified as a position along <xmin_chr>.
<xmax_chr> -- Name of the chromosome that the maximum X position should appear along.
<xmax_pos> -- The maximum X value, specified as a position along <xmax_chr>.
-ylimits [plot=<name>] <ymin> <ymax>
Set the Y-axis limits of the plot view.
[plot=<name>] -- Optional; specifies which plot we're changing view limits for. Can change all plots simultaneously with plot=ALL. (See Special Arguments, above.)
<ymin> -- The minimum Y value. Real number values only.
<ymax> -- The maximum Y value. Real number values only.
-view_limits [plot=<name>] <xmin_chr> <xmin_pos> <xmax_chr> <xmax_pos> <ymin> <ymax>
This is a convenient shorthand for the -xlimits and -ylimits commands listed above. See those commands for descriptions of this command's parameters.
-zoom_chr [plot=<name>] <chr_num>
Set X-axis limits such that they start and end at the beginning and end of a particular chromosome.
This does not affect the Y-axis limits of the plot.
[plot=<name>] -- Optional; specifies which plot we're changing view limits for. Can change all plots simultaneously with plot=ALL. (See Special Arguments, above.)
<chr_num> -- The number of the chromosome to zoom in to. Integer values only.
-tick_text_size [plot=<name>] <size>
Indicates a font size for each plot's tick labels.
[plot=<name>] -- Optional; specifies which plot we're changing the tick mark font size for. Can change all plots simultaneously with plot=ALL. (See Special Arguments, above.)
<size> -- Font size, in points. Integer values only. Default is 11.
-tick_mode [plot=<name>] <mode>
Sets what mode to use when placing tick marks along the x-axis.
The normal mode (default) is designed to be used for genome-wide chromosome plots.
There is also a present mode for plots that plot chromosome base-pair locations (base-pairs). The tick interval is 500,000, and tick marks are always shown at even multiples of the interval.
Alternatively, a custom tick mode can be designed using the options below.
[plot=<name>] -- Optional; specifies which plot we're changing tickmark parameters for. (See Special Arguments, above.)
<mode> -- The tick mode desired.
Valid modes: default, base-pairs, custom.
Default is default.
-tick_interval <size>
Specifies the interval (number of units) between each successive tick mark.
If this option is omitted, a suitable tick interval is computed automatically.
Used only with -tick_mode custom above and otherwise ignored.
<size> -- Interval size. Real number values only.
-tick_placement <placement>
Designates how tick marks are supposed to start placement.
Ticks can either be always placed at even multiples of the tick interval, or always start at the first available position and then be offset by the tick interval amount.
Used only with -tick_mode custom above and otherwise ignored.
<placement> -- The desired placement option.
Valid placements: even_multiples, first_position.
Default is even_multiples.
-tick_scientific_notation <on/off>
Toggles whether or not to use scientific notation to represent tick mark numbers. Useful when displaying very small or very large numbers.
Used only with -tick_mode custom above and otherwise ignored.
<on/off> -- Turn this option ON or OFF. Defaults to OFF.
-tick_precision <num>
Specifies the number of decimal places to show for tick mark numbers.
If this option is omitted, then a suitable tick precision is automatically computed.
Used only with -tick_mode custom above and otherwise ignored.
<num> -- Number of decimal places to show. Integer values only.
-tick_include_first_position <on/off>
Toggles whether or not to always include the first position of the chromosome in the tick marks.
Used only with -tick_mode custom above and otherwise ignored.
<on/off> -- Turn this option ON or OFF. Defaults to OFF.
-tick_include_last_position <on/off>
Toggles whether or not to always include the last position of the chromosome in the tick marks.
Used only with -tick_mode custom above and otherwise ignored.
<on/off> -- Turn this option ON or OFF. Defaults to OFF.

## Marker Map Commands

These add marker map overlays to a plot.

All options that start with -markerdata_ are dependent on a corresponding -import_markermap_data command, which they must follow. If you're adding multiple marker maps to your plot, make sure that each set of -markerdata_ commands only follows its respective -import_markermap_data and no other.

-import_markermap_data [plot=<name>] <filename>
Opens a text file containing a list of markers (by chromosome and position) and overlays them on existing linesets in the plot in the form of a series of symbols.
[plot=<name>] -- Optional; specifies which plot we're adding the marker map to. (See Special Arguments, above.)
<filename> -- Path to the marker map datafile we're importing. The filename (with the path and extension stripped) also serves as the default name of the marker map.
-markerdata_chr_col <column>
Sets the column in our data file that specifies chromosome numbers for each marker.
If left out, we look for a column named chromosome or chr and use it. If that's left out, we assume that each blank newline-separated "section" constitutes a new chromosome.
Used only with -import_markermap_data and otherwise ignored. Must come after the -import_markermap_data it is intended to configure and no other.
<column> -- Column with chromosome numbers. Specified by name of column in file (if there's a header line) OR column index number.
-markerdata_pos_col <column>
Sets the column in our data file that specifies the chromosome position for each marker.
If left out, we attempt to guess which column represents the position based on headers in the datafile. The guesses we look for (in priority order) are: position, pos, cm, kosambi, haldane, position1, position2.
If our datafile has NO headers, we assume the second column in the file (if there's three or more columns) or the first (if there's only two).
Used only with -import_markermap_data and otherwise ignored. Must come after the -import_markermap_data it is intended to configure and no other.
<column> -- Column with chromosome position values. Specified by name of column in file (if there's a header line) OR column index number.
-markerdata_use_header_line <on/off>
Controls whether or not we treat the first line of our marker map file as a header line (with column names).
Used only with -import_markermap_data and otherwise ignored. Must come after the -import_markermap_data it is intended to configure and no other.
<on/off> -- Turn this option ON or OFF. Defaults to ON.
-markerdata_metadata_cols <column1> <column2>
Designates columns in our marker map file that contain metadata associated with each marker (such as the SNP name).
Metadata so included is listed before any metadata included as part of a lineset import (such as from using the -data_metadata_cols command, above).
Used only with -import_markermap_data and otherwise ignored. Must come after the -import_markermap_data it is intended to configure and no other.
<columnX> -- Series of columns that contain metadata we want to include. Specified by name of column in file (if there's a header line) OR column index number.
-marker_map_name [plot=<name>] <oldname> <newname>
Changes the name of this set of markers. Marker set names are generally only used with the -marker_map_ commands.
[plot=<name>] -- Optional; specifies which plot contains the marker map we're renaming. (See Special Arguments, above.)
<oldname> - The existing marker map name. By default, this is the name of the datafile used to create the marker map (example: a marker map datafile named "markers2.txt" would, on import, be given the name "markers2").
<newname> - The name you want to give to this marker map. No spaces or special punctuation characters are permitted in this name!
-marker_map_size [plot=<name>] <name> <size>
Changes the symbol size of a set of markers.
[plot=<name>] -- Optional; specifies which plot contains the marker map we're changing the symbol size for. (See Special Arguments, above.)
<name> -- The name of the set of markers you want to change.
<size> -- The desired marker symbol size.
-marker_map_color [plot=<name>] <name> <color>
Changes the symbol color of a set of markers.
[plot=<name>] -- Optional; specifies which plot contains the marker map we're changing the color for. (See Special Arguments, above.)
<name> -- The name of the set of markers you want to change.
<color> -- The desired marker symbol color.
-marker_map_symbol [plot=<name>] <name> <symbol>
Changes the type of symbol used for a set of markers.
[plot=<name>] -- Optional; specifies which plot contains the marker map we're changing the symbol for. (See Special Arguments, above.)
<name> -- The name of the set of markers you want to change.
<symbol> -- Name of the symbol type. (Be sure to put quotes around the name!)
<symbol> -- Name of the symbol type. (Be sure to put quotes around the name!)
Valid symbols: no symbol, caret down, caret left, caret right, caret up, circle, diamond, hexagon 1, hexagon 2, horizontal line, octagon, pentagon, pixel, plus, point, square, star, thin diamond, tick down, tick left, tick right, tick up, tripod down, tripod left, tripod right, tripod up, triangle down, triangle left, triangle right, triangle up, vertical line, x
Default is o.

## Annotation Creation and Styling Commands

These allow us to create annotations in a plot, with optional different styles.

Annotation styling commands (-ann_color, -ann_fontsize, -ann_metadata, and -ann_always_visible) are dependent on one of the corresponding annotation creation commands (-ann_threshold, -ann_peak, and -ann_valley), which they must follow. If you're creating multiple annotations, make sure that each styling command only follows its respective creation command and no other.

-ann_autolayout [plot=<name>]
Tells Kelviz to take all annotations currently in the plot(s) and lay them out automatically. Will not affect any annotations added via commands listed after this command!
[plot=<name>] -- Optional; specifies which plot we're having lay out annotations. Can change all plots simultaneously with plot=ALL. (See Special Arguments, above.)
-ann_threshold [plot=<name>] <type> <threshold>
Creates annotations based on a threshold value.
[plot=<name>] -- Optional; specifies which plot we're adding annotations to. Can change all plots simultaneously with plot=ALL. (See Special Arguments, above.)
<type> -- One of peak, valley, all_above, all_below, or peak_boundary.
peak annotates all peaks above the threshold.
valley annotates all valleys below the threshold.
all_above annotates all data points above the threshold.
all_below annotates all data points below the threshold.
peak_boundary annotates the boundaries of any peaks crossing the threshold.
<threshold> -- The threshold value. Real number values only.
-ann_threshold_lineset <lineset_id>
Specifies that annotations created by threshold (using -ann_threshold above) should be added only to the specified lineset ID.
Used only with -ann_threshold and otherwise ignored. Must come after the -ann_threshold it is intended to configure and no other.
<lineset_id> -- Text ID for the lineset we're restricting annotation creation to. (See Special Arguments, above.)
-ann_peak [plot=<name>] <xstart_chr> <xstart_pos> <xend_chr> <xend_pos>
Annotates the highest peak in a given region defined by two points along the X-axis.
[plot=<name>] -- Optional; specifies which plot we're adding annotations to. Can change all plots simultaneously with plot=ALL. (See Special Arguments, above.)
<xstart_chr> -- Name of the chromosome that the starting X position should appear along.
<xstart_pos> -- The starting X value, specified as a position along <xstart_chr>.
<xend_chr> -- Name of the chromosome that the ending X position should appear along.
<xend_pos> -- The ending X value, specified as a position along <xend_chr>.
-ann_valley [plot=<name>] <xstart_chr> <xstart_pos> <xend_chr> <xend_pos>
Annotates the lowest valley in a given region defined by two points along the X-axis.
[plot=<name>] -- Optional; specifies which plot we're adding annotations to. Can change all plots simultaneously with plot=ALL. (See Special Arguments, above.)
<xstart_chr> -- Name of the chromosome that the starting X position should appear along.
<xstart_pos> -- The starting X value, specified as a position along <xstart_chr>.
<xend_chr> -- Name of the chromosome that the ending X position should appear along.
<xend_pos> -- The ending X value, specified as a position along <xend_chr>.
-ann_color <color>
Changes the color of an annotation or the annotations being created.
This is an annotation styling command; it must follow one of the four annotation creation commands listed above.
<color> -- The desired color of the annotation or annotations.
-ann_fontsize <size>
Changes the font size of an annotation or the annotations being created.
This is an annotation styling command; it must follow one of the four annotation creation commands listed above.
<size> -- Font size, in points. Integer values only. Default is 12.
-ann_metadata <on/off>
Indicates whether or not we want the annotation or annotations being created to use any associated metadata in their text in place of their position information.
This is an annotation styling command; it must follow one of the four annotation creation commands listed above.
<on/off> -- Turn this option ON or OFF. Defaults to ON.
-ann_always_visible <on/off>
Indicates whether or not this annotation or these annotations should only appear when showing each given annotation's particular group and no other groups (i.e. in a chr collage, or having used -zoom_chr), or if they should remain always visible.
This is an annotation styling command; it must follow one of the four annotation creation commands listed above.
<on/off> -- Turn this option ON or OFF. Defaults to ON.

## Output Commands

These create rendered images of our plots.

All options that start with -collage_ are dependent on a corresponding -export_collage command, which they must follow. If you're creating multiple subplot collages, make sure that each set of -collage_ commands only follows its respective -export_collage and no other.

-export <filename>
Exports the figure we're working on to an image.
File format is determined by file extension in filename. Known working formats include .png, .tif, .eps, .svg, and .pdf. If no extension is provided, .png is assumed by default.
<filename> -- Desired filename for the image.
-export_collage [plot=<name>] <type> <filename>
Creates a collage of individual plots in tabular form and saves it as one file. Can be saved as an image (the default) or as a GRX.
Collages are created either by selecting a single parent plot and divvying it up into multiple subplots (by chromosome - chr type - or by lineset - lineset type), or by selecting existing plots within the figure. The resulting selection of plots is then rearranged into a tabular form and given an in-grid figure-wide legend.
[plot=<name>] -- Optional; specifies which plot we're creating a collage from. Needed for chr and lineset type collages. (See Special Arguments, above.)
<type> -- The type of subplots desired.
Valid types are chr (individual chromosomes), lineset (individual linesets), and plot (existing plots in the figure).
<filename> -- Desired filename for the collage. Can be an image file or a Kelviz GRX file; the format will be determined by the filename extension.
-collage_figure_size <width> <height>
Specifies the space that the collage should take up. Within that space, plots are laid out within a grid with a set number of columns (see -collage_columns, below) and as many rows as needed to fit all the subplots.
By default, a collage's total figure size is automatically determined by the size of each plot and is otherwise unconstrained. To control the size of plots as opposed to the size of the entire collage, see -collage_plot_size, below. (Note also that this command overrides -collage_plot_size!)
<width> -- Width of the collage, in inches.
<height> -- Height of the collage, in inches.
-collage_plot_size <width> <height>
Specifies the amount of space (including all axis labels and padding) that each individual plot in the collage should take up. chr and lineset collages, by default, will attempt to calculate a plot size based on the amount of space the original source plot being split up into subplots took up. plot collages will calculate a plot size based on the original figure size.
This option can be overridden by -collage_figure_size; see above!
<width> -- Width of each plot, in inches.
<height> -- Height of each plot, in inches.
-collage_columns <columns>
Specifies the number of columns desired for the tabular layout of the collage we're creating.
By default, Kelviz takes the number of desired columns and adds rows until there's enough space for every plot.
<columns> -- The number of columns desired. Default is 2.
-collage_include <id1> <id2> ...
Specifies what subplots to include in the collage. By default Kelviz will include everything; use this option to restrict what is added to the collage.
<idX> -- Series of IDs to include in the collage.
For chr-type collages, this is specified by chromosome numbers ("1 2 3 5 8 13"). Ranges are also possible ("1-5 6 9-12").
For lineset-type collages, this is specified by lineset ID (see information on lineset IDs, above.)
For plot-type collages, this is specified by plot name ("a b d f").
-collage_legend_location <id> <loc>
For chr and lineset type collages, this indicates that we want a particular subplot (identified by ID) to have a non-default legend location. By default, every subplot uses the parent plot's legend location (specified by -legend_location, above).
Multiple subplots per collage can have their own legend locations; just specify this command once per subplot.
This command has no effect if you are generating a plot-type collage.
<id> -- The ID of the subplot for which we are specifying a legend location.
For chr-type collages, this is specified by chromosome numbers ("1 2 3 5 8 13").
For lineset-type collages, this is specified by lineset ID (see information on lineset IDs, above.)
<loc> -- The desired legend location. (Be sure to put quotes around the name!)
Valid locations: upper right, upper left, upper center, lower right, lower left, lower center, center left, center right, center.
Default is whatever is set by -legend_location; if that option has not been specified, the default is upper right.
Toggles whether or not we want one title for all subplots (the default) or if we want each subplot to have its own copy of the title.
<on/off> -- Turn this option ON or OFF. Defaults to ON.
-collage_autotitles <on/off>
For chr and lineset type collages, this toggles whether or not we want each plot to have automatic titles ("(a)", "(b)", "(c)", etc. - the default) or if they should have no titles at all.
<on/off> -- Turn this option ON or OFF. Defaults to ON.
-collage_title <id> <title>
For chr and lineset type collages, this indicates that we want a particular subplot (identified by ID) to have its own particular title. By default, subplots are given automatic titles; those have to be turned off for this option to be effective (see -collage_autotitles, immediately above).
<id> -- The ID of the subplot for which we are specifying a title.
For chr-type collages, this is specified by chromosome numbers ("1 2 3 5 8 13").
For lineset-type collages, this is specified by lineset ID (see information on lineset IDs, above.)
<title> -- Plot title. (Be sure to put quotes around it!)
-collage_ylimits <method>
For chr and lineset type collages, this specifies how the Y-axis limits should be determined for each subplot.
<method> -- One of home or current.
home means that default Y-axis limits will be used (as if the Home button had been pressed on the toolbar).
current uses the parent plot's current Y-axis limits.
-collage_custom_ylimits <id> <ymin> <ymax>
For chr and linesert type collages, this specifies custom Y-axis view limits for a specific subplot (identified by ID).
<id> -- The ID of the subplot for which we are specifying Y-axis view limits.
For chr-type collages, this is specified by chromosome numbers ("1 2 3 5 8 13").
For lineset-type collages, this is specified by lineset ID (see information on lineset IDs, above.)
<ymin> -- The minimum Y value. Real number values only.
<ymax> -- The maximum Y value. Real number values only.
-collage_separate_legend <on/off>
By default, a collage, once generated, is given a figure-wide legend using the in grid position option. Turn this option off to let each plot have its own legend.
<on/off> -- Turn this option ON or OFF. Defaults to ON.

## Deprecated Commands (Avoid Use)

Some commands or command formats continue to function for backwards compatibility. They have since been replaced, and may go away in future versions of Kelviz. They can be found in deprecated.md in the Kelviz documentation directory.

## Reference - Toolbar Buttons

Open GRX File
Opens an existing previously saved figure in Kelviz's GRX format.
Import Data From Text File
Opens a text file containing data to be plotted. (See Importing Data, above.)
Save GRX File
Save your work on the current figure. If it has not been previously saved, you will be prompted for a filename.
Export Figure To Image
Exports the currently shown figure to an image file (see Exporting Images Of Figures, above). You will be prompted for a filename. Available formats include PNG, TIFF, EPS, SVG, and PDF.
Inserts (or removes) black horizontal lines that run through an entire plot. You will be prompted for the y-value(s) of the line(s) to add, and will have the option to select existing such lines to remove. (See Horizontal Lines, above.)
Zoom To Chromosome
Select a plot and a chromosome with the drop-down boxes, and then click on the magnifying glass icon to only show that chromosome in that plot. (See Zooms and Views, above.)
Home View
Return to the "base view" - a view of all plots in which all data points plotted are visible. (See Zooms and Views, above.)
Previous View
Go back to the previous view (if any). (See Zooms and Views, above.)
Next View
Go to the next view (if any). (See Zooms and Views, above.)
Pan Mode
When turned on (by pressing this button once), you can drag the view inside plots around using the left mouse button. (See Zooms and Views, above.)
Zoom To Region Mode
When turned on (by pressing this button once), you can click and drag to select a free-form region within a plot to zoom in. Click this button again to turn this mode off. (See Zooms and Views, above.)
Zoom To X-Axis Limits Mode
When turned on (by pressing this button once), you can click and drag to select a horizontal region within a plot to zoom in to (along the X-axis). The Y-axis limits will be unchanged. Click this button again to turn this mode off. (See Zooms and Views, above.)
Zoom To Y-Axis Limits Mode
When turned on (by pressing this button once), you can click and drag to select a vertical region within a plot to zoom in to (along the Y-axis). The X-axis limits will be unchanged. Click this button again to turn this mode off. (See Zooms and Views, above.)
Annotate Point Mode
When turned on (by pressing this button once), you can click on or near data points within a plot to annotate them. Click this button again to turn this mode off. (See Creating New Annotations, above.)
Annotate Peak Mode
When turned on (by pressing this button once), you can click and drag to select a region within a plot containing a peak that you want annotated. Click this button again to turn this mode off. (See Creating New Annotations, above.)
Annotate Valley Mode
When turned on (by pressing this button once), you can click and drag to select a region within a plot containing a valley that you want annotated. Click this button again to turn this mode off. (See Creating New Annotations, above.)
Annotate Threshold
Creates annotations in the given plot or plots based on a threshold value. (See Creating New Annotations, above.)
Annotation Movement Mode
When turned on (by pressing this button once), you can click on any annotation and drag it to whereever you would like it to be positioned within its plot. Click this button again to turn this mode off. (See Modifying Existing Annotations, above.)
Automatically Layout Annotations
Analyzes the locations of all the annotations currently visible in the given plot or plots and attempts to place them optimally. WARNING: If you have a lot of annotations, this can take a very long time to complete.

• New Kelviz Window: Opens a new Kelviz window.
• Open GRX File: Opens an existing previously saved figure in Kelviz's GRX format.
• Import Data from File: Opens a text file containing data to be plotted so you can import it into your figure. (See Importing Data, above.)
• Import Plot From GRX File: Opens an existing figure in GRX format so you can import one of the plots from that figure into your existing plot. (See Importing Data, above.)
• Close Kelviz Window: Closes the current Kelviz window.
• Save GRX File: Saves your work on the current figure. If it has not been previously saved, you will be prompted for a filename.
• Save As GRX File: Same as 'Save GRX File', except you can choose a new filename.
• Export Figure to Color Image: Exports the currently shown figure to an image file (see Exporting Images Of Figures, above). You will be prompted for a filename. Available formats include PNG, TIFF, EPS, SVG, and PDF.
• Export Figure to Grayscale Image: Same as 'Export Figure to Color Image', except that the final image will be grayscale. (See Exporting Images Of Figures, above.)
• Create Collage Table From Figure: Takes a list of existing plots from the figure OR generates a series of subplots wherein only one chromosome or one line set is shown (depending on the collage type), then creates a new figure with those plots arranged in a tabular grid and saves that figure. (See Exporting Images Of Plots - Collages, above.)

• Clear Figure: Resets the figure and removes everything from it so that you may start working on a new or existing figure in place of the figure currently loaded. Make sure you save any changes to your existing figure before doing this!
• Copy Figure: Copies a picture of the current figure to the clipboard.
• Annotate Threshold: Creates annotations in the given plot or plots based on a threshold value. (See Creating New Annotations, above.)
• Automatically Layout Annotations: Analyzes the locations of all the annotations currently visible in the given plot or plots and attempts to place them optimally. WARNING: If you have a lot of annotations, this can take a very long time to complete.
• Remove All Annotations: Deletes all annotations in the figure. You will be prompted to confirm this action, as it cannot be undone. (See Modifying Existing Annotations, above.)
• Add Or Remove Horizontal Lines: Inserts (or removes) black horizontal lines that run through an entire plot. You will be prompted for the y-value(s) of the line(s) to add, and will have the option to select existing such lines to remove. (See Horizontal Lines, above.)
• Overlay Marker Map: Insert a map of markers. (See Marker Map Overlays, above.)