Plotting

The plot command allows you to generate 2D and 1D histograms from your trace data. This is useful for visualizing the overall distribution of your dataset or inspecting specific clusters after running a clustering algorithm.

Usage

Simplified Plotting

To quickly generate a 2D histogram of all traces in the current directory:

icluto plot <traces_file> [--svg]
  • <traces_file>: Path to your input trace file (e.g., .npy, .bin).
  • --svg: [Optional] Save the plot as an SVG instead of PNG.

This will generate a plot named <traces_file_name>_2dhist.png in the current directory.

Example:

icluto plot data/traces.npy

This will generate traces_2dhist.png in your current working directory.

Basic Plotting (Custom Output Directory)

To plot the histograms for an entire dataset and specify the output directory:

icluto plot <traces_file> <output_dir>
  • <traces_file>: Path to your input trace file.
  • <output_dir>: Directory where the plot will be saved.

Example:

icluto plot traces.npy ./plots

This will generate dataset.png inside the ./plots directory.

Plotting with Clusters

If you have already clustered your data and have a labels file (a NumPy array matching the length of your traces), you can plot histograms for each cluster individually:

icluto plot <traces_file> <labels_file> <output_dir>
  • <traces_file>: Path to your input trace file.
  • <labels_file>: Path to the .npy file containing cluster labels.
  • <output_dir>: Directory where the plots will be saved.

Configuration

You can configure the plot sizes, histogram bins, and output formats in the plots section of your YAML configuration file:

plots:
  size x: 9 # in inches
  size y: 9 # in inches
  formats: ["png", "svg"] # List of formats to save plots in (e.g., png, svg, pdf, jpg)
  histograms:
    number of bins x: 30
    number of bins y: 30
  • size x, size y: Dimensions of the generated plots in inches.
  • formats: A list of file extensions (without the dot). If multiple formats are specified, iCluto will save the same plot in each format.
  • histograms: Configure the number of bins for the 2D and 1D histograms.

Output

  • dataset.png: Generated when no labels are provided. Shows the 2D and 1D histograms for all traces.
  • cluster_{label}.png: Generated when labels are provided. Shows the histograms for the specific subset of traces belonging to cluster {label}.