6.20. Handling Graphical Output

6.20.1. Introduction

EMBOSS can produce two types of graphics output. First are the 'drawn' graphics. They allow a user to draw in a graphics window using primitives for (e.g.) line and dot plotting. The other, more commonly used, graphic is the 'graph' plot. Several functions are provided to take the sting out of displaying graphs, for example the automatic drawing of axes and the ability to set titles for them. The graphics are currently produced using wrapper functions to PLplot. At the time development of EMBOSS began, PLplot was the only multi-platform C graphics library available with the LGPL licence.

Graph objects are created through ACD datatypes. The library calls provide an interface to the PLplot library which manages output to the screen or to files. PLplot defines a graphics viewport to work within. The viewport dimensions depend on the definitions in the PLplot drivers for each device and are not identical in size or proportion. Where the application needs to manipulate the scale of objects (for example EMBOSS application cirdna) we recommend working in units of millimetres (or 4 pixels) rather than arbitrary units which fail to scale when used on a different device.

General features of the graphics output include:

  • Graphics functions can define colours, line styles, titles and axis labels and plot scaling factors.

  • The objects plotted can be lines, shapes or text.

  • Functions are available to calculate scaled character sizes, polar coordinates and distances between plot coordinates.

  • The most useful internal data is PLplot scaling information including current scaling factors and the plot dimensions in millimetres.

  • Where plot output is to a file, there are functions to control the directory and output file names.

  • The PLplot library has general settings that are independent of any single plot. For this reason we avoid using more than one active graph object in any EMBOSS application.

6.20.2. AJAX Library Files

AJAX library files for handling graphics are listed in the table (Table 6.34, “AJAX Library Files for Handling Graphics”). Library file documentation, including a complete description of datatypes and functions, is available at:

http://emboss.open-bio.org/rel/dev/libs/
Table 6.34. AJAX Library Files for Handling Graphics
Library File DocumentationDescription
ajgraphGeneral graph handling functions
ajgraphstructData structures for use with graphs
ajgraphxmlGraph XML file object and functions for manipulating it
ajhistHistograms.
ajcallGraphics package access
ajdomDocument Object Model library calls

ajgraph.h/cAll the basic functions you are likely to need for plotting and printing graphs. It also contains static data structures and functions for handling graphics at a low level.

ajgraphstruct.hObjects for handling graphs, including the basic graph object (AjPGraph) and the PLplot graph data object (AjPGraphdata).

ajhist.hDefines the histogram object AjPHist object for handling histograms, which includes the histogram data object (AjPHistdata) as a substructure. It contains basic functions for handling histograms (Section 6.20.17, “Histograms”).

ajcall.h/cContains a few functions to allow access to different graphics packages, should alternatives to PLplot be implemented in the future. They are not currently used or documented here and you should see the online library documentation for further information.

ajdom.h/cData structures and functions, and also static functions for handling a document object model which will be used for a future EMBOSS graphics library. It is under development and is not documented here. See the online library documentation for further information.

You are unlikely to need the static data structures and functions in the above files unless you plan to implement code to extend the core functionality of the library.

6.20.3. ACD Datatypes

There are two datatypes for handling graphics output:

graph

Graphical output of any general kind.

graphxy

Graphical output as a simple two dimensional (2D) XY plot with the sequence along the x-axis.

6.20.4. ACD Data Definition

A typical ACD definition for graphics output (graph datatype):

graph: graph 
[
    gxtitle: "Residue Position"
]

A typical ACD definition for graphics output (xygraph datatype):

xygraph: graph 
[
    gxtitle: "Residue Position"
]

6.20.4.1. Parameter Name

All data definitions for graphics output should have the standard parameter name graph. See Appendix A, ACD Syntax Reference.

6.20.4.2. Common Attributes

Attributes that are typically specified are summarised below. These include two datatype-specific attributes (Section A.5, “Datatype-specific Attributes”).

gtitle: Specifies the graph title for either type of graph. Many other graphical elements can be set using the attributes.

multiple: Specifies the number of multiple XY graphs in a single output for a graph ACD datatype.

6.20.5. Program Initialisation

In earlier releases of EMBOSS, any application that made graphics calls was required to first initialize the graphics library functions. The restructuring of the libraries in EMBOSS 6.2.0 makes development much easier. All applications now simply call embInit or embInitPV.

6.20.6. AJAX Datatypes

For handling graphical output defined in the ACD file use:

AjPGraph

Basic graphics object (for graph and graphxy ACD datatypes).

One further datatype is used for handling histogram graphics:

AjPHist

Histogram object

The basic datatypes above include as nested substructures the following AJAX datatypes:

AjPGraphobj

PLplot graph object (a substructure of AjPGraph).

AjPGraphdata

PLplot graph data object (a substructure of AjPGraph).

AjPHistdata

Histogram data object (a substructure of AjPHist).

You are unlikely to need the static functions unless you plan to extend the graphics library code.

6.20.7. ACD File Handling

Datatypes and functions for handling graphics output via the ACD file are shown below (Table 6.35, “Datatypes and Functions for Graphical Output”).

Table 6.35. Datatypes and Functions for Graphical Output
To write a graph graphTo write a graphxy graph
ACD datatypegraphgraphxy
AJAX datatypeAjPGraphAjPGraph
To retrieve from ACDajAcdGetGraphajAcdGetGraphxy

6.20.7.1. Output Graphics Retrieval

To retrieve an output graphics object an object pointer is declared and then initialised using the appropriate ajAcdGet* function.

6.20.7.1.1. graph
    AjPGraph graph=NULL;

    graph = ajAcdGetGraph("graph");
6.20.7.1.2. graphxy
    AjPGraph graph=NULL;

    graph = ajAcdGetGraphxy("graph");

6.20.7.2. Processing Command line Options and ACD Attributes

Currently there are no functions for this.

6.20.7.3. Memory and File Management

Your application code will call embInit or embInitPV to process the ACD file and command line. All values from the ACD file are read into memory and files are opened as necessary. You have a handle on the files and memory through the ajAcdGet* family of functions which return pointers to appropriate objects. It is your responsibility to call the graphics library to close any files and free up memory at the end of the program.

6.20.7.3.1. Closing Graphics Files

To close an output graphics file call ajGraphicsClose. It closes graphics output through the PLplot library, closing any output files and screen displays:

    AjPGraph graph=NULL;

    graph = ajAcdGetGraphxy("graph");

    /* Do something with graph */

    ajGraphicsClose();
6.20.7.3.2. Freeing Memory

You must call the default destructor function (see below) on any graphics objects returned by calls to ajAcdGetGraph or ajAcdGetGraphxy.

6.20.8. Graphics Object Memory Management

6.20.8.1. Default Object Construction

Graphics objects are typically loaded from ACD file processing via a call to ajAcdGetGraph or ajAcdGetGraphxy (see above). You should therefore never need to instantiate the graphics object (AjPGraph) manually. In the unlikely event you do, two constructor functions are provided. The default constructor and ajGraphxyNewI which specifies the number of graphs:

AjPGraph  ajGraphNew (void);
AjPGraph  ajGraphxyNewI (ajint numsets);

You may also need to create a graphics data object. Two constructors are provided, the default constructor and ajGraphdataNewI which specifies the number of data points:

AjPGraphdata  ajGraphdataNew (void);      
AjPGraphdata  ajGraphdataNewI (ajint numsets);

All constructors return the address of a new object. The pointers do not need to be initialised to NULL but it is good practice to do so:

    AjPGraph        graph   = NULL;
    AjPGraph        graphxy = NULL;
    AjPGraphdata    gdata1  = NULL;
    AjPGraphdata    gdata2  = NULL;

    graph   = ajGraphNew();
    graphxy = ajGraphxyNewI(2);
    gdata1  = ajGraphdataNew();
    gdata2  = ajGraphdataNew();

/* The objects are instantiated and ready for use */

6.20.8.2. Default Object Destruction

You must free the memory for an object before the pointer is re-used and also once your are finished with it. The default destructor functions are:

void  ajGraphxyDel (AjPGraph* pmult);
void  ajGraphdataDel(AjPGraphdata *thys);

They are used as follows:

    AjPGraph graph=NULL;

    graph = ajAcdGetGraphxy("graph");

    /* Do something with graph */

    ajGraphicsClose();
    ajGraphxyDel(&graph);

A further example:

    AjPGraph        graph   = NULL;
    AjPGraph        graphxy = NULL;
    AjPGraphdata    gdata1  = NULL;
    AjPGraphdata   gdata2  = NULL;

    graph   = ajGraphNew();
    graphxy = ajGraphxyNewI(2);
    gdata1  = ajGraphdataNew();
    gdata2  = ajGraphdataNew();

    /* Do something with the objects */
    ajGraphxyDel(&graph);
    ajGraphxyDel(&graphxy);
    ajGraphdataDel(&gdata1);
    ajGraphdataDel(&gdata2);

6.20.9. Graphics File Management

Functions for handling graphics output files have the prefix ajGraph. The file name and directory can be specified (usually through ACD attributes and command line qualifiers which call these functiosn). Files are created for PLplot output devices that do not write directly to the screen. The library also provides data file output which is used to bypass PLplot and directly pass graphics results to the Staden package:

ajGraphicsSetFilename /* Set name and extension of output file. */ 
ajGraphSetOutfileS    /* Set name of output file. */ 
ajGraphSetOutdirS     /* Set directory of output file. */ 
ajGraphIsData         /* Checks if the graph is creating a Staden data file. */
ajGraphxyDisplay      /* Displays an xy graph */

The following functions set the output file name. You will not normally need to call these as the file will have received a name during ACD file processing.

/* Set name and extension of output file. */
void  ajGraphicsSetFilename (const AjPGraph thys);           

/* Set name of output file.      */
void  ajGraphSetOutfileS (AjPGraph thys, const AjPStr txt); 

/* Set directory of output file. */
void  ajGraphSetOutdirS(AjPGraph thys, const AjPStr txt);

ajGraphxyDisplay is used to display the graph(s) in a graph object to the plotting device. It must be called once by any program with graphics output. The second argument (closeit) is ajTrue if the graphics output file is to be closed once displayed:

void  ajGraphxyDisplay (AjPGraph thys, AjBool closeit );

Finally, ajGraphIsData will return ajTrue if the graph is creating a data file:

AjBool  ajGraphIsData (const AjPGraph thys);

6.20.10. Initialisation Functions

There are various assignment function for initialising and updating graph objects:

ajGraphDataAdd        /* Add a graph. */
ajGraphDataAdd        /* Add another graph to a multiple graph. */
ajGraphDataReplace    /* Replace a graph. */
ajGraphDataReplaceI   /* Replace a graph with specified number. */
ajGraphInitSeq        /* Set default values for graph based on a sequence. */
ajGraphxyNewI         /* Create graph object to hold a number of graphs. */
ajGraphxySetRanges    /* Set the min. and max. of data points. */
ajGraphClear          /* Delete drawable objects associated with a graph */ 

ajGraphSetMulti is used to add multiple graphs to a graph object. The number of graphs (numsets) is specified:

void  ajGraphSetMulti (AjPGraph thys, ajint numsets);

ajGraphDataAdd is used to add a graph to a graph object. The graph data (held in a AjPGraphdata object) is passed and the function returns 1 on success (0 otherwise):

ajint  ajGraphDataAdd (AjPGraph thys, AjPGraphdata graphdata);

The function can be called multiple times to add any number of graphs. The graph data object is used by the graph and should not be deleted until you are finished with the graph itself:

    AjPGraph        graphs = NULL;
    AjPGraphdata    gdata  = NULL;

    graphs = ajAcdGetGraphxy("graphs");

    gdata  = ajGraphdataNew();

    /* Set up graph data */

    ajGraphDataAdd(graphs,gdata);

    /* Do something with the graph */

    ajGraphdataDel(&gdata);
    ajGraphxyDel(&graphs);

ajGraphDataReplace and ajGraphDataReplaceI are used to replace one graph in a graph object with another. The new graph data (held in a AjPGraphdata object) is passed and graph data object that is replaced is deleted. The function returns 1 on success (0 otherwise):

ajint  ajGraphDataReplace (AjPGraph thys, AjPGraphdata graphdata);
ajint  ajGraphDataReplaceI (AjPGraph thys, AjPGraphdata graphdata, ajint num);

ajGraphDataReplace replaces the first graph whereas ajGraphDataReplace replaces the numbered graph.

ajGraphInitSeq is used to define default values for a graph object based on a sequence that is passed:

void  ajGraphInitSeq (AjPGraph thys, const AjPSeq seq);

The title of the plot is set to the name of the sequence and the x-axis is set to the sequence size. It is used as follows:

int main(int argc, char **argv)
{
    AjPSeq   seq   = NULL;
    AjPGraph graph = NULL;

    embInit("isochore", argc, argv);
 
    seq   = ajAcdGetSeq("sequence");
    graph = ajAcdGetGraphxy("graph");

    ajGraphInitSeq(graph, seq);

Finally, ajGraphxySetRanges will calculate the minimum and maximum of the data points and store the values in the graph object:

void  ajGraphxySetRanges (AjPGraph thys);

To delete all the drawable objects connected to the graph object (to reuse it for a new graph page) call:

void  ajGraphClear (AjPGraph thys);

6.20.11. Creating Windows

The following functions are for managing windows for plotting graphs:

ajGraphOpenWin     /* Open a window. */
ajGraphOpenPlotset /* Open a window with a number of plots. */
ajGraphOpenMm      /* Open a window and return dimensions in mm */
ajGraphicsClose    /* Close a window. */
ajGraphClear       /* Clear screen or new page. */

A window is required for each graph (screen or page) to be plotted. Functions with the prefix ajGraphOpen will open a window for graph plotting:

void  ajGraphOpenWin (AjPGraph thys, float xmin, float xmax, float ymin, float ymax);
void  ajGraphOpenPlotset (AjPGraph thys, ajint numofsets);
void  ajGraphOpenMm (AjPGraph thys, float * xmm, float * ymm);

ajGraphOpenWin is typically used and should be called once for each graph, typically once per application. The window is defined by the supplied minimum and maximum x and y values. Alternatively, ajGraphOpenPlotset will open a window for a number of plots. ajGraphOpenMm opens a window and returns the physical size in millimetres which the application can then map to its own plot units. This is the safe way to work with scaling drawable objects as PLplot device page sizes are inconsistent.

ajGraphClear is used to clear the screen (for screen output) or to create a new page (for plotter/postscript output). It is passed a boolean argument which if ajTrue will cause the current pen colour character sizes, plot title and subtitle, etc to be reset for the next page.

void  ajGraphClear (AjPGraph thys, AjBool resetdefaults); 

Once you are done drawing to the window (see below), you must close it using ajGraphicsClose:

void  ajGraphicsClose (void)

6.20.12. Drawing Functions

Functions with the prefix ajGraphicsDraw are for drawing graphical elements to the plotter device. The functions are as follows:

ajGraphicsDrawposBox               /* Draw a box.                    */
ajGraphicsDrawposBoxFill           /* Draw a box and fill.           */
ajGraphicsDrawposDia               /* Draw a diamond.                */
ajGraphicsDrawposDiaFill           /* Draw a diamond and fill.       */
ajGraphicsDrawsetPoly              /* Draw a polygon.                */
ajGraphicsDrawsetPolyFill          /* Draw a polygon and fill.       */
ajGraphicsDrawposRect              /* Draw a rectangle.              */
ajGraphicsDrawposRectFill          /* Draw a rectangle and fill.     */
ajGraphicsDrawarcRect              /* Draw a rectangle along a curve.*/
ajGraphicsDrawarcRectFill          /* Draw a rectangle along a curve and fill. */
ajGraphicsDrawposTri               /* Draw a triangle.               */
ajGraphicsDrawposTriFill           /* Draw a triangle and fill.      */
ajGraphicsDrawposCircle            /* Draw a circle.                 */
ajGraphicsDrawsetDots              /* Draw a set of dots.            */
ajGraphicsDrawbarsHoriz            /* Draw horizontal error bars.    */
ajGraphicsDrawbarsVert             /* Draw vertical error bars.      */
ajGraphicsDrawposLine              /* Draw a line between 2 points.  */
ajGraphicsDrawsetLines             /* Draw a number of lines.        */
ajGraphicsDrawsetSymbols           /* Draw a set of dots.            */
ajGraphicsDrawposTextAtend         /* Draw text at end point.        */
ajGraphicsDrawposTextAtmid         /* Draw text at mid point.        */
ajGraphicsDrawposTextAtlineJusti fy/* Draw text along line.          */
ajGraphicsDrawposTextAtstart       /* Draw text at start point.      */
ajGraphicsDrawarcTextJustify       /* Draw text along a curve.       */
ajGraphicsDrawarcArc               /* Draw a portion of a circle (an arc). */

You should see the online documentation for an explanation of how to use these functions.

6.20.13. Setting Graphical Elements to Render

Functions with the prefix ajGraphicsSet are for setting graphical elements to be rendered when the graph is plotted. The ajGraphSetFlag function is used internally. Developers should prefer to call the individual ajGraphxyShow functions for each flag. The functions are as follows:

ajGraphicsSetBgcolourBlack /* Background colour to black.    */
ajGraphicsSetBgcolourWhite /* Background colour to white.    */
ajGraphicsSetFgcolour      /* Foreground colour to a colour. */
ajGraphicsSetLabelsC       /* Labels for the plot.           */
ajGraphicsSetRlabelC       /* Right Y-axis label.            */
ajGraphSetDescC            /* Graph description.             */
ajGraphicsSetLinestyle     /* Line style.                    */
ajGraphicsSetPortrait      /* Page orientation.              */
ajGraphicsSetPenwidth      /* Pen width.                     */
ajGraphxyShowPointsCircle  /* Draw points as circles.        */
ajGraphxyShowPointsJoin    /* Draw lines between the points. */
ajGraphSetFlag             /* Set PLplot flags to add or subtract.  */
ajGraphxySetRanges         /* Max. and min. of the data points for all graphs.        */
ajGraphxySetflagOverlay    /* Sets whether the graphs should lay on top of each other.*/
ajGraphSetSubtitleC        /* Subtitle.                                               */
ajGraphShowSubtitle        /* Set whether subtitle is displayed.              .       */
ajGraphSetTitleC           /* Title.                                                  */
ajGraphShowTitle           /* Set whether title is displayed.                         */
ajGraphxySetflagGaps       /* Set whether the graphs should enable gaps.              */
ajGraphicsSetDefcharsize   /* Default character size in mm.                           */
ajGraphicsSetCharscale     /* Character scale factor.                                 */
ajGraphicsSetFillpat       /* Fill pattern type.                                      */

Functions with the prefix ajGraphxySetX and prefix ajGraphxySetY are for setting graphical properties of the x or y-axis respectively. The functions are as follows:

ajGraphxyShowXaxis       /*   bottom x-axis. */
ajGraphxyShowUnum        /*   labels on the top x-axis. */
ajGraphxyShowXtick       /*   tick marks on the x-axis. */
ajGraphxyShowUaxis       /*   left X-axis at the top. */
ajGraphxySetXendF        /*   end position for x in the graph. */
ajGraphxyShowXgrid       /*   grid the tick marks on the x-axis. */ 
ajGraphxyShowXinvert     /*   tick marks inside the plot on the x-axis. */
ajGraphxyShowXlabel      /*   label the x-axis. */
ajGraphxySetXrangeII     /*   x-axis range with integers. */
ajGraphxySetXstartF      /*   start position for x in the graph. */
ajGraphxyShowYnum        /*   labels on the left hand axis. */
ajGraphSetXlabelC        /*   title for the x-axis for multiple plots on one graph. */
ajGraphxyShowYaxis       /*   left hand y-axis. */
ajGraphxyShowRaxis       /*   right hand y-axis. */
ajGraphxyShowYtick       /*   tick marks on the y-axis. */ 
ajGraphxySetYendF        /*   end position for y in the graph. */ 
ajGraphxyShowYgrid       /*   grid the tick marks on the y-axis. */ 
ajGraphxyShowYinvert     /*   tick marks inside the plot on the y-axis. */
ajGraphxyShowYlabel      /*   label the y-axis. */
ajGraphxySetYrangeII     /*   y-axis range with integers. */
ajGraphxySetYstartF      /*   start position for y in the graph. */
ajGraphSetYlabelC        /*   title for the y-axis for multiple plots on one graph. */

The functions above are used in conjunction with functions to add graphical elements to be rendered:

ajGraphAddLine   /* Adds a line. */
ajGraphAddRect   /* Adds a rectangle. */
ajGraphAddTextC  /* Adds text. */
ajGraphAddTextScaleC /* Adds text with scale factor */

A more limited set of functions is available for setting elements to be rendered in a graph data object:

ajGraphdataSetMinmax     /*   Min. and max. of data points for all graphs. */
ajGraphdataSetTruescale  /*   Scale min. and max. of the data points      .*/
ajGraphdataSetTypeC      /*   Type of the graph for data output.           */
ajGraphdataSetSubtitleC  /*   Subtitle  */                                      
ajGraphdataSetTitleC     /*   Title  */
ajGraphAppendTitleC      /*   Title from the description. */
ajGraphdataSetXlabelC    /*   x-axis title. */
ajGraphdataSetYlabelC    /*   y-axis title.  */
ajGraphdataSetColour     /*   Colour for the plot on one graph. */
ajGraphdataSetLinetype   /*   Line type for the plot on one graph. */

These are used in conjunction with functions to add graphical elements to be rendered:

ajGraphdataAddposLine    /* Adds a line. */
ajGraphdataAddposRect    /* Adds a rectangle. */
ajGraphdataAddposTextC   /* Adds text. */
ajGraphdataAddXY         /* Adds X,Y data points. */
ajGraphdataCalcXY        /* Adds X,Y data points from an increment. */

You should see the online documentation for an explanation of how to use these functions.

6.20.14. Retrieving Properties of Graphs

Functions for retrieving a property of a graph have the prefix ajGraphGet:

ajGraphGetSubtitleC         /* Graph subtitle. */
ajGraphGetTitleC            /* Graph title. */ 
ajGraphGetXlabelC           /* x-axis title */ 
ajGraphGetYlabelC           /* y-axis title */
ajGraphicsGetFgcolour       /* Current foreground colour. */
ajGraphicsBasecolourNewNuc  /* Base colours array for nucleotide sequence. */
ajGraphicsBasecolourNewProt /* Base colours array for protein sequence. */
ajGraphicsGetCharsize       /* Character size. */
ajGraphGetParamsPage        /* Output device parameters. */    

Functions that return the graph titles return the string object itself (not a copy) so you must be careful not to unintentionally change or delete it.

ajGraphicsGetFgcolour will return the current foreground colour as an integer:

ajint  ajGraphicsGetFgcolour (void);

ajGraphicsCheckColourC takes a string argument for a colour and returns an integer corresponding to that colour, or -1 if that colour was not found.

ajint  ajGraphicsCheckColourS (const AjPStr colour);
ajint*  ajGraphicsBasecolourNewNuc (const AjPStr codes);
ajint*  ajGraphicsBasecolourNewProt (const AjPStr codes); 

The code below picks up a colour, specified as a string by the user, from ACD file processing. ajGraphicsCheckColourC is called to get the integer for the colour, which is then passed to ajGraphicsSetFgcolour to set the foreground colour:

AjPStr colour  = NULL;
ajint  colouri;

colour   = ajAcdGetString("colour");

colouri = ajGraphicsCheckColourC(colour);
if(colouri == -1)
    colouri = GREY;

ajGraphicsSetFgcolour(colouri);

ajGraphicsGetCharsize retrieves the default and current character size. This is useful when setting the size of other graphical elements:

void  ajGraphicsGetCharsize (float *defheight, float *currentheight);

ajGraphicsGetParamsPage gets the output device parameters defined internally in PLplot. These are less useful than one might expect as some are hardcoded for each device driver, or simply copies of user values that are ignored in PLplot. Where the plot dimensions are needed, use ajGraphOpenMm and work in millimetre units.

6.20.15. Calculated Properties of Graphs

The following functions return some calculated value (in user coordinates) derived from a graph:

ajGraphicsCalcCoord        /* coordinates of a point on a circle knowing the angle. */
ajGraphicsCalcDistance     /* Distances between 2 points. */
ajGraphicsCalcTextlengthC  /* Text length. */
ajGraphicsCalcTextheight   /* Text height. */
ajGraphicsCalcCharsize     /* Text size (mm) to needed for given text length and height. */

You should see the online documentation for an explanation of how to use these functions.

6.20.16. Graph Debug Functions

Functions for debugging graph objects have the prefix ajGraphDebug. See the online documentation for further information.

6.20.17. Histograms

Histograms are a special case of graphics plotting. A dedicated set of functions are provided that handle the underlying graph objects and function calls so that you don't need to.

To plot a histogram you first must create a histogram object. Two constructors are provided and take the number of sets of data (numofsets), all of which must have the same number of data points (numofpoints) per set:

AjPHist  ajHistNew (ajint numofsets, ajint numofpoints);
AjPHist  ajHistNewG (ajint numofsets, ajint numofpoints, AjPGraph graph);

ajHistNewG will also assign a graph object (passed as an argument) to the histogram that is returned. A number (numofsets) of graphs are added to the graph object. The graph device and name and extension of output file are also set.

To set the titles for histogram with a single set use one of the functions below:

/* Title */
void  ajHistSetTitleC (AjPHist hist, const char* strng);        

/* x-axis label */
void  ajHistSetXlabelC (AjPHist hist, const char* strng);        

/* y-axis left label */
void  ajHistSetYlabelC (AjPHist hist,const  char* strng);    

/* y-axis right label */
void  ajHistSetRlabelC (AjPHist hist, const char* strng);

To set the titles for histogram with multiple sets use one of the functions below. index is the number of the histogram in the set to have its title set to title:

/* Title for histogram with multiple sets */
void  ajHistSetmultiTitleC (AjPHist hist, ajint index, const AjPStr title);     

/* x-axis title */
void  ajHistSetmultiXlabelC (AjPHist hist, ajint index, const AjPStr title);    

/* y-axis title */
void  ajHistSetmultiYlabelC (AjPHist hist, ajint index, const AjPStr title);

ajHistSetmultiColour and ajHistSetmultiPattern will set the colour or linestyle for the specified set (index):

/* Set colour for bars in histogram */ 
void  ajHistSetmultiColour(AjPHist hist, ajint index, ajint colour);   

/* Set linestyle for set of bars */
void  ajHistSetmultiPattern (AjPHist hist, ajint index, ajint style)   

ajHistSetMono is useful for printing in monochrome:

/* Set patterns instead of colours  */
void  ajHistSetMono (AjPHist hist, AjBool set);  

To display a histogram, call ajHistDisplay:

void  ajHistDisplay (const AjPHist hist);

Once you are done with the histogram, you must close the output file and delete the histogram object. The functions are:

void  ajHistogramClose (void);
void  ajHistDel (AjPHist* hist);

ajHistDataAdd and ajHistDataCopy are used to specify a set of data points for a specified histogram (index) in a set:

void  ajHistDataAdd (AjPHist hist, ajint index, PLFLT *data);
void  ajHistDataCopy (AjPHist hist, ajint index, const PLFLT *data);

ajHistDataAdd sets the histogram to point to the data passed whereas ajHistDataCopy copies the data.

The example below shows a function for copying a set of data held in an integer array (results) into a histogram (hist). ajHistDataCopy is used to copy the array of data which is why farray can be deleted. Had ajHistDataAdd been used instead then AJFREE would not have been called:

void func(AjPHist hist, const ajint * results, ajint npts, ajint hist_num)
{
    ajint i;

    float *farray;

    AJCNEW(farray, npts);
    for(i=0; i<npts; i++)
        farray[i] = (float) results[i];

    ajHistDataCopy(hist, hist_num, farray);
    AJFREE(farray);