HelpSource/Reference/plot.schelp

   1 title:: plot
   2 summary:: Plot data in a graph
   3 categories:: Common methods, GUI
   4
   5
   6 section:: Description
   7 The link::Overviews/Methods#plot#plot method:: provides the ability to plot data in a GUI window. The method is implemented in the link::Classes/ArrayedCollection:: class but is also available for other classes for convenience, including link::Classes/Function::, link::Classes/Env::, link::Classes/Buffer::, link::Classes/SoundFile::, link::Classes/Wavetable::.
   8
   9 method:: plot (name, bounds, discrete, numChannels, minval, maxval, parent, labels)
  10 All arguments are optional
  11 argument:: name
  12 The name to be used as the GUI window title.
  13
  14 argument:: bounds
  15 A link::Classes/Rect:: providing coordinates for the GUI location.
  16
  17 argument:: discrete
  18 Plots are line-plots by default. Set this to code::true:: for bar charts.
  19
  20 argument:: numChannels
  21 The number of interleaved channels that an array represents. For Buffers this argument is not available, since it's filled in automatically.
  22
  23 argument:: minval
  24 Minimum value(s) for the display range. For a Buffer this defaults to code::-1:: but can be changed.
  25
  26 argument:: maxval
  27 Maximum value(s) for the display range. For a Buffer this defaults to code::+1:: but can be changed.
  28
  29 argument:: parent
  30 By default the plot is placed in a new GUI window. This argument can be used to specify an existing GUI container to send the plot to.
  31
  32 argument:: labels
  33 By default labels appear at the top left of the plot giving a data readout based on mouse position. Set this argument to code::false:: to prevent them appearing.
  34
  35 discussion::
  36 If code::minval:: and/or code::maxval:: are set to code::nil:: (this is default, except for link::Classes/Buffer::s), they will be automatically calculated from the dataset minimum and/or maximum. For multi-channel data, code::minval:: and code::maxval:: may be arrays, specifying the range independently for each channel (including use of code::nil::, in which case the min/max will be calculated for the specific channel rather than for the overall dataset).
  37
  38 Hitting the strong::L-key:: on the keyboard when the window is focussed toggles the lock, and the window can be used to edit the data.
  39
  40 section:: Examples
  41
  42 note:: See some of the classes linked above for more examples ::
  43
  44 code::
  45 // Arrays
  46 [5, 6, 7, 6.5, 4.5, 3.5].plot("Some data")
  47 [5, 6, 7, 6.5, 4.5, 3.5].plot("Some data, in stereo", numChannels:2)
  48 [5, 6, 7, 6.5, 4.5, 3.5].plot("Some data, in stereo", numChannels:2, discrete: true)
  49
  50 { |i| { |j| j + 1 * i % 6 }.dup(5) }.dup(200).plot("Some 2-d data");
  51
  52 // 3-channel interlaced data
  53 b = [{1.0.rand}.dup(50), { 20.0.rand - 30 }.dup(50),{ 10.0.rand }.dup(50)].lace(150);
  54 b.plot(numChannels:3, minval: nil, maxval: nil); // Common rescaling
  55 b.plot(numChannels:3, minval: [nil, nil, nil], maxval: [nil, nil, nil]); // Separate rescaling
  56
  57 // Envelopes
  58 Env.adsr(0.4, 0.4, 0.8, 0.9).plot
  59
  60 // Buffers
  61 s.boot;
  62 b = Buffer.read(s, Help.dir +/+ "sounds/a11wlk01.wav");
  63 b.plot; // +-1 range
  64 b.plot(minval: nil, maxval: nil); // auto range
  65 b.plot(minval: 0, maxval: nil); // semi-auto range
  66 ::