.. DO NOT EDIT.
.. THIS FILE WAS AUTOMATICALLY GENERATED BY SPHINX-GALLERY.
.. TO MAKE CHANGES, EDIT THE SOURCE PYTHON FILE:
.. "examples/tc_rainfall.py"
.. LINE NUMBERS ARE GIVEN BELOW.

.. only:: html

    .. note::
        :class: sphx-glr-download-link-note

        :ref:`Go to the end <sphx_glr_download_examples_tc_rainfall.py>`
        to download the full example code

.. rst-class:: sphx-glr-example-title

.. _sphx_glr_examples_tc_rainfall.py:


=========================
Tropical Cyclone Rainfall
=========================
This sample script shows how to use Tropycal to retrieve and plot rainfall associated with U.S. tropical cyclones, from the Weather Prediction Center (WPC)'s database.

.. GENERATED FROM PYTHON SOURCE LINES 7-10

.. code-block:: default


    from tropycal import tracks, rain








.. GENERATED FROM PYTHON SOURCE LINES 11-19

Reading In HURTDAT2 Dataset
---------------------------

Let's start with the HURDAT2 dataset by loading it into memory. By default, this reads in the HURDAT dataset from the National Hurricane Center (NHC) website, unless you specify a local file path using either ``atlantic_url`` for the North Atlantic basin on ``pacific_url`` for the East & Central Pacific basin.

HURDAT data is not available for the current year. To include the latest data up through today, the "include_btk" flag needs to be set to True, which reads in preliminary best track data from the NHC website. For this example, we'll set this to False.

Let's create an instance of a TrackDataset object, which will store the North Atlantic HURDAT2 dataset in memory. Once we have this we can use its methods for various types of analyses.

.. GENERATED FROM PYTHON SOURCE LINES 19-22

.. code-block:: default


    basin = tracks.TrackDataset(basin='north_atlantic',include_btk=False)





.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    --> Starting to read in HURDAT2 data
    --> Completed reading in HURDAT2 data (2.16 seconds)




.. GENERATED FROM PYTHON SOURCE LINES 23-29

WPC Rainfall Dataset
--------------------

Next, we'll read in rainfall associated with tropical cyclones. Tropical cyclones are known to produce heavy rainfall, with at times catastrophic flooding. The Weather Prediction Center (WPC) routinely issues advisories on tropical cyclones or their remnants inland, and maintains a database of rainfall associated with tropical cyclones in the US.

This dataset is now available in CSV format, and can be easily read into Tropycal using the new Rain module:

.. GENERATED FROM PYTHON SOURCE LINES 29-32

.. code-block:: default


    rain_obj = rain.RainDataset()





.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    --> Starting to read in rainfall data
    --> Completed reading in rainfall data (8.87 seconds)




.. GENERATED FROM PYTHON SOURCE LINES 33-36

Hurricane Harvey (2017) produced catastrophic flooding over Texas. Let's pull its rain observations to take a deeper look.

To do so, we'll first need to retrieve a Storm object for Harvey, then provide it as an input argument to ``get_storm_rainfall()``. This will return a Pandas DataFrame containing all rainfall observations associated with Harvey.

.. GENERATED FROM PYTHON SOURCE LINES 36-43

.. code-block:: default


    #Retrieve storm object
    storm = basin.get_storm(('harvey',2017))

    #Retrieve storm rainfall
    harvey_rain = rain_obj.get_storm_rainfall(storm)








.. GENERATED FROM PYTHON SOURCE LINES 44-45

Now let's look through the pandas DataFrame containing Harvey's rainfall:

.. GENERATED FROM PYTHON SOURCE LINES 45-48

.. code-block:: default


    harvey_rain






.. raw:: html

    <div class="output_subarea output_html rendered_html output_result">
    <div>
    <style scoped>
        .dataframe tbody tr th:only-of-type {
            vertical-align: middle;
        }

        .dataframe tbody tr th {
            vertical-align: top;
        }

        .dataframe thead th {
            text-align: right;
        }
    </style>
    <table border="1" class="dataframe">
      <thead>
        <tr style="text-align: right;">
          <th></th>
          <th>Station</th>
          <th>Total</th>
          <th>Lat</th>
          <th>Lon</th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <th>261570</th>
          <td>ABEL                     5 SW</td>
          <td>1.79</td>
          <td>33.60</td>
          <td>-85.65</td>
        </tr>
        <tr>
          <th>261571</th>
          <td>ADDISON</td>
          <td>2.17</td>
          <td>34.20</td>
          <td>-87.18</td>
        </tr>
        <tr>
          <th>261572</th>
          <td>ALABASTER</td>
          <td>1.42</td>
          <td>33.18</td>
          <td>-86.78</td>
        </tr>
        <tr>
          <th>261573</th>
          <td>ALBERTVILLE</td>
          <td>1.63</td>
          <td>34.24</td>
          <td>-86.19</td>
        </tr>
        <tr>
          <th>261574</th>
          <td>ALEXANDER CITY</td>
          <td>2.46</td>
          <td>32.95</td>
          <td>-85.95</td>
        </tr>
        <tr>
          <th>...</th>
          <td>...</td>
          <td>...</td>
          <td>...</td>
          <td>...</td>
        </tr>
        <tr>
          <th>268375</th>
          <td>WHITE SULPHUR SPRINGS</td>
          <td>1.14</td>
          <td>37.80</td>
          <td>-80.48</td>
        </tr>
        <tr>
          <th>268376</th>
          <td>WHITE SULPHUR SPRINGS</td>
          <td>0.96</td>
          <td>37.80</td>
          <td>-80.30</td>
        </tr>
        <tr>
          <th>268377</th>
          <td>WHITMER                  3 W</td>
          <td>0.20</td>
          <td>38.82</td>
          <td>-79.60</td>
        </tr>
        <tr>
          <th>268378</th>
          <td>WILLIAMSON</td>
          <td>0.61</td>
          <td>37.67</td>
          <td>-82.28</td>
        </tr>
        <tr>
          <th>268379</th>
          <td>WOLF PEN</td>
          <td>0.40</td>
          <td>37.53</td>
          <td>-81.58</td>
        </tr>
      </tbody>
    </table>
    <p>6797 rows × 4 columns</p>
    </div>
    </div>
    <br />
    <br />

.. GENERATED FROM PYTHON SOURCE LINES 49-50

We can use Pandas' DataFrame utility to rearrange this by the "Total" column (representing rainfall in inches) to see the highest rain total associated with Harvey - which gives us 60.58 inches near Nederland.

.. GENERATED FROM PYTHON SOURCE LINES 50-53

.. code-block:: default


    harvey_rain.sort_values('Total',ascending=False)






.. raw:: html

    <div class="output_subarea output_html rendered_html output_result">
    <div>
    <style scoped>
        .dataframe tbody tr th:only-of-type {
            vertical-align: middle;
        }

        .dataframe tbody tr th {
            vertical-align: top;
        }

        .dataframe thead th {
            text-align: right;
        }
    </style>
    <table border="1" class="dataframe">
      <thead>
        <tr style="text-align: right;">
          <th></th>
          <th>Station</th>
          <th>Total</th>
          <th>Lat</th>
          <th>Lon</th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <th>267161</th>
          <td>Nederland 1.5 SW</td>
          <td>60.58</td>
          <td>29.950000</td>
          <td>-94.010000</td>
        </tr>
        <tr>
          <th>266354</th>
          <td>Groves 1.3 N</td>
          <td>60.54</td>
          <td>29.960000</td>
          <td>-93.920000</td>
        </tr>
        <tr>
          <th>266199</th>
          <td>Friendswood</td>
          <td>56.00</td>
          <td>29.500000</td>
          <td>-95.200000</td>
        </tr>
        <tr>
          <th>267575</th>
          <td>Santa Fe 3 ENE</td>
          <td>54.77</td>
          <td>29.390000</td>
          <td>-95.050000</td>
        </tr>
        <tr>
          <th>265621</th>
          <td>Friendswood</td>
          <td>54.00</td>
          <td>29.745100</td>
          <td>-95.566600</td>
        </tr>
        <tr>
          <th>...</th>
          <td>...</td>
          <td>...</td>
          <td>...</td>
          <td>...</td>
        </tr>
        <tr>
          <th>263372</th>
          <td>MADISON</td>
          <td>0.00</td>
          <td>39.430000</td>
          <td>-92.170000</td>
        </tr>
        <tr>
          <th>266215</th>
          <td>Fulshear 2.7 WNW</td>
          <td>0.00</td>
          <td>29.707364</td>
          <td>-95.939681</td>
        </tr>
        <tr>
          <th>263375</th>
          <td>MARSHALL</td>
          <td>0.00</td>
          <td>39.130000</td>
          <td>-93.220000</td>
        </tr>
        <tr>
          <th>263376</th>
          <td>MARSHFIELD</td>
          <td>0.00</td>
          <td>37.340000</td>
          <td>-92.900000</td>
        </tr>
        <tr>
          <th>263374</th>
          <td>MANSFIELD</td>
          <td>0.00</td>
          <td>37.120000</td>
          <td>-92.580000</td>
        </tr>
      </tbody>
    </table>
    <p>6797 rows × 4 columns</p>
    </div>
    </div>
    <br />
    <br />

.. GENERATED FROM PYTHON SOURCE LINES 54-55

More generically speaking, we can write the code below to retrieve the row with the maximum rainfall for the storm, then retrieve its rain total in inches, station name, and coordinates.

.. GENERATED FROM PYTHON SOURCE LINES 55-65

.. code-block:: default


    import numpy as np

    row = harvey_rain.loc[harvey_rain['Total'] == np.nanmax(harvey_rain['Total'])]

    print(f"Max Rainfall = {row['Total'].values[0]} Inches")
    print(f"Location = {row['Station'].values[0]}")
    print(f"Latitude = {row['Lat'].values[0]}")
    print(f"Longitude = {row['Lon'].values[0]}")





.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    Max Rainfall = 60.58 Inches
    Location = Nederland 1.5 SW
    Latitude = 29.95
    Longitude = -94.01




.. GENERATED FROM PYTHON SOURCE LINES 66-73

Plotting TC Rainfall
--------------------
Tropycal provides two methods to plot tropical cyclone rainfall: by grid, or by individual observations.

We'll start off with plotting gridded rainfall. First we'll need to interpolate to a cartesian grid using the ``interpolate_to_grid()`` method, and retrieve an xarray DataArray of the grid and its associated coordinates. Note that the default is to interpolate to a 0.1 degree grid - you can use the ``grid_res`` argument to provide a different resolution.

Next we'll use the ``plot_rain_grid()`` method to plot the output, and provide contour levels for plotting. As Hurricane Harvey was most damaging in Texas, we'll provide a custom domain zoomed in over Texas.

.. GENERATED FROM PYTHON SOURCE LINES 73-80

.. code-block:: default


    #Interpolate to grid
    grid = rain_obj.interpolate_to_grid(storm,return_xarray=True)

    levels = [1,2,4,8,12,16,20,30,40,50,60]
    rain_obj.plot_rain_grid(storm,grid,levels,domain={'s':26,'n':39,'w':-103,'e':-82})




.. image-sg:: /examples/images/sphx_glr_tc_rainfall_001.png
   :alt: Hurricane HARVEY Interpolated WPC Storm Rainfall (in), 17 Aug 2017 – 01 Sep 2017 115 kt • 937 hPa • 11.4 ACE
   :srcset: /examples/images/sphx_glr_tc_rainfall_001.png
   :class: sphx-glr-single-img


.. rst-class:: sphx-glr-script-out

 .. code-block:: none


    <GeoAxes: title={'left': 'Hurricane HARVEY\nInterpolated WPC Storm Rainfall (in)', 'right': '17 Aug 2017 – 01 Sep 2017\n115 kt • 937 hPa • 11.4 ACE'}>



.. GENERATED FROM PYTHON SOURCE LINES 81-84

Linear interpolation isn't perfect of course, especially considering that some observations in this dataset aren't perfectly quality controlled.

To compensate, we can also plot the individual rain observation dots using the ``plot_rain()`` method:

.. GENERATED FROM PYTHON SOURCE LINES 84-88

.. code-block:: default


    levels = [1,2,4,8,12,16,20,30,40,50,60]
    rain_obj.plot_rain(storm,levels=levels,domain={'s':26,'n':39,'w':-103,'e':-82})




.. image-sg:: /examples/images/sphx_glr_tc_rainfall_002.png
   :alt: Hurricane HARVEY WPC Storm Rainfall (inch), 17 Aug 2017 – 01 Sep 2017 115 kt • 937 hPa • 11.4 ACE
   :srcset: /examples/images/sphx_glr_tc_rainfall_002.png
   :class: sphx-glr-single-img


.. rst-class:: sphx-glr-script-out

 .. code-block:: none


    <GeoAxes: title={'left': 'Hurricane HARVEY\nWPC Storm Rainfall (inch)', 'right': '17 Aug 2017 – 01 Sep 2017\n115 kt • 937 hPa • 11.4 ACE'}>



.. GENERATED FROM PYTHON SOURCE LINES 89-92

The Houston, Texas metro was particularly hard-hit by Hurricane Harvey, with rain totals over 30 inches in many locations.

Let's filter the plot to only rain observations over 30 inches to highlight this, while zooming in closer over Houston:

.. GENERATED FROM PYTHON SOURCE LINES 92-94

.. code-block:: default


    levels = [1,2,4,8,12,16,20,30,40,50,60]
    rain_obj.plot_rain(storm,levels=levels,minimum_threshold=30,domain={'s':27,'n':32,'w':-99,'e':-92})


.. image-sg:: /examples/images/sphx_glr_tc_rainfall_003.png
   :alt: Hurricane HARVEY WPC Storm Rainfall (>30 inch), 17 Aug 2017 – 01 Sep 2017 115 kt • 937 hPa • 11.4 ACE
   :srcset: /examples/images/sphx_glr_tc_rainfall_003.png
   :class: sphx-glr-single-img


.. rst-class:: sphx-glr-script-out

 .. code-block:: none


    <GeoAxes: title={'left': 'Hurricane HARVEY\nWPC Storm Rainfall (>30 inch)', 'right': '17 Aug 2017 – 01 Sep 2017\n115 kt • 937 hPa • 11.4 ACE'}>




.. rst-class:: sphx-glr-timing

   **Total running time of the script:** ( 0 minutes  18.383 seconds)


.. _sphx_glr_download_examples_tc_rainfall.py:

.. only:: html

  .. container:: sphx-glr-footer sphx-glr-footer-example




    .. container:: sphx-glr-download sphx-glr-download-python

      :download:`Download Python source code: tc_rainfall.py <tc_rainfall.py>`

    .. container:: sphx-glr-download sphx-glr-download-jupyter

      :download:`Download Jupyter notebook: tc_rainfall.ipynb <tc_rainfall.ipynb>`


.. only:: html

 .. rst-class:: sphx-glr-signature

    `Gallery generated by Sphinx-Gallery <https://sphinx-gallery.github.io>`_