1.0 Upgrade guide

[dopplershift]

We should have a page in the docs that covers any requisite change to upgrade to 1.0:

• Function name/arg changes
• XArray data model changes
• How to take advantage of new stuff

[jthielen]

Below is just organizing notes on what should be included in this upgrade guide (and related 1.0 doc updates) from all the scattered places I had them previously. Not necessarily a complete list, but feel free to edit or comment below with additional suggestions I don't have up yet.

• Clarify dimensionality on assign_* helpers in docs
• Add reference to http://cfconventions.org/Data/cf-conventions/cf-conventions-1.7/cf-conventions.html#appendix-grid-mappings with assign_crs, and a brief example of the parameters needed
  • May be modified based on Use PyProj instead of CartoPy for calculations #1455
• Include example where manually adding projection info through assign_crs is needed instead of parse_cf (esp. with GRIB, such as Cross-Section from HRRR output #1004 (comment))
• Emphasize "returns new" behavior in summary line of docstring for assign_* functions
• Emphasize the "returns new" behavior of MetPy's xarray stuff in tutorial
• Document the metadata requirements needed for various xarray "magic" features (cross sections, kinematics, declarative plotting, etc.) to work properly
• Explain how "quantification" works in xarray and MetPy and how to interoperate properly with xarray and Pint (and where existing pain points still exist)
  • Particularly need a strongly worded warning about the change in behavior from before and to not mix Quantity-in-xarray- and units-on-attribute-assuming code
• Document how to "deparse" or "parse down" your xarray Dataset to safely write to disk
• List out all the function call signature API breaks (perhaps with before and after?), and explain general troubleshooting steps to handle the API breaks
• Comment on updated minimum versions/dependency changes

[jthielen]

While on the last telecon I had mentioned I would give some more thought to how to split up the workload on this upgrade guide, in the limited time I've had to do so, I haven't come up with any grand insights...but here it goes anyways:

I guess I would see the major portions of this being:

• an overhauled xarray with MetPy tutorial that demonstrates
  • all the features of the accessors both new and old (emphasizing the "returns new" rather than "in place" paradigm)
  • metadata requirements for all features that leverage them
  • recommended workflows to account for quantification concerns
  • how to parse down your xarray data to write safely to disk
  • Question: can plotting be handled separately from this tutorial (see next major item)?
  • I think this might be best for me to take on?
• narrative documentation for declarative plotting/recommended plotting workflows
  • featuring what's new/fixed in 1.0 as well as easier xarray use
  • @kgoebber I'd think this could be something you may want to take on?
  • not sure if this would be a good place to demo da.plot-style preview plots like the current xarray tutorial has?
• API changes
  • perhaps a side-by-side of v0.12 and v1.0 APIs that have been changed
  • kinematics (with the removal of dim_order and addition of x_dim, y_dim and xarray grid argument magic) is particularly key here
  • recommended processes for identifying and resolving issues with the altered APIs
  • @dopplershift or @dcamron?
• Summary page
  • link out to all the key sub components
  • comment on when xarray return values can be expected (e.g., non-profile thermo calculations, kinematics) and when they aren't (e.g., profile calculations)
  • probably the best place to mention dependency changes (PyProj/Cartopy, new minimum versions, etc.)
  • @dopplershift or @dcamron?

One other item that I think should be addressed before the final v1.0 docs, but I'm not sure the context it fits best into, is unit support documentation. There's been a lot of updates to unit support over the course of v1.0 (either in MetPy itself or upstream in Pint), and I think it would be worth calling these things out explicitly in a place that can be easily referred to when providing support. Items I'd see worth covering:

• reconcile/combine the two different "unit support" pages in the docs (https://unidata.github.io/MetPy/dev/units.html and https://unidata.github.io/MetPy/dev/tutorials/unit_tutorial.html)
• percent sign and UDUNITS power support (Add percent sign and UDUNITS exponent syntax support via Pint's new preprocessor option #1281), since the percent sign correction hack is pervasive
• Jupyter repr fix (Change HTML repr away from LaTeX to a Sparse/Dask-like repr hgrecco/pint#1133), since having to always use print for fear of crashing your notebook is also rather pervasive
• current state of masked array support (waiting on upstream fix) and recommendations on how to deal with it
• comment on NEP 18 support (can use Quantities more directly inside NumPy functions, preliminary support for nesting with Dask, sparse, etc., with more optimized support to come in future)

Finally, please do fill in with anything you think I'm missing, or something I mentioned that isn't really needed at this point!

[kgoebber]

More than happy to do the declarative parts...it will help me prep for my class using it next semester. Early testing last night makes using calculations and adding new computed variable into xarray a since with MetPy 1.0rc2! How/where are we going to compile all of these pieces for the Upgrade Guide? Where within the documentation do we want to house this? Would it be worth having a declarative syntax tutorial, in addition to information for the upgrade guide?

[jthielen]

@dopplershift Unfortunately I didn't get the chance to get to the xarray tutorial this weekend. Not sure where you're at with things, but wanted to mention that I still may have another chance this evening or tomorrow if you don't get around to it by then (or, if you do, can review then too).