# coyote: CGWINDROSE

- coyote/Graphics
- [Source code]

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: <http://en.wikipedia.org/wiki/Wind_rose>`).
      Data to test the program (in SAMPSON formatted data files) can be freely downloaded from
      the `Meteorological Resource Center <http://www.webmet.com/>`.
      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 <http://www.idlcoyote.com/gallery/index.html#WINDROSE>`.
      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.