Metadata-Version: 1.1
Name: windrose
Version: 1.6
Summary: Python Matplotlib, Numpy library to manage wind data, draw windrose (also known as a polar rose plot)
Home-page: https://github.com/scls19fr/windrose
Author: Sebastien Celles
Author-email: s.celles@gmail.com
License: CeCILL-B
Description: |Latest Version| |Supported Python versions| |Wheel format| |License|
        |Development Status| |Downloads monthly| |Code Health| |Build Status|
        
        windrose
        ========
        
        A windrose, also known as a polar rose plot, is a special diagram for
        representing the distribution of meteorological datas, typically wind
        speeds by class and direction. This is a simple module for the
        matplotlib python library, which requires numpy for internal
        computation.
        
        Original code forked from: - windrose 1.4 by `Lionel
        Roubeyrie <https://github.com/LionelR>`__ lionel.roubeyrie@gmail.com
        http://youarealegend.blogspot.fr/search/label/windrose
        
        Requirements:
        -------------
        
        -  matplotlib http://matplotlib.org/
        -  numpy http://www.numpy.org/
        -  and naturally python https://www.python.org/ :-P
        
        Option libraries:
        
        -  Pandas http://pandas.pydata.org/ (to feed plot functions easily)
        -  Scipy http://www.scipy.org/ (to fit data with Weibull distribution)
        -  ffmpeg https://www.ffmpeg.org/ (to output video)
        -  click http://click.pocoo.org/ (for command line interface tools)
        
        Notebook example :
        ------------------
        
        An `IPython (Jupyter) <http://ipython.org/>`__ notebook showing this
        package usage is available at:
        
        -  http://nbviewer.ipython.org/github/scls19fr/windrose/blob/master/windrose\_sample\_random.ipynb
        
        Script example :
        ----------------
        
        This example use randoms values for wind speed and direction(ws and wd
        variables). In situation, these variables are loaded with reals values
        (1-D array), from a database or directly from a text file (see the
        "load" facility from the matplotlib.pylab interface for that).
        
        ::
        
            from windrose import WindroseAxes
            from matplotlib import pyplot as plt
            import matplotlib.cm as cm
            import numpy as np
        
            #Create wind speed and direction variables
        
            ws = np.random.random(500) * 6
            wd = np.random.random(500) * 360
        
        A stacked histogram with normed (displayed in percent) results :
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
        
        ::
        
            ax = WindroseAxes.from_ax()
            ax.bar(wd, ws, normed=True, opening=0.8, edgecolor='white')
            ax.set_legend()
        
        .. figure:: screenshots/bar.png
           :alt: bar
        
           bar
        
        Another stacked histogram representation, not normed, with bins limits
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
        
        ::
        
            ax = WindroseAxes.from_ax()
            ax.box(wd, ws, bins=np.arange(0, 8, 1))
            ax.set_legend()
        
        .. figure:: screenshots/box.png
           :alt: box
        
           box
        
        A windrose in filled representation, with a controled colormap
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
        
        ::
        
            ax = WindroseAxes.from_ax()
            ax.contourf(wd, ws, bins=np.arange(0, 8, 1), cmap=cm.hot)
            ax.set_legend()
        
        .. figure:: screenshots/contourf.png
           :alt: contourf
        
           contourf
        
        Same as above, but with contours over each filled region...
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
        
        ::
        
            ax = WindroseAxes.from_ax()
            ax.contourf(wd, ws, bins=np.arange(0, 8, 1), cmap=cm.hot)
            ax.contour(wd, ws, bins=np.arange(0, 8, 1), colors='black')
            ax.set_legend()
        
        .. figure:: screenshots/contourf-contour.png
           :alt: contourf-contour
        
           contourf-contour
        
        ###...or without filled regions
        
        ::
        
            ax = WindroseAxes.from_ax()
            ax.contour(wd, ws, bins=np.arange(0, 8, 1), cmap=cm.hot, lw=3)
            ax.set_legend()
        
        .. figure:: screenshots/contour.png
           :alt: contour
        
           contour
        
        After that, you can have a look at the computed values used to plot the
        windrose with the ``ax._info`` dictionnary : - ``ax._info['bins']`` :
        list of bins (limits) used for wind speeds. If not set in the call, bins
        will be set to 6 parts between wind speed min and max. -
        ``ax._info['dir']`` : list of directions "bundaries" used to compute the
        distribution by wind direction sector. This can be set by the nsector
        parameter (see below). - ``ax._info['table']`` : the resulting table of
        the computation. It's a 2D histogram, where each line represents a wind
        speed class, and each column represents a wind direction class.
        
        So, to know the frequency of each wind direction, for all wind speeds,
        do:
        
        ::
        
            ax.bar(wd, ws, normed=True, nsector=16)
            table = ax._info['table']
            wd_freq = np.sum(table, axis=0)
        
        and to have a graphical representation of this result :
        
        ::
        
            direction = ax._info['dir']
            wd_freq = np.sum(table, axis=0)
            plt.bar(np.arange(16), wd_freq, align='center')
            xlabels = ('N','','N-E','','E','','S-E','','S','','S-O','','O','','N-O','')
            xticks=arange(16)
            gca().set_xticks(xticks)
            draw()
            gca().set_xticklabels(xlabels)
            draw()
        
        .. figure:: screenshots/histo_WD.png
           :alt: histo\_WD
        
           histo\_WD
        
        In addition of all the standard pyplot parameters, you can pass special
        parameters to control the windrose production. For the stacked histogram
        windrose, calling help(ax.bar) will give :
        ``bar(self, direction, var, **kwargs)`` method of
        ``windrose.WindroseAxes`` instance Plot a windrose in bar mode. For each
        var bins and for each sector, a colored bar will be draw on the axes.
        
        Mandatory: - ``direction`` : 1D array - directions the wind blows from,
        North centred - ``var`` : 1D array - values of the variable to compute.
        Typically the wind speeds
        
        Optional: - ``nsector`` : integer - number of sectors used to compute
        the windrose table. If not set, nsectors=16, then each sector will be
        360/16=22.5°, and the resulting computed table will be aligned with the
        cardinals points. - ``bins`` : 1D array or integer- number of bins, or a
        sequence of bins variable. If not set, bins=6 between min(var) and
        max(var). - ``blowto`` : bool. If True, the windrose will be pi rotated,
        to show where the wind blow to (usefull for pollutant rose). -
        ``colors`` : string or tuple - one string color (``'k'`` or
        ``'black'``), in this case all bins will be plotted in this color; a
        tuple of matplotlib color args (string, float, rgb, etc), different
        levels will be plotted in different colors in the order specified. -
        ``cmap`` : a cm Colormap instance from ``matplotlib.cm``. - if
        ``cmap == None`` and ``colors == None``, a default Colormap is used. -
        ``edgecolor`` : string - The string color each edge bar will be plotted.
        Default : no edgecolor - ``opening`` : float - between 0.0 and 1.0, to
        control the space between each sector (1.0 for no space)
        
        probability density function (pdf) and fitting Weibull distribution
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
        
        A probability density function can be plot using:
        
        ::
        
            from windrose import WindAxes
            ax = WindAxes.from_ax()
            bins = np.arange(0, 6 + 1, 0.5)
            bins = bins[1:]
            ax, params = ax.pdf(ws, bins=bins)
        
        .. figure:: screenshots/pdf.png
           :alt: pdf
        
           pdf
        
        Optimal parameters of Weibull distribution can be displayed using
        
        ::
        
            print(params)
            (1, 1.7042156870194352, 0, 7.0907180300605459)
        
        Functional API
        --------------
        
        Instead of using object oriented approach like previously shown, some
        "shortcut" functions have been defined: ``wrbox``, ``wrbar``,
        ``wrcontour``, ``wrcontourf``, ``wrpdf``. See `unit
        tests <tests/test_windrose.py>`__.
        
        Pandas support
        --------------
        
        windrose not only supports Numpy arrays. It also supports also Pandas
        DataFrame. ``plot_windrose`` function provides most of plotting features
        previously shown.
        
        ::
        
            N = 500
            ws = np.random.random(N) * 6
            wd = np.random.random(N) * 360
            df = pd.DataFrame({'speed': ws, 'direction': wd})
            plot_windrose(df, kind='contour', bins=np.arange(0.01,8,1), cmap=cm.hot, lw=3)
        
        Mandatory: - ``df``: Pandas DataFrame with ``DateTimeIndex`` as index
        and at least 2 columns (``'speed'`` and ``'direction'``).
        
        Optional: - ``kind`` : kind of plot (might be either, ``'contour'``,
        ``'contourf'``, ``'bar'``, ``'box'``, ``'pdf'``) - ``var_name`` : name
        of var column name ; default value is ``VAR_DEFAULT='speed'`` -
        ``direction_name`` : name of direction column name ; default value is
        ``DIR_DEFAULT='direction'`` - ``clean_flag`` : cleanup data flag (remove
        data points with ``NaN``, ``var=0``) before plotting ; default value is
        ``True``.
        
        Video export
        ------------
        
        A video of plots can be exported. See:
        
        |Video| |Video| |Video|
        
        `Source code <samples/sample_animate.py>`__
        
        This is just a sample for now. API for video need to be created.
        
        Use:
        
        ::
        
            $ python samples/sample_animate.py --help
        
        to display command line interface usage.
        
        .. |Latest Version| image:: https://img.shields.io/pypi/v/windrose.svg
           :target: https://pypi.python.org/pypi/windrose/
        .. |Supported Python versions| image:: https://img.shields.io/pypi/pyversions/windrose.svg
           :target: https://pypi.python.org/pypi/windrose/
        .. |Wheel format| image:: https://img.shields.io/pypi/wheel/windrose.svg
           :target: https://pypi.python.org/pypi/windrose/
        .. |License| image:: https://img.shields.io/pypi/l/windrose.svg
           :target: https://pypi.python.org/pypi/windrose/
        .. |Development Status| image:: https://img.shields.io/pypi/status/windrose.svg
           :target: https://pypi.python.org/pypi/windrose/
        .. |Downloads monthly| image:: https://img.shields.io/pypi/dm/windrose.svg
           :target: https://pypi.python.org/pypi/windrose/
        .. |Code Health| image:: https://landscape.io/github/scls19fr/windrose/master/landscape.svg?style=flat
           :target: https://landscape.io/github/scls19fr/windrose/master
        .. |Build Status| image:: https://travis-ci.org/scls19fr/windrose.svg
           :target: https://travis-ci.org/scls19fr/windrose
        .. |Video| image:: http://img.youtube.com/vi/_lfrwvjjVFw/0.jpg
           :target: https://www.youtube.com/watch?v=_lfrwvjjVFw
        .. |Video| image:: http://img.youtube.com/vi/e8kP64VXxR0/0.jpg
           :target: https://www.youtube.com/watch?v=e8kP64VXxR0
        .. |Video| image:: http://img.youtube.com/vi/CsALnB-0G28/0.jpg
           :target: https://www.youtube.com/watch?v=CsALnB-0G28
        
Keywords: python plot matplotlib numpy wind wind rose compass
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Cython
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3.3
Classifier: Programming Language :: Python :: 3.4
Classifier: License :: OSI Approved :: CEA CNRS Inria Logiciel Libre License, version 2.1 (CeCILL-2.1)
