gd_graph.h File Reference

C library for generating 2D plots and histograms. More...

#include <stdio.h>
#include <gd.h>

Include dependency graph for gd_graph.h:

Go to the source code of this file.

Defines
#define	NUM_COLORS   8
#define	gdgGetGD(gdg)   gdg->im
Typedefs
typedef enum gdgBar	gdgBarType
Enumerations
enum	gdgMarker {   FILLED_SQUARE, OPEN_SQUARE, POINT, HORIZONTAL_CROSS,   DIAGONAL_CROSS, OPEN_TRIANGLE, FILLED_TRIANGLE, OPEN_UTRIANGLE,   FILLED_UTRIANGLE, FILLED_CIRCLE, OPEN_CIRCLE, AUTO_MARKER }
enum	gdgBar { FILLED, OPEN, OUTLINE }
Functions
gdgImagePtr	gdgCreatePlot (int width, int height)
	allocate memory needed for plotting
void	gdgImageDestroy (gdgImagePtr gdg)
	free all memory associated with the plot
void	gdgSetColorMap (int map)
void	gdgSetLegend (gdgImagePtr gdg, char **legends)
void	gdgSetYLabel (gdgImagePtr gdg, char *ylabel)
void	gdgSetXLabel (gdgImagePtr gdg, char *xlabel)
void	gdgSetTitle (gdgImagePtr gdg, char *title)
void	gdgSetMarker (gdgImagePtr gdg, gdgMarkerType marker)
void	gdgSetBar (gdgImagePtr gdg, gdgBarType bar)
void	gdgSetMarkerSize (gdgImagePtr gdg, int size)
void	gdgSetUseLine (int val)
void	gdgSetNoSort (int val)
int	gdgGetColor (const gdgImagePtr gdg, const char *color)
void	gdgImage2DPlot (gdgImagePtr gdg, int numPoints, double *x, double *y, int markerColor, int lineColor)
void	gdgImageHist (gdgImagePtr gdg, int numPoints, double *x, int maxBreaks, int noYscale, int color)
void	gdgImageHeat (gdgImagePtr gdg, int numRows, int numCols, double **matrix, char **xlabels, char **ylabels, double squishWithin, int autoCenter)
void	gdgImagePng (gdgImagePtr gdg, FILE *out)
	writes the current plot as a png to out
void	gdgImageJpeg (gdgImagePtr gdg, FILE *out, int quality)
	writes the current plot as a jpeg to out

---

Detailed Description

C library for generating 2D plots and histograms.

The main functions in libwebplot are gdgImage2DPlot(), gdgImageHist(), gdgImageHeat(). After calling one of these functions, you can call gdgImagePng() to generate the image file. All of the other functions are for adding legends, axis, labels, and other plot customizations.

Note that png is the currently the only available image file type. jpeg support will be coming shortly.

---

Define Documentation

#define gdgGetGD (  gdg   )     gdg->im

get the gdImagePtr for creating custom colors or customizing the plot in anyway

#define NUM_COLORS   8

available markers for the points on a graph; some perform much better than others at various tasks

---

Typedef Documentation

typedef enum gdgBar gdgBarType

available formats for histogram bars

---

Enumeration Type Documentation

enum gdgBar

available formats for histogram bars Enumerator: FILLED  solid bar OPEN  open bar OUTLINE  can't remember

enum gdgMarker

Enumerator: FILLED_SQUARE  fast and clean OPEN_SQUARE  fast and clean POINT  extremely fast and clean, but very small; use only when there are many data points HORIZONTAL_CROSS  fast and clean DIAGONAL_CROSS  fast and moderately clean OPEN_TRIANGLE  moderately clean and moderately fast FILLED_TRIANGLE  moderately clean and moderately fast OPEN_UTRIANGLE  moderately clean and moderately fast FILLED_UTRIANGLE  moderately clean and moderately fast FILLED_CIRCLE  very slow and sloppy OPEN_CIRCLE  slow and sloppy AUTO_MARKER  marker choosen automatically

---

Function Documentation

int gdgGetColor (  const gdgImagePtr  gdg, const char *  color )

provides a way to retrieve built-in colors (eg gdgGetColor("red") will return the integer for red); available colors are: red, blue, green, magenta, cyan, chartreuse, yellow, chocolate, orange, gray, lightGray The built in functions are case sensitive.

void gdgImage2DPlot (  gdgImagePtr  gdg, int  numPoints, double *  x, double *  y, int  markerColor, int  lineColor )

plots x vs y; if markerColor < 0 or lineColor < 0, the color is chosen automatically. You can call this many times be for you call gdgImagePng() or gdgImageJpeg() and all of the data you submit will be plotted in the reverse order that you submitted it.

void gdgImageHeat (  gdgImagePtr  gdg, int  numRows, int  numCols, double **  matrix, char **  xlabels, char **  ylabels, double  squishWithin, int  autoCenter )

creates a heat plot of matrix; maximum number of unique colors is 256. There are currently three colormaps; a microarray style green to red, a more color blind friendly blue to red, and a grayScale. The color map is set with gdgSetColorMap(). If xlabels or ylabels are provided they MUST equal to numCols and numRows respectively. Note that extremely long names can drastically reduce the amount of space available to create the heat plot, and your plot size choice should take this into consideration. Heat plots can look poor due to outliers that make the non-outliers look like the same value. squishWithin forces a maximum and minimum number of standard deviations from the mean on the values in matrix. For example, squishWithin = 2 truncates all numbers to be within two standard deviations from the mean. NOTE that this permanently modifies matrix, so make a copy if that is undesired. If squishWithin is <= 0.0 it has no effect. autocenter attempts to center the data range around 0 (useful for array data normalized by some control). 0 = don't center, 1 = center using smallest value, 2 = center using largest value. Autocentering will not occur if either the minimum or the maximum is less than 1/2 a standard deviation away from the mean. This prevents ackward scaling of unnormalized data

void gdgImageHist (  gdgImagePtr  gdg, int  numPoints, double *  x, int  maxBreaks, int  noYscale, int  color )

plots a histogram of x using maxBreaks divisions of the data; if noYscale is true, it forces the minimum point on the Y axis to be 0, otherwise the y-axis is scaled to maximally show the differences amongst the histogram bins; color is the color used in drawing the bar (you either need to create a color using gdgGetGD() and the color creation functions in gd or retrieve one of the default colors from gdgGetColor() )

void gdgImageJpeg (  gdgImagePtr  gdg, FILE *  out, int  quality )

writes the current plot as a jpeg to out This function is currently not working, but will be fixed soon.

void gdgSetBar (  gdgImagePtr  gdg, gdgBarType  bar )

set the histogram bar to a new type (default is OPEN)

void gdgSetColorMap (  int  map  )

sets the color map used for a heat map. 1 = red-white-blue, 2 = red-black-green, 3 = grayScale

void gdgSetLegend (  gdgImagePtr  gdg, char **  legends )

used for scatterplots if you want a legend at the bottom of the plot. Particularly useful when you are plotting multiple things on the same plot. legends must be the same size as the number of plots you've made. The programmer is reponsible for freeing legends, and a local copy is NOT made (so don't free this before you call gdgImagePng() )

void gdgSetMarker (  gdgImagePtr  gdg, gdgMarkerType  marker )

set the marker to a new type (default is FILLED_SQUARE)

void gdgSetMarkerSize (  gdgImagePtr  gdg, int  size )

size of marker in pixels; note this function has no effect on marker type POINT, which is only 1 pixel in size

void gdgSetNoSort (  int  val  )

don't sort the data. only used when drawing line plots. This will cause the line connecting data points to be drawn in the order the data points are in the original array passed to gdg2DImagePlot() (this is not usually what you want, unless you have sorted the data yourself)

void gdgSetTitle (  gdgImagePtr  gdg, char *  title )

set graph title

void gdgSetUseLine (  int  val  )

set true if you want the graph to draw a line connecting your points. If you don't want a visible marker, call gdgSetMarker(gdg, POINT)

void gdgSetXLabel (  gdgImagePtr  gdg, char *  xlabel )

set label for the x axis

void gdgSetYLabel (  gdgImagePtr  gdg, char *  ylabel )

set label for the y axis

---