Class: Gruff::Scatter

Inherits:
Base
  • Object
show all
Defined in:
lib/gruff/scatter.rb

Overview

Here's how to set up an XY Scatter Chart

g = Gruff::Scatter.new(800) g.data(:apples, [1,2,3,4], [4,3,2,1]) g.data('oranges', [5,7,8], [4,1,7]) g.write('test/output/scatter.png')

Constant Summary

Constants inherited from Base

Base::DATA_COLOR_INDEX, Base::DATA_LABEL_INDEX, Base::DATA_VALUES_INDEX, Base::DATA_VALUES_X_INDEX, Base::DEBUG, Base::DEFAULT_MARGIN, Base::DEFAULT_TARGET_WIDTH, Base::LABEL_MARGIN, Base::LEGEND_MARGIN, Base::THOUSAND_SEPARATOR

Instance Attribute Summary collapse

Attributes inherited from Base

#additional_line_values, #bold_title, #bottom_margin, #center_labels_over_point, #colors, #font, #font_color, #has_left_labels, #hide_legend, #hide_line_markers, #hide_line_numbers, #hide_title, #label_formatting, #label_max_size, #label_stagger_height, #label_truncation_style, #labels, #left_margin, #legend_at_bottom, #legend_box_size, #legend_font_size, #legend_margin, #marker_color, #marker_count, #marker_font_size, #marker_shadow_color, #maximum_value, #minimum_value, #no_data_message, #right_margin, #show_labels_for_bar_values, #sort, #sorted_drawing, #stacked, #title, #title_font, #title_font_size, #title_margin, #top_margin, #use_data_label, #x_axis_increment, #x_axis_label, #y_axis_increment, #y_axis_label

Instance Method Summary collapse

Methods inherited from Base

#add_color, #initialize_ivars, #margins=, #replace_colors, #theme=, #theme_37signals, #theme_greyscale, #theme_keynote, #theme_odeo, #theme_pastel, #theme_rails_keynote, #to_blob, #write

Methods included from Deprecated

#graph_height, #graph_left, #graph_top, #graph_width, #scale_measurements, #total_height

Constructor Details

#initializeScatter

Gruff::Scatter takes the same parameters as the Gruff::Line graph

Example

g = Gruff::Scatter.new


62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
# File 'lib/gruff/scatter.rb', line 62

def initialize(*)
  super

  @baseline_x_color = @baseline_y_color = 'red'
  @baseline_x_value = @baseline_y_value = nil
  @circle_radius = nil
  @disable_significant_rounding_x_axis = false
  @enable_vertical_line_markers = false
  @marker_x_count = nil
  @maximum_x_value = @minimum_x_value = nil
  @stroke_width = nil
  @use_vertical_x_labels = false
  @x_axis_label_format = nil
  @x_label_margin = nil
  @y_axis_label_format = nil
end

Instance Attribute Details

#circle_radiusObject

Attributes to allow customising the size of the points


37
38
39
# File 'lib/gruff/scatter.rb', line 37

def circle_radius
  @circle_radius
end

#disable_significant_rounding_x_axisObject

Allow disabling the significant rounding when labeling the X axis This is useful when working with a small range of high values (for example, a date range of months, while seconds as units)


42
43
44
# File 'lib/gruff/scatter.rb', line 42

def disable_significant_rounding_x_axis
  @disable_significant_rounding_x_axis
end

#enable_vertical_line_markersObject

Allow enabling vertical lines. When you have a lot of data, they can work great


45
46
47
# File 'lib/gruff/scatter.rb', line 45

def enable_vertical_line_markers
  @enable_vertical_line_markers
end

#marker_x_countObject

The number of vertical lines shown for reference


22
23
24
# File 'lib/gruff/scatter.rb', line 22

def marker_x_count
  @marker_x_count
end

#maximum_x_valueObject

Maximum X Value. The value will get overwritten by the max in the datasets.


15
16
17
# File 'lib/gruff/scatter.rb', line 15

def maximum_x_value
  @maximum_x_value
end

#minimum_x_valueObject

Minimum X Value. The value will get overwritten by the min in the datasets.


19
20
21
# File 'lib/gruff/scatter.rb', line 19

def minimum_x_value
  @minimum_x_value
end

#stroke_widthObject

Returns the value of attribute stroke_width


38
39
40
# File 'lib/gruff/scatter.rb', line 38

def stroke_width
  @stroke_width
end

#use_vertical_x_labelsObject

Returns the value of attribute use_vertical_x_labels


49
50
51
# File 'lib/gruff/scatter.rb', line 49

def use_vertical_x_labels
  @use_vertical_x_labels
end

#x_axis_label_formatObject

Returns the value of attribute x_axis_label_format


53
54
55
# File 'lib/gruff/scatter.rb', line 53

def x_axis_label_format
  @x_axis_label_format
end

#x_label_marginObject

Allow using vertical labels in the X axis (and setting the label margin)


48
49
50
# File 'lib/gruff/scatter.rb', line 48

def x_label_margin
  @x_label_margin
end

#y_axis_label_formatObject

Allow passing lambdas to format labels


52
53
54
# File 'lib/gruff/scatter.rb', line 52

def y_axis_label_format
  @y_axis_label_format
end

Instance Method Details

#data(name, x_data_points = [], y_data_points = [], color = nil) ⇒ Object

The first parameter is the name of the dataset. The next two are the x and y axis data points contain in their own array in that respective order. The final parameter is the color.

Can be called multiple times with different datasets for a multi-valued graph.

If the color argument is nil, the next color from the default theme will be used.

NOTE: If you want to use a preset theme, you must set it before calling data().

Parameters

name

String or Symbol containing the name of the dataset.

x_data_points

An Array of of x-axis data points.

y_data_points

An Array of of y-axis data points.

color

The hex string for the color of the dataset. Defaults to nil.

Exceptions

Data points contain nil values

This error will get raised if either the x or y axis data points array contains a nil value. The graph will not make an assumption as how to graph nil

x_data_points is empty

This error is raised when the array for the x-axis points are empty

y_data_points is empty

This error is raised when the array for the y-axis points are empty

x_data_points.length != y_data_points.length

Error means that the x and y axis point arrays do not match in length

Examples

g = Gruff::Scatter.new g.data(:apples, [1,2,3], [3,2,1]) g.data('oranges', [1,1,1], [2,3,4]) g.data('bitter_melon', [3,5,6], [6,7,8], '#000000')

Raises:

  • (ArgumentError)

171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
# File 'lib/gruff/scatter.rb', line 171

def data(name, x_data_points=[], y_data_points=[], color=nil)
  
  raise ArgumentError, 'Data Points contain nil Value!' if x_data_points.include?(nil) || y_data_points.include?(nil)
  raise ArgumentError, 'x_data_points is empty!' if x_data_points.empty?
  raise ArgumentError, 'y_data_points is empty!' if y_data_points.empty?
  raise ArgumentError, 'x_data_points.length != y_data_points.length!' if x_data_points.length != y_data_points.length
  
  # Call the existing data routine for the y axis data
  super(name, y_data_points, color)
  
  #append the x data to the last entry that was just added in the @data member
  last_elem = @data.length()-1
  @data[last_elem] << x_data_points
  
  if @maximum_x_value.nil? && @minimum_x_value.nil?
    @maximum_x_value = @minimum_x_value = x_data_points.first
  end
  
  @maximum_x_value = x_data_points.max > @maximum_x_value ?
                      x_data_points.max : @maximum_x_value
  @minimum_x_value = x_data_points.min < @minimum_x_value ?
                      x_data_points.min : @minimum_x_value
end

#drawObject


90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
# File 'lib/gruff/scatter.rb', line 90

def draw
  super
  return unless @has_data

  # Check to see if more than one datapoint was given. NaN can result otherwise.  
  @x_increment = (@column_count > 1) ? (@graph_width / (@column_count - 1).to_f) : @graph_width

  #~ if (defined?(@norm_y_baseline)) then
    #~ level = @graph_top + (@graph_height - @norm_baseline * @graph_height)
    #~ @d = @d.push
    #~ @d.stroke_color @baseline_color
    #~ @d.fill_opacity 0.0
    #~ @d.stroke_dasharray(10, 20)
    #~ @d.stroke_width 5
    #~ @d.line(@graph_left, level, @graph_left + @graph_width, level)
    #~ @d = @d.pop
  #~ end

  #~ if (defined?(@norm_x_baseline)) then
    
  #~ end

  @norm_data.each do |data_row|      
    data_row[DATA_VALUES_INDEX].each_with_index do |data_point, index|
      x_value = data_row[DATA_VALUES_X_INDEX][index]
      next if data_point.nil? || x_value.nil? 

      new_x = get_x_coord(x_value, @graph_width, @graph_left)
      new_y = @graph_top + (@graph_height - data_point * @graph_height)

      # Reset each time to avoid thin-line errors
      @d = @d.stroke data_row[DATA_COLOR_INDEX]
      @d = @d.fill data_row[DATA_COLOR_INDEX]
      @d = @d.stroke_opacity 1.0
      @d = @d.stroke_width @stroke_width || clip_value_if_greater_than(@columns / (@norm_data.first[1].size * 4), 5.0)

      circle_radius = @circle_radius || clip_value_if_greater_than(@columns / (@norm_data.first[1].size * 2.5), 5.0)
      @d = @d.circle(new_x, new_y, new_x - circle_radius, new_y)
    end
  end

  @d.draw(@base_image)
end

#setup_drawingObject


79
80
81
82
83
84
85
86
87
88
# File 'lib/gruff/scatter.rb', line 79

def setup_drawing
  # TODO Need to get x-axis labels working. Current behavior will be to not allow.
  @labels = {}

  super

  # Translate our values so that we can use the base methods for drawing
  # the standard chart stuff
  @column_count = @x_spread
end