Metadata-Version: 2.1
Name: marutils
Version: 1.0.0
Summary: Utilities and tools for working with MAR regional climate model outputs through xarray
Home-page: https://github.com/GlacioHack/marutils
Author: GlacioHack / Andrew Tedstone (@atedstone)
Author-email: andrew.tedstone@unifr.ch
License: UNKNOWN
Project-URL: Bug Tracker, https://github.com/GlacioHack/marutils/issues
Platform: UNKNOWN
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.6
Description-Content-Type: text/markdown

# marutils - Utilities for working with MAR RCM outputs

This package contains utilities/tools that make it easier to open MAR RCM outputs.

* Load outputs straight into an xarray Dataset with standard dimensions names `(time, y, x)`.
* Provide a path with a wildcard expression (`*`) to automatically load several years of MAR files at once, concatenating them along the time axis.
* Plays nicely with Dask - chunking options default to 365-366 days (but can be changed at will).
* Loaded Datasets are automatically "geo-aware" using the rioxarray `.rio` accessor - no more trying to work out MAR's geo-referencing manually!
* Helper functions for turning X-hourly variables into continuous time series.
* Helper functions for masking.


## QuickStart

```python
import marutils
# Open a time series for the 21st century.
mar_outputs = marutils.open_dataset('MARv3.11.2/MAR*20*.nc')

# Check out the coordinates.
print(mar_outputs.coords)
Coordinates:
  * x            (x) float32 -760000.0 -740000.0 -720000.0 ... 660000.0 680000.0
  * y            (y) float32 -1180000.0 -1160000.0 ... 1480000.0 1500000.0
  * SECTOR       (SECTOR) float32 1.0 2.0
  * SECTOR1_1    (SECTOR1_1) float32 1.0
  * time         (time) datetime64[ns] 2019-01-01T12:00:00 ... 2019-12-31T12:...
  * ATMLAY3_3    (ATMLAY3_3) float32 0.99974793
    spatial_ref  int64 0

# What is proj.4 string for the geo-referencing of this dataset?
print(mar_outputs.rio.crs.to_proj4())
+proj=stere +lat_0=70.5 +lon_0=-40 +k=1 +x_0=0 +y_0=0 +datum=WGS84 +units=m +no_defs=True
```

## Installation

At the moment, manually:

	git clone <repository>
	cd <repository>
	pip install -e .

Soon to be available via pyPI.


## Working with X-hourly outputs

To return an X-hourly variable with a single, continuous hourly time variable:

```python
hourly_air_temperatures = marutils.xhourly.Xhourly_to_time(mar_outputs.TTH)
```

## Useful notes

### Pixel corners vs centres

It's useful to remember that netCDF file geo-referencing treats X,Y coordinates as pixel (cell) centres. In contrast, the rasterio/GDAL data model treats X,Y coordinates as pixel upper-left corners.

In the QuickStart section above we loaded a 20 km resolution dataset. The minimum and maximum X coordinates are -760000 and 680000 m respectively. These correspond to the centres of the min/max pixels.

Through the `.rio` accessor we can check on the bounds/complete spatial extent of the file:

```python
# What is the centre of the top-left cell? (xmin, ymin, xmax, ymax)
mar_outputs.rio.bounds()
(-770000.0, 1510000.0, 690000.0, -1190000.0)
```

We can see that these bounds account for the 20 km pixel size of this dataset.


## Caveats

The geo-referencing capabilities have so far been tested only for Greenland datasets. If you have problems trying to load other domains, please post an issue on this repository.



