File: startingguide.rst

package info (click to toggle)
metpy 1.7.1%2Bds-1
  • links: PTS, VCS
  • area: main
  • in suites: forky, sid
  • size: 18,584 kB
  • sloc: python: 41,853; makefile: 111; javascript: 57
file content (368 lines) | stat: -rw-r--r-- 14,073 bytes parent folder | download | duplicates (2)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
Getting Started with MetPy
==========================

Welcome to MetPy! We're glad you're here and we hope that you find this Python library
to be useful for your needs. In order to help get you started with MetPy, we've put together
this guide to introduce you to the basic syntax and functionality of this library. If you're
new to Python, please visit the `Unidata Python Training`_ site for in-depth
discussion and examples of the Scientific Python ecosystem.

For installation instructions, please see our :doc:`installguide`.

-----
Units
-----

For the in-depth explanation of units, associated syntax, and unique features, please see
our :doc:`Units Tutorial </tutorials/unit_tutorial>` page. What follows in this section is
a short summary of how MetPy uses units, which uses extensively the `Pint`_ library.

One of the most significant differences in syntax for MetPy, compared to other Python
libraries, is the frequent requirement of units to be attached to arrays before being
passed to MetPy functions. There are very few exceptions to this, and you'll usually be
safer to always use units whenever applicable to make sure that your analyses are done
correctly. Once you get used to the units syntax, it becomes very handy, as you never have
to worry about unit conversion for any calculation. MetPy does it for you!

To demonstrate the units syntax briefly here, we can do this:

.. code-block:: python

    import numpy as np
    from metpy.units import units

    distance = np.arange(1, 5) * units.meters

Another way to attach units is do create the array directly with the :class:`pint.Quantity`
object:

.. code-block:: python

    time = units.Quantity(np.arange(2, 10, 2), 'sec')

Unit-aware calculations can then be done with these variables:

.. code-block:: python

    print(distance / time)

.. parsed-literal::
    [ 0.5  0.5  0.5  0.5] meter / second


In addition to the :doc:`Units Tutorial </tutorials/unit_tutorial>` page, checkout the MetPy
Monday blog on
`units <https://www.unidata.ucar.edu/blogs/developer/en/entry/metpy-mondays-4-units-in>`_ or
watch our MetPy Monday video on
`temperature units <https://www.youtube.com/watch?v=iveJCqxe3Z4>`_.

-------------
Functionality
-------------

MetPy aims to have three primary purposes: read and write meteorological data (I/O), calculate
meteorological quantities with well-documented equations, and create publication-quality plots
of meteorological data. The three subsections that follow will demonstrate just some of this
functionality. For full reference to all of MetPy's API, please see our
:doc:`Reference Guide </api/index>`.

++++++++++++
Input/Output
++++++++++++

MetPy has built in support for reading GINI satellite and NEXRAD radar files. If you have one
of these files, opening it with MetPy is as easy as:

.. code-block:: python

    from metpy.io import Level2File, Level3File, GiniFile

    f = GiniFile(example_filename.gini)
    f = Level2File(example_filename.gz)
    f = Level3File(example_filename.gz)

From there, you can pull out the variables you want to analyze and plot. For more information,
see the :doc:`GINI </examples/formats/GINI_Water_Vapor>`,
:doc:`NEXRAD Level 2 </examples/formats/NEXRAD_Level_2_File>`, and
:doc:`NEXRAD Level 3 </examples/formats/NEXRAD_Level_3_File>` examples. MetPy Monday videos
`#29`_ and `#30`_ also show how to plot radar files with MetPy.

.. _`#29`: https://youtu.be/73fhfV2zOt8
.. _`#30`: https://youtu.be/fSax8g9EfxM

The other exciting feature is MetPy's Xarray accessor. Xarray is a Python package that
makes working with multi-dimensional labeled data (i.e. netCDF files) easy. For a thorough
look at Xarray's capabilities, see this `MetPy Monday video <https://youtu.be/_9j7Y1-lk-o>`_.
With MetPy's accessor to this package, we can quickly pull out common dimensions, parse
Climate and Forecasting (CF) metadata, and handle projection information. While the
:doc:`Xarray with MetPy </tutorials/xarray_tutorial>` is the best place to see the full
utility of the MetPy Xarray accessor, let's demonstrate some of the functionality here:

.. code-block:: python

    import xarray as xr
    import metpy
    from metpy.cbook import get_test_data

    ds = xr.open_dataset(get_test_data('narr_example.nc', as_file_obj = False))
    ds = ds.metpy.parse_cf()

    # Grab lat/lon values from file as unit arrays
    lats = ds.lat.metpy.unit_array
    lons = ds.lon.metpy.unit_array

    # Get the valid time
    vtime = ds.Temperature_isobaric.metpy.time[0]

    # Get the 700-hPa heights without manually identifying the vertical coordinate
    hght_700 = ds.Geopotential_height_isobaric.metpy.sel(vertical=700 * units.hPa,
                                                     time=vtime)

From here, you could make a map of the 700-hPa geopotential heights. We'll discuss how to
do that in the Plotting section.

++++++++++++
Calculations
++++++++++++

Meteorology and atmospheric science are fully-dependent on complex equations and formulas.
Rather than figuring out how to write them efficiently in Python yourself, MetPy provides
support for many of the common equations within the field. For the full list, please see the
:doc:`Calculations </api/generated/metpy.calc>` reference guide. If you don't see the equation
you're looking for, consider submitting a feature request to MetPy
`here <https://github.com/Unidata/MetPy/issues/new/choose>`_.

To demonstrate some of the calculations MetPy can do, let's show a simple example:

.. code-block:: python

    import numpy as np
    from metpy.units import units
    import metpy.calc as mpcalc

    temperature = [20] * units.degC
    rel_humidity  = [50] * units.percent
    print(mpcalc.dewpoint_from_relative_humidity(temperature, rel_humidity))

.. parsed-literal::

    array([9.27008599]) <Unit('degC')>

.. code-block:: python

    speed = np.array([5, 10, 15, 20]) * units.knots
    direction = np.array([0, 90, 180, 270]) * units.degrees
    u, v = mpcalc.wind_components(speed, direction)
    print(u, v)

.. parsed-literal::

    [0 -10 0 20] knot
    [-5 0 15 0] knot

As discussed above, if you don't provide units to these functions, they will frequently
fail with the following error:

.. parsed-literal::

    ValueError: `calculation` given arguments with incorrect units: `variable` requires
    "[`type of unit`]" but given "none". Any variable `x` can be assigned a unit as follows:
    from metpy.units import units
    x = x * units.meter / units.second

If you see this error in your code, just attach the appropriate units and you'll be good to go!

++++++++
Plotting
++++++++

MetPy contains two special types of meteorological plots, the Skew-T Log-P and Station plots,
that more general Python plotting packages don't support as readily. Additionally, with the
goal to replace GEMPAK, MetPy's declarative plotting interface is being actively developed,
which will make plotting a simple task with straight-forward syntax, similar to GEMPAK.

******
Skew-T
******

The Skew-T Log-P diagram is the canonical thermodynamic diagram within meteorology. Using
:mod:`matplotlib`, MetPy is able to readily create a Skew-T for you:

.. plot::
    :include-source: True

    import matplotlib.pyplot as plt
    import numpy as np
    import metpy.calc as mpcalc
    from metpy.plots import SkewT
    from metpy.units import units

    fig = plt.figure(figsize=(9, 9))
    skew = SkewT(fig)

    # Create arrays of pressure, temperature, dewpoint, and wind components
    p = [902, 897, 893, 889, 883, 874, 866, 857, 849, 841, 833, 824, 812, 796, 776, 751,
         727, 704, 680, 656, 629, 597, 565, 533, 501, 468, 435, 401, 366, 331, 295, 258,
         220, 182, 144, 106] * units.hPa
    t = [-3, -3.7, -4.1, -4.5, -5.1, -5.8, -6.5, -7.2, -7.9, -8.6, -8.9, -7.6, -6, -5.1,
         -5.2, -5.6, -5.4, -4.9, -5.2, -6.3, -8.4, -11.5, -14.9, -18.4, -21.9, -25.4,
         -28, -32, -37, -43, -49, -54, -56, -57, -58, -60] * units.degC
    td = [-22, -22.1, -22.2, -22.3, -22.4, -22.5, -22.6, -22.7, -22.8, -22.9, -22.4,
          -21.6, -21.6, -21.9, -23.6, -27.1, -31, -38, -44, -46, -43, -37, -34, -36,
          -42, -46, -49, -48, -47, -49, -55, -63, -72, -88, -93, -92] * units.degC
    # Calculate parcel profile
    prof = mpcalc.parcel_profile(p, t[0], td[0]).to('degC')
    u = np.linspace(-10, 10, len(p)) * units.knots
    v = np.linspace(-20, 20, len(p)) * units.knots

    skew.plot(p, t, 'r')
    skew.plot(p, td, 'g')
    skew.plot(p, prof, 'k')  # Plot parcel profile
    skew.plot_barbs(p[::5], u[::5], v[::5])

    skew.ax.set_xlim(-50, 15)
    skew.ax.set_ylim(1000, 100)

    # Add the relevant special lines
    skew.plot_dry_adiabats()
    skew.plot_moist_adiabats()
    skew.plot_mixing_lines()

    plt.show()


For some MetPy Monday videos on Skew-Ts, please watch `#16`_, `#18`_, and `#19`_. Hodographs
can also be created and plotted with a Skew-T (see MetPy Monday video `#38`_).
For more examples on how to do create Skew-Ts and Hodographs, please visit
check out the :doc:`Simple Sounding </examples/plots/Simple_Sounding>`,
:doc:`Advanced Sounding </examples/Advanced_Sounding>`, and
:doc:`Hodograph Inset </examples/plots/Hodograph_Inset>`.

.. _`#16`: https://youtu.be/oog6_b-844Q
.. _`#18`: https://youtu.be/quFXzaNbWXM
.. _`#19`: https://youtu.be/7QsBJTwuLvE
.. _`#38`: https://youtu.be/c0Uc7imDNv0

*************
Station Plots
*************

Station plots display surface or upper-air station data in a concise manner. The creation of
these plots is made straightforward with MetPy. MetPy supplies the ability to create each
station plot and place the points on the map. The creation of 2-D cartographic maps, commonly
used in meteorology for observational and model visualization, relies upon the :mod:`cartopy`
library. This package handles projections and transforms to make sure your data is plotted in
the correct location.

For examples on how to make a station plot, please see the
:doc:`Station Plot </examples/plots/Station_Plot>` and
:doc:`Station Plot Layout </examples/plots/Station_Plot_with_Layout>` examples.

************
Gridded Data
************

While MetPy doesn't provide many new tools for 2-D gridded data maps, we do provide lots of
examples illustrating how to use MetPy for data analysis and CartoPy for visualization. Those
examples can be found in the :doc:`MetPy Gallery </examples/index>` and at the
`Unidata Python Training`_ site.

One unique tool in MetPy for gridded data is cross-section analysis. A detailed example of how
to create a cross section with your gridded data is available
:doc:`here </examples/cross_section>`.

********************
Declarative Plotting
********************

The declarative plotting interface, which is still under active development, aims to replicate
the simple plotting declarations in GEMPAK to make map creation straightforward, especially
for those less familiar with Python, CartoPy, and matplotlib. To demonstrate the ease of
creating a plot with this interface, let's make a color-filled plot of temperature using
NARR data.

.. plot::
    :include-source: True

    import xarray as xr
    from metpy.cbook import get_test_data
    from metpy.plots import ImagePlot, MapPanel, PanelContainer
    from metpy.units import units

    # Use sample NARR data for plotting
    narr = xr.open_dataset(get_test_data('narr_example.nc', as_file_obj=False))

    img = ImagePlot()
    img.data = narr
    img.field = 'Geopotential_height'
    img.level = 850 * units.hPa

    panel = MapPanel()
    panel.area = 'us'
    panel.layers = ['coastline', 'borders', 'states', 'rivers', 'ocean', 'land']
    panel.title = 'NARR Example'
    panel.plots = [img]

    pc = PanelContainer()
    pc.size = (10, 8)
    pc.panels = [panel]
    pc.show()

Other plot types are available, including contouring to create overlay maps. For an example of
this, check out the :doc:`Combined Plotting </examples/plots/Combined_plotting>` example.
MetPy Monday videos `#69`_, `#70`_, and `#71`_ also demonstrate the declarative plotting
interface.

.. _`#69`: https://youtu.be/mbxE2ovXx9M
.. _`#70`: https://youtu.be/QgS27jwj8OI
.. _`#71`: https://youtu.be/RBJ8Pm7x4ok

----------------------
Other Python Resources
----------------------

While MetPy does a lot of things, it doesn't do everything. Here are some other good resources
to use as you start using MetPy and Python for meteorology and atmospheric science:

**Learning Resources**

* `Unidata Python Training`_
* `MetPy Monday Playlist`_

.. _`Unidata Python Training`: https://unidata.github.io/python-training
.. _`MetPy Monday Playlist`:
     https://www.youtube.com/playlist?list=PLQut5OXpV-0ir4IdllSt1iEZKTwFBa7kO

**Useful Python Packages**

* `Siphon`_: remote access of meteorological data, including simple web services and and via
  `THREDDS Data Servers`_
* netCDF4-python_ is the officially blessed Python API for netCDF_
* `Xarray`_: reading/writing labeled N-dimensional arrays
* `Pandas`_: reading/writing tabular data
* `NumPy`_: numerical computations
* `Matplotlib`_: creation of publication-quality figures
* `CartoPy`_: publication-quality cartographic maps
* `Pint`_: physical units tracking and conversion
* `SatPy`_: read and visualize satellite data
* `PyART`_: read and visualize radar data

.. _Siphon: https://unidata.github.io/siphon/
.. _THREDDS Data Servers: https://docs.unidata.ucar.edu/tds/current/userguide/index.html
.. _netCDF4-python: https://unidata.github.io/netcdf4-python/
.. _netCDF: https://www.unidata.ucar.edu/software/netcdf/
.. _Xarray: https://docs.xarray.dev/en/stable/
.. _Pandas: https://pandas.pydata.org
.. _NumPy: https://numpy.org/devdocs
.. _Matplotlib: https://matplotlib.org
.. _CartoPy: https://scitools.org.uk/cartopy/docs/latest/
.. _Pint: https://pint.readthedocs.io/en/stable/
.. _SatPy: https://satpy.readthedocs.io/en/latest/
.. _PyART: https://arm-doe.github.io/pyart/

-------
Support
-------

Get stuck trying to use MetPy with your data? Unidata's Python team is here to help! See our
:doc:`support page <SUPPORT>` for more information.