coyote: CGWINDROSE

Description
This program draws a wind rose diagram. A wind rose diagram shows the frequency, speed, and 
direction of winds over some defined period of time. It is widely used in meteorological
applications (`see here: `).
Data to test the program (in SAMPSON formatted data files) can be freely downloaded from
the `Meteorological Resource Center `.
Changes made to the program in Oct 2014 allow multiple windrose plots to be placed in
a graphics window, but with a few reservations. Windrose plots normally have an aspect
ratio of 1 (i.e., they are square). Unfortunately, this cannot be guaranteed if you use
!P.Multi to create multiple plots. Therefore, it is recommened that you use cgLayout to
obtain a multi-plot layout for multiple windrose plots, and give each plot a specific
position in the graphics window with the `Position` keyword.
Categories
Graphics
Examples
An example of how to use the program can be found in the
`Coyote Plot Gallery `.
image:: cgwindrose.png
To display multiple plots in the window, set the positions with `cgLayout`, like this::
    pos = cgLayout([2,1], OXMargin=[5,5], OYMargin=[8, 5], XGap=10)
    cgDisplay, 900, 550
    cgWindRose, SamFile='93058_90.sam', Position=pos[*,0], Title='Plot 1', /NoLegend
    cgWindRose, SamFile='94018_90.sam', Position=pos[*,1], Title='Plot 2', LegendPosition=[0.44, 0.325], /NoErase
image:: cgwindrosetwo.png
Author
FANNING SOFTWARE CONSULTING::
   David W. Fanning
   1645 Sheely Drive
   Fort Collins, CO 80526 USA
   Phone: 970-221-0438
   E-mail: david@idlcoyote.com
   Coyote's Guide to IDL Programming: http://www.idlcoyote.com
History
Change History::
   Written, 7 March 2013 by David W. Fanning.
   Fixed error in which I was assuming some calm winds. 23 May 2013. DWF.
   Added LegendPosition, Position, CircleLabelSize, and NoLegend keywords and made changes 
       that allow multiple windrose plots to be place in a graphics window. To better 
       accommodate multiple plots, the cardinal directions are now indicated with a 
       single letter and the default circle label font size is reduced. 22 Oct 2014. DWF.
   Fixed a couple of hardcoded number problems when using your own speed and direction vectors. 20 June 2015. DWF.
   Added an OUTPUT keyword so that the windrose output can be sent directly to an output file. 1 July 2016. DWF.
Copyright
Copyright (c) 2013-2016, Fanning Software Consulting, Inc.
 function returns 100 x and y points as a 2x100 array that forms an arc between two angles
 plotted. The arc is created as if the 0 angle was to the North (top on drawings).
Params
speed: in, required, type=float
   The wind speed array. Note that missing values should be removed prior to passing the
   speed array to the program. This vector should have the same number of elements as the
   `direction` array. It is assumed there are no negative speed values in the array. Winds
   assumed to be measured in meters/second.
direction: in, required, type=float
   The direction of the wind. This should have the same number of elements as the `speed` array.
   The wind directions are assumed to be in the range 0 to 360.
Keywords
calmsfreq: out, optional, type=float
   The frequency of calms measurements in the data. (Winds less than 1 meter/second.)
circlelabelsize: in, optional, type=float, default=0.6
   A multiplier of the default character size, used for labelling the circle percents.
legendposition: in, optional, type=float
   A two-element array giving the X and Y position of the top-left corner of the legend box
   in normalized coordinates. By default, to the southwest of the windrose plot. Depending on
   window size, etc., the legend may not be visible or may be only partially visible. Adjust
   either the size of the window or the location of the legend for improved visibility.
nolegend: in, optional, type=boolean, default=0
   Set this keyword to prevent the windrose legend from being drawn with the windrose plot.;         
utput: in, optional, type=string, default=""
  Set this keyword to the type of output desired. Possible values are these::
      'PS'   - PostScript file
      'EPS'  - Encapsulated PostScript file
      'PDF'  - PDF file
      'BMP'  - BMP raster file
      'GIF'  - GIF raster file
      'JPEG' - JPEG raster file
      'PNG'  - PNG raster file
      'TIFF' - TIFF raster file
  Or, you can simply set this keyword to the name of the output file, and the type of
  file desired will be determined by the file extension. If you use this option, the
  user will not be prompted to supply the name of the output file.
  All raster file output is created through PostScript intermediate files (the
  PostScript files will be deleted), so ImageMagick and Ghostview MUST be installed
  to produce anything other than PostScript output. (See cgPS2PDF and cgPS_Close for
  details.) And also note that you should NOT use this keyword when doing multiple
  plots. The keyword is to be used as a convenient way to get PostScript or raster
  output for a single graphics command. Output parameters can be set with cgWindow_SetDefs.
position: in, optional, type=float
   The usual four-element POSITION keyword giving the plot position of the windrose plot in
   normalized coordinates.
samfile: in, optional, type=string
   The path to a SAMSON (*.sam) format meteorological data file from which wind speed and wind
   direction can be obtained.
speedbinsize:, in, optional, type=float, default=3
   The size of the bin when the speed is binned with the Histogram command.
title: in, optional, type=string, default=""
   The plot title. Not displayed if a null string.