Standard ellipses

Point distributions can be visualised directly by plotting them in your sketch. However, this approach does not work well for very large numbers of points, nor is it always a good way of demonstrating structure or trends in the point distribution. A visual summary of a set of points can be generated using a standard ellipse whose centre represents the mean centre of the point values and size represents the dispersion of those points around their centre. The long axis of the ellipse shows the direction of maximum dispersion and the short axis, the direction of minimum dispersion.

Using standard ellipses in Processing

The StandardEllipse class is one of a number of statistical graphics available in gicentreUtils. To use it you should import the class into your sketch with the line

import org.gicentre.utils.stat.StandardEllipse;

For full details of the methods available see the StandardEllipse API reference. See also, the StandardEllipseExample sketch supplied in the examples folder of the giCentre utilities library.

To create a standard ellipse object, a collection of point values must be provided to its constructor. Each point should be stored as a Processing PVector object. The x and y values of the PVector represent the point's 2d location.

For example,

ArrayList<PVector> points = new ArrayList<PVector>();
points.add(new PVector(100,100));
points.add(new PVector(250,100));
points.add(new PVector(130,190));
points.add(new PVector(230,20));

standardEllipse = new StandardEllipse(points);

To draw the ellipse, simply call the draw() method of the StandardEllipse object supplying the sketch in which the ellipse is to appear (usually this will be called inside your own draw() method supplying this as the sketch). The ellipse will be drawn using the sketch's current stroke and fill settings. For example, the following code draws and customises the appearance of an ellipse:

// Draw the ellipse.
strokeWeight(3);
stroke(183,128,128);
fill(183,128,128,50);
standardEllipse.draw(this);

// Draw the ellipse axes.
stroke(80,80,80,100);
strokeWeight(1);
standardEllipse.drawAxes(this);

Weighted ellipses

By default, all points are given equal weight when calculating the mean centre and major and minor axes of the ellipse. To give points different weights, the optional z value of the PVector objects should contain a positive value representing the point's weight. Additionally, the method setIsWeighted(true) should be called to turn on weighting when calculating the ellipse's dimensions and position.

The example below shows how both a weighted and unweighted ellipse can be created and drawn in a sketch:

import org.gicentre.utils.stat.StandardEllipse;

// Sketch to demonstrate the use of the StandardEllipse class. 
// Draws some random points then their weighted and unweighted
// standard ellipse.
// Version 1.5, 5th November, 2013.
// Author Jo Wood, giCentre.

ArrayList<PVector> points;
static final int NUM_POINTS = 150;
static final int HIGH_WEIGHT = 10;

// Creates a set of randomly placed points.
void setup()
{
  size(700,300);
  points = new ArrayList<PVector>();
  
  for (int i=0; i<NUM_POINTS; i++)
  {  
    if (random(1) < 0.5)
    {
      // Add a highly weighted point somewhere above-left.
      points.add(new PVector(width/6 + random(width/6),
                             height/3+random(-height/10,height/10),
                             HIGH_WEIGHT));
    }
    else
    {
      // Add unit weighted point to the central belt of the region.
      points.add(new PVector(width/2 + random(-width/3,width/3),
                             height/2+random(-height/6,height/6)));
    }
  }
}

// Draws points, randomly perturbs them and draws standard ellipse.
void draw()
{
  background(255);
  strokeWeight(4);
    
  // Plot original points and make them move about a bit.
  for (PVector p : points)
  {
    p.x += random(-2,2);
    p.y += random(-2,2);
    
    if (p.z == 0)
    {
      stroke(128,80,80);
    }
    else
    {
      stroke(183,80,80);
    }    
    point(p.x,p.y);
  }
  
  strokeWeight(1);
  
  // Calculate the standard ellipse of the points.
  StandardEllipse standardEllipse = new StandardEllipse(points);
  
  // Draw the unweighted version of the ellipse.
  stroke(128,128,183);
  fill(128,128,183,50);
  standardEllipse.draw(this);
  
  // Draw the ellipse axes.
  stroke(80,80,80,100);
  standardEllipse.drawAxes(this);
  
   // Draw the weighted version of the ellipse.
  standardEllipse.setIsWeighted(true);
  stroke(193,128,128);
  fill(183,128,128,50);
  standardEllipse.draw(this);
  
  // Draw the ellipse axes.
  stroke(80,80,80,100);
  standardEllipse.drawAxes(this);
}