Data Files

CSV (Default)

These files contain the data to be plotted. As well as the data, these files may contain parameters that modify the plot. It is important to note that any parameters in these files will always be applied if possible, unless they are overwritten by command line parameters. For the data file, all command line parameters are valid except file. The parameters in the header are formatted slightly differently to those in the command line. They always start with a #, followed by the key-value pair, which, unlike the command-line parameters, can include whitespaces. Multiple values are separated by ,.

For example, the start of the header could look like this:

# title : Test
# x_label : x
# y_label : y
# x_columns:1
# y_columns:2,3,4

The line following the header may contain column labels that will be used to create a legend within the plot. If this is not specified as legend_line:1, GRPlot will check if the first entry in the line is a number, and use this information to determine whether to create a legend. Another way to specify the column labels is to use a header entry such as #legend:<val>,<val>,<val>. Each entry is separated by ,, meaning that no value after or between two commas will skip the label for that specific column. Regardless of their position, spaces will not be ignored. If there is a header entry like the one in the previous example, GRPlot will always treat the first line as a data line, unless legend_line:1 is used. In this case, the previous labels will be replaced.

Every other line in the file includes data values, and blank lines can be ignored by setting ignore_blank_lines:1. Data items are separated by a tab character (\t). Depending on the plot type, the data is interpreted differently. The following list shows how data is treated for different plot types:

  • contour, contourf, heatmap, imshow, marginal_heatmap, surface, wireframe: The expected data is a matrix. Each element of the matrix is displayed according to its position within the matrix. These elements are interpreted as values in the x- and y-directions. When the use_bins parameter is set to 1, the first row and column of the data are interpreted as information about the x_range and y_range. The previously explained data format cannot handle non-linear x- or y-values. Another format is available for this, which allows the x-, y- and z-values to be defined. Each line contains a triplet of x-, y- and z-values separated by spaces. The x-values must change first. To activate this option, use the xyz_file parameter with the value 1.

  • line, scatter: One or more columns are expected here. Each column will be displayed in a single plot. Therefore, the values in the columns are interpreted as y-values. In combination with the error parameter, every second (and third) column is interpreted as an error value. A more detailed description of the error parameter can be found in the key-value pair section. Another option enables users to specify which columns should contain the x-, y- and error values. For this, the x_columns, y_columns and error_columns parameters can be used.

  • isosurface, volume: The expected data consists of multiple matrices, each separated by an empty line. Each matrix represents a slice inside the volume.

  • line3, scatter, scatter3, tricontour, trisurface: Three columns of data are expected, representing the x-, y- and z-values.

  • barplot, stem, stairs: One or more columns are expected. Each column will be displayed in a single plot. Therefore, the values in the columns are interpreted as y-values. In combination with the error parameter, the second (and third) column is interpreted as error values. A more detailed description of the error parameter can be found in the key-value pair section. Another option allows the user to define which columns include the x-, y- and error values. For this, the x_columns, y_columns, and error_columns parameters can be used.

  • pie: The expected data consists of 1–4 lines. The first line represents the data to be displayed. The next three rows are used to set the RGB values for the pie charts. Each row represents one RGB element.

  • polar_histogram: One column representing the values is expected.

  • polar_line, polar_scatter: The expected data are pairs of columns containing angles and values.

  • polar_heatmap: The expected data is a matrix. Each element of the matrix is displayed according to its position within the matrix. These elements are interpreted as values in the theta(x) and radial(y) directions. If not specified, theta will range from 0.0 to 360.0, while r(radial) will range from 0.0 to 3.0. Both parameters can be modified using theta_range for theta and r_range for r.

  • quiver: The expected data are two matrices. The first matrix contains information about the x-directions, and the second matrix contains information about the y-directions.

  • hexbin, shade: The expected data are two columns representing the x- and y-data.

  • histogram: One or more columns are expected. Each column will be displayed in a single plot. Therefore, the values inside the columns are interpreted as x-values. In combination with the error parameter, the second (and third) column is interpreted as error values. A more detailed description of the error parameter can be found in the key-value pair section. Another option allows the user to define which columns include the x-, y- (weights) and error values. For this, the x_columns, y_columns, and error_columns parameters can be used.

Plot types that expect the same data shape as other plot types can be converted using an interactive menu.

Following parameters can be useful for it:

columns, file, x_columns, xye_file, xyz_file, y_columns