Change default configuration of netcdf file output coordinates

[amoodie]

changes

This PR changes the default netCDF output file to be more easily importable and operable with the xarray package. Backwards compatibility (e.g., creating the old format) is maintained through a legacy_netcdf flag.

The change in the netcdf file is described below, and is documented in the legacy_netcdf DeltaModel attribute.

        +-------------+-------------------+---------------------------------+
        |             | default           | legacy                          |
        +=============+===================+=================================+
        | dimensions  | `time`, `x`, `y`  | `total_time`, `length`, `width` |
        +---------------+------------------------+--------------------------+
        | variables   | `time`, `x`, `y`  | `time`, `y`, `x`; x, y as 2D    |
        +-------------+------------------------+----------------------------+
        | data        | `t-x-y` array     | `t-y-x` array                   |
        +-------------+-------------------+---------------------------------+

I have also updated the documentation in the outputfile guide.

deltametrics preview

A preview of how this will work more smoothly with DeltaMetrics. Note, that the new format will not work with the current deltametrics version. So, I have some changes ready to go there shortly when we merge this and I update the same data on DeltaMetrics. I believe the changes there will be API-breaking but since we are in alpha, we can just increment the minor version and break everything. I'm also working on a guide to setting up any sedimentary model/experiment/dataset to be usable with DeltaMetrics, based on what I've learned here.

before = dm.cube.DataCube('/scratch/change_grid/before/pyDeltaRCM_output.nc')
after = dm.cube.DataCube('/scratch/change_grid/after_2/pyDeltaRCM_output.nc')

fig, ax = plt.subplots(2, 2)
ax[0, 0].imshow(before['eta'][-1, :, :])
ax[0, 1].imshow(after['eta'][-1, :, :])
before['eta'][-1, :, :].plot.imshow(ax=ax[1, 0], cmap='viridis')
after['eta'][-1, :, :].plot.imshow(ax=ax[1, 1], cmap='viridis')
plt.show(block=False)

after_strat = dm.cube.StratigraphyCube.from_DataCube(after, dz=0.1)
after_strat.register_section('circular', dm.section.CircularSection(radius=8))

fig, ax = plt.subplots(1, 2)
after.show_plan('eta', t=-1, ticks=True, ax=ax[0])
after_strat.sections['circular'].show_trace(ax=ax[0])
after_strat.sections['circular'].show('time', ax=ax[1])
plt.show(block=False)

The key point on the above plot is that in the left column (the before this PR column), the xarray plotting routine did not know how to use the field x and y in the data file. In the right column, xarray finds as uses these fields. In DM, we will want to plot things manually still (not using xarray's interface, but using the mpl interface), but this helps make sure that everything will be set up correctly.

The key point here is just that things mostly still work in DeltaMetrics, with a few tweaks. So, we have to integrate the dimensions still, but not everything is broken, which is good :smile:

[codecov[bot]]

Codecov Report

Merging #233 (d1e1da1) into develop (06b04d4) will increase coverage by 0.09%. The diff coverage is 96.42%.

@@             Coverage Diff             @@
##           develop     #233      +/-   ##
===========================================
+ Coverage    78.59%   78.68%   +0.09%     
===========================================
  Files           12       12              
  Lines         2560     2576      +16     
===========================================
+ Hits          2012     2027      +15     
- Misses         548      549       +1     

Impacted Files	Coverage Δ
pyDeltaRCM/model.py	89.40% <83.33%> (-0.06%)	:arrow_down:
pyDeltaRCM/_version.py	100.00% <100.00%> (ø)
pyDeltaRCM/init_tools.py	97.10% <100.00%> (+0.07%)	:arrow_up:

---

Continue to review full report at Codecov.

Legend - Click here to learn more Δ = absolute <relative> (impact), ø = not affected, ? = missing data Powered by Codecov. Last update 06b04d4...d1e1da1. Read the comment docs.

[amoodie]

note that docs build is only failing due to outage on the csdms website