def test_nominal(self):
"""
Nominal test
"""
dataset = xr.Dataset({
'first': (['lat', 'lon', 'time'], np.random.rand(5, 10, 2)),
'second': (['lat', 'lon', 'time'], np.random.rand(5, 10, 2)),
'lat':
np.linspace(-89.5, 89.5, 5),
'lon':
np.linspace(-179.5, 179.5, 10),
'time':
pd.date_range('2000-01-01', periods=2)
})
indexers = {'time': '2000-01-01', 'lat': -88}
out = get_var_data(dataset.second, indexers, remaining_dims=[
'lon',
])
self.assertEqual(out.time, np.datetime64('2000-01-01'))
self.assertEqual(out.lat, -89.5)
self.assertEqual(len(out.lon.values), 10)
indexers = {
'lat': -88,
}
out = get_var_data(dataset.second,
indexers,
remaining_dims=[
'lon',
],
time=np.datetime64('2000-01-01'))
self.assertEqual(out.time, np.datetime64('2000-01-01'))
self.assertEqual(out.lat, -89.5)
self.assertEqual(len(out.lon.values), 10)
def plot_contour(ds: xr.Dataset,
var: VarName.TYPE,
time: TimeLike.TYPE = None,
indexers: DictLike.TYPE = None,
title: str = None,
filled: bool = True,
properties: DictLike.TYPE = None,
file: str = None) -> Figure:
"""
Create a contour plot of a variable given by dataset *ds* and variable name *var*.
:param ds: the dataset containing the variable to plot
:param var: the variable's name
:param time: time slice index to plot, can be a string "YYYY-MM-DD" or an integer number
:param indexers: Optional indexers into data array of *var*. The *indexers* is a dictionary
or a comma-separated string of key-value pairs that maps the variable's dimension names
to constant labels. e.g. "layer=4".
:param title: an optional title
:param filled: whether the regions between two contours shall be filled
:param properties: optional plot properties for Python matplotlib,
e.g. "bins=512, range=(-1.5, +1.5), label='Sea Surface Temperature'"
For full reference refer to
https://matplotlib.org/api/lines_api.html and
https://matplotlib.org/devdocs/api/_as_gen/matplotlib.patches.Patch.html#matplotlib.patches.Patch
:param file: path to a file in which to save the plot
:return: a matplotlib figure object or None if in IPython mode
"""
var_name = VarName.convert(var)
if not var_name:
raise ValidationError("Missing name for 'var'")
var = ds[var_name]
time = TimeLike.convert(time)
indexers = DictLike.convert(indexers) or {}
properties = DictLike.convert(properties) or {}
figure = plt.figure(figsize=(8, 4))
ax = figure.add_subplot(111)
var_data = get_var_data(var, indexers, time=time)
if filled:
var_data.plot.contourf(ax=ax, **properties)
else:
var_data.plot.contour(ax=ax, **properties)
if title:
ax.set_title(title)
figure.tight_layout()
if file:
figure.savefig(file)
return figure if not in_notebook() else None
def plot_hist(ds: xr.Dataset,
var: VarName.TYPE,
indexers: DictLike.TYPE = None,
title: str = None,
properties: DictLike.TYPE = None,
file: str = None) -> Figure:
"""
Plot a variable, optionally save the figure in a file.
The plot can either be shown using pyplot functionality, or saved,
if a path is given. The following file formats for saving the plot
are supported: eps, jpeg, jpg, pdf, pgf, png, ps, raw, rgba, svg,
svgz, tif, tiff
:param ds: Dataset that contains the variable named by *var*.
:param var: The name of the variable to plot
:param indexers: Optional indexers into data array of *var*. The *indexers* is a dictionary
or a comma-separated string of key-value pairs that maps the variable's dimension names
to constant labels. e.g. "lon=12.6, layer=3, time='2012-05-02'".
:param title: an optional title
:param properties: optional histogram plot properties for Python matplotlib,
e.g. "bins=512, range=(-1.5, +1.5), label='Sea Surface Temperature'"
For full reference refer to
https://matplotlib.org/devdocs/api/_as_gen/matplotlib.pyplot.hist.html and
https://matplotlib.org/devdocs/api/_as_gen/matplotlib.patches.Patch.html#matplotlib.patches.Patch
:param file: path to a file in which to save the plot
:return: a matplotlib figure object or None if in IPython mode
"""
var_name = VarName.convert(var)
if not var_name:
raise ValidationError("Missing name for 'var'")
var = ds[var]
indexers = DictLike.convert(indexers)
properties = DictLike.convert(properties) or {}
figure = plt.figure(figsize=(8, 4))
ax = figure.add_subplot(111)
figure.tight_layout()
var_data = get_var_data(var, indexers)
var_data.plot.hist(ax=ax, **properties)
if title:
ax.set_title(title)
figure.tight_layout()
if file:
figure.savefig(file)
return figure if not in_notebook() else None
def plot_hist(ds: xr.Dataset,
var: VarName.TYPE,
indexers: DictLike.TYPE = None,
title: str = None,
properties: DictLike.TYPE = None,
file: str = None) -> Figure:
"""
Plot a variable, optionally save the figure in a file.
The plot can either be shown using pyplot functionality, or saved,
if a path is given. The following file formats for saving the plot
are supported: eps, jpeg, jpg, pdf, pgf, png, ps, raw, rgba, svg,
svgz, tif, tiff
:param ds: Dataset that contains the variable named by *var*.
:param var: The name of the variable to plot
:param indexers: Optional indexers into data array of *var*. The *indexers* is a dictionary
or a comma-separated string of key-value pairs that maps the variable's dimension names
to constant labels. e.g. "lon=12.6, layer=3, time='2012-05-02'".
:param title: an optional title
:param properties: optional histogram plot properties for Python matplotlib,
e.g. "bins=512, range=(-1.5, +1.5), label='Sea Surface Temperature'"
For full reference refer to
https://matplotlib.org/devdocs/api/_as_gen/matplotlib.pyplot.hist.html and
https://matplotlib.org/devdocs/api/_as_gen/matplotlib.patches.Patch.html#matplotlib.patches.Patch
:param file: path to a file in which to save the plot
:return: a matplotlib figure object or None if in IPython mode
"""
var_name = VarName.convert(var)
if not var_name:
raise ValidationError("Missing name for 'var'")
var = ds[var]
indexers = DictLike.convert(indexers)
properties = DictLike.convert(properties) or {}
figure = plt.figure(figsize=(8, 4))
ax = figure.add_subplot(111)
figure.tight_layout()
var_data = get_var_data(var, indexers)
var_data.plot.hist(ax=ax, **properties)
if title:
ax.set_title(title)
figure.tight_layout()
if file:
figure.savefig(file)
return figure if not in_notebook() else None
def plot_contour(ds: xr.Dataset,
var: VarName.TYPE,
indexers: DictLike.TYPE = None,
title: str = None,
filled: bool = True,
properties: DictLike.TYPE = None,
file: str = None) -> Figure:
"""
Create a contour plot of a variable given by dataset *ds* and variable name *var*.
:param ds: the dataset containing the variable to plot
:param var: the variable's name
:param indexers: Optional indexers into data array of *var*. The *indexers* is a dictionary
or a comma-separated string of key-value pairs that maps the variable's dimension names
to constant labels. e.g. "layer=4".
:param title: an optional title
:param filled: whether the regions between two contours shall be filled
:param properties: optional plot properties for Python matplotlib,
e.g. "bins=512, range=(-1.5, +1.5), label='Sea Surface Temperature'"
For full reference refer to
https://matplotlib.org/api/lines_api.html and
https://matplotlib.org/devdocs/api/_as_gen/matplotlib.patches.Patch.html#matplotlib.patches.Patch
:param file: path to a file in which to save the plot
:return: a matplotlib figure object or None if in IPython mode
"""
var_name = VarName.convert(var)
if not var_name:
raise ValidationError("Missing name for 'var'")
var = ds[var_name]
indexers = DictLike.convert(indexers) or {}
properties = DictLike.convert(properties) or {}
figure = plt.figure(figsize=(8, 4))
ax = figure.add_subplot(111)
var_data = get_var_data(var, indexers)
if filled:
var_data.plot.contourf(ax=ax, **properties)
else:
var_data.plot.contour(ax=ax, **properties)
if title:
ax.set_title(title)
figure.tight_layout()
if file:
figure.savefig(file)
return figure if not in_notebook() else None
def run(value):
ax.clear()
if extents:
ax.set_extent(extents, ccrs.PlateCarree())
else:
ax.set_global()
ax.coastlines()
indexers[animate_dim] = value
var_data = get_var_data(var, indexers, remaining_dims=('lon', 'lat'))
var_data.plot.contourf(ax=ax, transform=ccrs.PlateCarree(), subplot_kws={'projection': proj},
add_colorbar=False, **plot_kwargs)
if title:
ax.set_title(title)
monitor.progress(1)
return ax
def plot(ds: DatasetLike.TYPE,
var: VarName.TYPE,
indexers: DictLike.TYPE = None,
title: str = None,
properties: DictLike.TYPE = None,
file: str = None) -> Figure:
"""
Create a 1D/line or 2D/image plot of a variable given by dataset *ds* and variable name *var*.
:param ds: Dataset or Dataframe that contains the variable named by *var*.
:param var: The name of the variable to plot
:param indexers: Optional indexers into data array of *var*. The *indexers* is a dictionary
or a comma-separated string of key-value pairs that maps the variable's dimension names
to constant labels. e.g. "lat=12.4, time='2012-05-02'".
:param title: an optional plot title
:param properties: optional plot properties for Python matplotlib,
e.g. "bins=512, range=(-1.5, +1.5), label='Sea Surface Temperature'"
For full reference refer to
https://matplotlib.org/api/lines_api.html and
https://matplotlib.org/devdocs/api/_as_gen/matplotlib.patches.Patch.html#matplotlib.patches.Patch
:param file: path to a file in which to save the plot
:return: a matplotlib figure object or None if in IPython mode
"""
ds = DatasetLike.convert(ds)
var_name = VarName.convert(var)
if not var_name:
raise ValidationError("Missing name for 'var'")
var = ds[var_name]
indexers = DictLike.convert(indexers)
properties = DictLike.convert(properties) or {}
figure = plt.figure()
ax = figure.add_subplot(111)
var_data = get_var_data(var, indexers)
var_data.plot(ax=ax, **properties)
if title:
ax.set_title(title)
figure.tight_layout()
if file:
figure.savefig(file)
return figure if not in_notebook() else None
def animate_map(ds: xr.Dataset,
var: VarName.TYPE = None,
animate_dim: str = 'time',
interval: int = 200,
true_range: bool = False,
indexers: DictLike.TYPE = None,
region: PolygonLike.TYPE = None,
projection: str = 'PlateCarree',
central_lon: float = 0.0,
title: str = None,
contour_plot: bool = False,
cmap_params: DictLike.TYPE = None,
plot_properties: DictLike.TYPE = None,
file: str = None,
monitor: Monitor = Monitor.NONE) -> HTML:
"""
Create a geographic map animation for the variable given by dataset *ds* and variable name *var*.
Creates an animation of the given variable from the given dataset on a map with coastal lines.
In case no variable name is given, the first encountered variable in the
dataset is animated.
It is also possible to set extents of the animation. If no extents
are given, a global animation is created.
The following file formats for saving the animation are supported: html
:param ds: the dataset containing the variable to animate
:param var: the variable's name
:param animate_dim: Dimension to animate, if none given defaults to time.
:param interval: Delay between frames in milliseconds. Defaults to 200.
:param true_range: If True, calculates colormap and colorbar configuration parameters from the
whole dataset. Can potentially take a lot of time. Defaults to False, in which case the colormap
is calculated from the first frame.
:param indexers: Optional indexers into data array of *var*. The *indexers* is a dictionary
or a comma-separated string of key-value pairs that maps the variable's dimension names
to constant labels. e.g. "layer=4".
:param region: Region to animate
:param projection: name of a global projection, see http://scitools.org.uk/cartopy/docs/v0.15/crs/projections.html
:param central_lon: central longitude of the projection in degrees
:param title: an optional title
:param contour_plot: If true plot a filled contour plot of data, otherwise plots a pixelated colormesh
:param cmap_params: optional additional colormap configuration parameters,
e.g. "vmax=300, cmap='magma'"
For full reference refer to
http://xarray.pydata.org/en/stable/generated/xarray.plot.contourf.html
:param plot_properties: optional plot properties for Python matplotlib,
e.g. "bins=512, range=(-1.5, +1.5)"
For full reference refer to
https://matplotlib.org/api/lines_api.html and
https://matplotlib.org/api/_as_gen/matplotlib.axes.Axes.contourf.html
:param file: path to a file in which to save the animation
:param monitor: A progress monitor.
:return: An animation in HTML format
"""
if not isinstance(ds, xr.Dataset):
raise NotImplementedError('Only gridded datasets are currently supported')
var_name = None
if not var:
for key in ds.data_vars.keys():
var_name = key
break
else:
var_name = VarName.convert(var)
try:
var = ds[var_name]
except KeyError:
raise ValidationError('Provided variable name "{}" does not exist in the given dataset'.format(var_name))
indexers = DictLike.convert(indexers) or {}
properties = DictLike.convert(plot_properties) or {}
cmap_params = DictLike.convert(cmap_params) or {}
extents = None
bounds = handle_plot_polygon(region)
if bounds:
lon_min, lat_min, lon_max, lat_max = bounds
extents = [lon_min, lon_max, lat_min, lat_max]
if len(ds.lat) < 2 or len(ds.lon) < 2:
# Matplotlib can not plot datasets with less than these dimensions with
# contourf and pcolormesh methods
raise ValidationError('The minimum dataset spatial dimensions to create a map'
' plot are (2,2)')
# See http://scitools.org.uk/cartopy/docs/v0.15/crs/projections.html#
if projection == 'PlateCarree':
proj = ccrs.PlateCarree(central_longitude=central_lon)
elif projection == 'LambertCylindrical':
proj = ccrs.LambertCylindrical(central_longitude=central_lon)
elif projection == 'Mercator':
proj = ccrs.Mercator(central_longitude=central_lon)
elif projection == 'Miller':
proj = ccrs.Miller(central_longitude=central_lon)
elif projection == 'Mollweide':
proj = ccrs.Mollweide(central_longitude=central_lon)
elif projection == 'Orthographic':
proj = ccrs.Orthographic(central_longitude=central_lon)
elif projection == 'Robinson':
proj = ccrs.Robinson(central_longitude=central_lon)
elif projection == 'Sinusoidal':
proj = ccrs.Sinusoidal(central_longitude=central_lon)
elif projection == 'NorthPolarStereo':
proj = ccrs.NorthPolarStereo(central_longitude=central_lon)
elif projection == 'SouthPolarStereo':
proj = ccrs.SouthPolarStereo(central_longitude=central_lon)
else:
raise ValidationError('illegal projection: "%s"' % projection)
figure = plt.figure(figsize=(8, 4))
ax = plt.axes(projection=proj)
if extents:
ax.set_extent(extents, ccrs.PlateCarree())
else:
ax.set_global()
ax.coastlines()
if not animate_dim:
animate_dim = 'time'
indexers[animate_dim] = var[animate_dim][0]
var_data = get_var_data(var, indexers, remaining_dims=('lon', 'lat'))
with monitor.starting("animate", len(var[animate_dim]) + 3):
if true_range:
data_min, data_max = _get_min_max(var, monitor=monitor)
else:
data_min, data_max = _get_min_max(var_data, monitor=monitor)
cmap_params = determine_cmap_params(data_min, data_max, **cmap_params)
plot_kwargs = {**properties, **cmap_params}
# Plot the first frame to set-up the axes with the colorbar properly
# transform keyword is for the coordinate our data is in, which in case of a
# 'normal' lat/lon dataset is PlateCarree.
if contour_plot:
var_data.plot.contourf(ax=ax, transform=ccrs.PlateCarree(), subplot_kws={'projection': proj},
add_colorbar=True, **plot_kwargs)
else:
var_data.plot.pcolormesh(ax=ax, transform=ccrs.PlateCarree(), subplot_kws={'projection': proj},
add_colorbar=True, **plot_kwargs)
if title:
ax.set_title(title)
figure.tight_layout()
monitor.progress(1)
def run(value):
ax.clear()
if extents:
ax.set_extent(extents, ccrs.PlateCarree())
else:
ax.set_global()
ax.coastlines()
indexers[animate_dim] = value
var_data = get_var_data(var, indexers, remaining_dims=('lon', 'lat'))
var_data.plot.contourf(ax=ax, transform=ccrs.PlateCarree(), subplot_kws={'projection': proj},
add_colorbar=False, **plot_kwargs)
if title:
ax.set_title(title)
monitor.progress(1)
return ax
anim = animation.FuncAnimation(figure, run, [i for i in var[animate_dim]],
interval=interval, blit=False, repeat=False)
anim_html = anim.to_jshtml()
# Prevent the animation for running after it's finished
del anim
# Delete the rogue temp-file
try:
os.remove('None0000000.png')
except FileNotFoundError:
pass
if file:
with open(file, 'w') as outfile:
outfile.write(anim_html)
monitor.progress(1)
return HTML(anim_html)
def test_nominal(self):
"""
Nominal test
"""
dataset = xr.Dataset({
'first': (['lat', 'lon', 'time'], np.random.rand(5, 10, 2)),
'second': (['lat', 'lon', 'time'], np.random.rand(5, 10, 2)),
'lat': np.linspace(-89.5, 89.5, 5),
'lon': np.linspace(-179.5, 179.5, 10),
'time': pd.date_range('2000-01-01', periods=2)})
indexers = {'time': '2000-01-01', 'lat': -88}
out = get_var_data(dataset.second, indexers, remaining_dims=['lon', ])
self.assertEqual(out.time, np.datetime64('2000-01-01'))
self.assertEqual(out.lat, -89.5)
self.assertEqual(len(out.lon.values), 10)
# test on data with more dims
dataset2 = xr.Dataset({
'first': (['lat', 'lon', 'layers', 'time'], np.random.rand(5, 10, 16, 2)),
'second': (['lat', 'lon', 'layers', 'time'], np.random.rand(5, 10, 16, 2)),
'lat': np.linspace(-89.5, 89.5, 5),
'lon': np.linspace(-179.5, 179.5, 10),
'layers': np.linspace(1, 16, 16),
'time': pd.date_range('2000-01-01', periods=2)})
indexers = {'lat': 0, 'lon': -179.5, 'layers': 5}
out = get_var_data(dataset2.second, indexers, remaining_dims=['time', ])
self.assertEqual(out.lat, 0)
self.assertEqual(out.lon, -179.5)
self.assertEqual(out.layers, 5)
self.assertEqual(len(out.time.values), 2)
# test when a dimension is neither in indexers nor remaining_dims specified,
# it will select the first element of that dimension (if remaining_dims is specified)
indexers = {'lat': 0, 'lon': -179.5}
out = get_var_data(dataset2.second, indexers, remaining_dims=['time', ])
self.assertEqual(out.lat, 0)
self.assertEqual(out.lon, -179.5)
self.assertEqual(out.layers, 1)
self.assertEqual(len(out.time.values), 2)
# when remaining_dims is not specified, it should only index based on the given indexers
indexers = {'lat': 0, 'lon': -179.5}
out = get_var_data(dataset2.second, indexers)
self.assertEqual(out.lat, 0)
self.assertEqual(out.lon, -179.5)
self.assertEqual(len(out.layers), 16)
self.assertEqual(len(out.time.values), 2)
# should raise a ValidationError when the specified dimension is not part of variable dimension names
indexers = {'lat': 0, 'lon': -179.5, 'time': '2000-01-01'}
with self.assertRaises(ValidationError) as cm:
get_var_data(dataset2.second, indexers, remaining_dims=['dummy', ])
self.assertEqual(str(cm.exception), "The specified dataset does not have a dimension called \'dummy\'.")
# should raise a ValidationError when a dimension is specified as both indexers and remaining_dims
indexers = {'lat': 0, 'lon': -179.5, 'time': '2000-01-01'}
with self.assertRaises(ValidationError) as cm:
get_var_data(dataset2.second, indexers, remaining_dims=['time', ])
self.assertEqual(str(cm.exception), "Dimension 'time' is also specified as indexers. Please ensure that a "
"dimension is used exclusively either as indexers or as the selected "
"dimension.")
# should raise a ValidationError when a dimension is specified as indexers does not exist in the given variable
indexers = {'lat': 0, 'lon': -179.5, 'dummy': 1}
with self.assertRaises(ValidationError) as cm:
get_var_data(dataset2.second, indexers, remaining_dims=['time', ])
self.assertEqual(str(cm.exception), "The specified dataset does not have a dimension called 'dummy'.")
def plot_map(ds: xr.Dataset,
var: VarName.TYPE = None,
indexers: DictLike.TYPE = None,
region: PolygonLike.TYPE = None,
projection: str = 'PlateCarree',
central_lon: float = 0.0,
title: str = None,
contour_plot: bool = False,
properties: DictLike.TYPE = None,
file: str = None) -> object:
"""
Create a geographic map plot for the variable given by dataset *ds* and variable name *var*.
Plots the given variable from the given dataset on a map with coastal lines.
In case no variable name is given, the first encountered variable in the
dataset is plotted. In case no *time* is given, the first time slice
is taken. It is also possible to set extents of the plot. If no extents
are given, a global plot is created.
The plot can either be shown using pyplot functionality, or saved,
if a path is given. The following file formats for saving the plot
are supported: eps, jpeg, jpg, pdf, pgf, png, ps, raw, rgba, svg,
svgz, tif, tiff
:param ds: the dataset containing the variable to plot
:param var: the variable's name
:param indexers: Optional indexers into data array of *var*. The *indexers* is a dictionary
or a comma-separated string of key-value pairs that maps the variable's dimension names
to constant labels. e.g. "layer=4".
:param region: Region to plot
:param projection: name of a global projection, see http://scitools.org.uk/cartopy/docs/v0.15/crs/projections.html
:param central_lon: central longitude of the projection in degrees
:param title: an optional title
:param contour_plot: If true plot a filled contour plot of data, otherwise plots a pixelated colormesh
:param properties: optional plot properties for Python matplotlib,
e.g. "bins=512, range=(-1.5, +1.5)"
For full reference refer to
https://matplotlib.org/api/lines_api.html and
https://matplotlib.org/api/_as_gen/matplotlib.axes.Axes.contourf.html
:param file: path to a file in which to save the plot
:return: a matplotlib figure object or None if in IPython mode
"""
if not isinstance(ds, xr.Dataset):
raise ValidationError('Only gridded datasets are currently supported.')
var_name = None
if not var:
for key in ds.data_vars.keys():
var_name = key
break
else:
var_name = VarName.convert(var)
var = ds[var_name]
indexers = DictLike.convert(indexers) or {}
properties = DictLike.convert(properties) or {}
extents = None
bounds = handle_plot_polygon(region)
if bounds:
lon_min, lat_min, lon_max, lat_max = bounds
extents = [lon_min, lon_max, lat_min, lat_max]
if len(ds.lat) < 2 or len(ds.lon) < 2:
# Matplotlib can not plot datasets with less than these dimensions with
# contourf and pcolormesh methods
raise ValidationError('The minimum dataset spatial dimensions to create a map'
' plot are (2,2)')
# See http://scitools.org.uk/cartopy/docs/v0.15/crs/projections.html#
if projection == 'PlateCarree':
proj = ccrs.PlateCarree(central_longitude=central_lon)
elif projection == 'LambertCylindrical':
proj = ccrs.LambertCylindrical(central_longitude=central_lon)
elif projection == 'Mercator':
proj = ccrs.Mercator(central_longitude=central_lon)
elif projection == 'Miller':
proj = ccrs.Miller(central_longitude=central_lon)
elif projection == 'Mollweide':
proj = ccrs.Mollweide(central_longitude=central_lon)
elif projection == 'Orthographic':
proj = ccrs.Orthographic(central_longitude=central_lon)
elif projection == 'Robinson':
proj = ccrs.Robinson(central_longitude=central_lon)
elif projection == 'Sinusoidal':
proj = ccrs.Sinusoidal(central_longitude=central_lon)
elif projection == 'NorthPolarStereo':
proj = ccrs.NorthPolarStereo(central_longitude=central_lon)
elif projection == 'SouthPolarStereo':
proj = ccrs.SouthPolarStereo(central_longitude=central_lon)
else:
raise ValidationError('illegal projection: "%s"' % projection)
figure = plt.figure(figsize=(8, 4))
ax = plt.axes(projection=proj)
if extents:
ax.set_extent(extents, ccrs.PlateCarree())
else:
ax.set_global()
ax.coastlines()
var_data = get_var_data(var, indexers, remaining_dims=('lon', 'lat'))
# transform keyword is for the coordinate our data is in, which in case of a
# 'normal' lat/lon dataset is PlateCarree.
if contour_plot:
var_data.plot.contourf(ax=ax, transform=ccrs.PlateCarree(), subplot_kws={'projection': proj}, **properties)
else:
var_data.plot.pcolormesh(ax=ax, transform=ccrs.PlateCarree(), subplot_kws={'projection': proj}, **properties)
if title:
ax.set_title(title)
figure.tight_layout()
if file:
try:
figure.savefig(file)
except MemoryError:
raise MemoryError('Not enough memory to save the plot. Try using a different file format'
' or enabling contour_plot.')
return figure if not in_notebook() else ax
def plot_map(ds: xr.Dataset,
var: VarName.TYPE = None,
indexers: DictLike.TYPE = None,
region: PolygonLike.TYPE = None,
projection: str = 'PlateCarree',
central_lon: float = 0.0,
title: str = None,
contour_plot: bool = False,
properties: DictLike.TYPE = None,
file: str = None) -> object:
"""
Create a geographic map plot for the variable given by dataset *ds* and variable name *var*.
Plots the given variable from the given dataset on a map with coastal lines.
In case no variable name is given, the first encountered variable in the
dataset is plotted. In case no *time* is given, the first time slice
is taken. It is also possible to set extents of the plot. If no extents
are given, a global plot is created.
The plot can either be shown using pyplot functionality, or saved,
if a path is given. The following file formats for saving the plot
are supported: eps, jpeg, jpg, pdf, pgf, png, ps, raw, rgba, svg,
svgz, tif, tiff
:param ds: the dataset containing the variable to plot
:param var: the variable's name
:param indexers: Optional indexers into data array of *var*. The *indexers* is a dictionary
or a comma-separated string of key-value pairs that maps the variable's dimension names
to constant labels. e.g. "layer=4".
:param region: Region to plot
:param projection: name of a global projection, see http://scitools.org.uk/cartopy/docs/v0.15/crs/projections.html
:param central_lon: central longitude of the projection in degrees
:param title: an optional title
:param contour_plot: If true plot a filled contour plot of data, otherwise plots a pixelated colormesh
:param properties: optional plot properties for Python matplotlib,
e.g. "bins=512, range=(-1.5, +1.5)"
For full reference refer to
https://matplotlib.org/api/lines_api.html and
https://matplotlib.org/api/_as_gen/matplotlib.axes.Axes.contourf.html
:param file: path to a file in which to save the plot
:return: a matplotlib figure object or None if in IPython mode
"""
if not isinstance(ds, xr.Dataset):
raise ValidationError('Only gridded datasets are currently supported.')
var_name = None
if not var:
for key in ds.data_vars.keys():
var_name = key
break
else:
var_name = VarName.convert(var)
var = ds[var_name]
indexers = DictLike.convert(indexers) or {}
properties = DictLike.convert(properties) or {}
extents = None
bounds = handle_plot_polygon(region)
if bounds:
lon_min, lat_min, lon_max, lat_max = bounds
extents = [lon_min, lon_max, lat_min, lat_max]
if len(ds.lat) < 2 or len(ds.lon) < 2:
# Matplotlib can not plot datasets with less than these dimensions with
# contourf and pcolormesh methods
raise ValidationError(
'The minimum dataset spatial dimensions to create a map'
' plot are (2,2)')
# See http://scitools.org.uk/cartopy/docs/v0.15/crs/projections.html#
if projection == 'PlateCarree':
proj = ccrs.PlateCarree(central_longitude=central_lon)
elif projection == 'LambertCylindrical':
proj = ccrs.LambertCylindrical(central_longitude=central_lon)
elif projection == 'Mercator':
proj = ccrs.Mercator(central_longitude=central_lon)
elif projection == 'Miller':
proj = ccrs.Miller(central_longitude=central_lon)
elif projection == 'Mollweide':
proj = ccrs.Mollweide(central_longitude=central_lon)
elif projection == 'Orthographic':
proj = ccrs.Orthographic(central_longitude=central_lon)
elif projection == 'Robinson':
proj = ccrs.Robinson(central_longitude=central_lon)
elif projection == 'Sinusoidal':
proj = ccrs.Sinusoidal(central_longitude=central_lon)
elif projection == 'NorthPolarStereo':
proj = ccrs.NorthPolarStereo(central_longitude=central_lon)
elif projection == 'SouthPolarStereo':
proj = ccrs.SouthPolarStereo(central_longitude=central_lon)
else:
raise ValidationError('illegal projection: "%s"' % projection)
figure = plt.figure(figsize=(8, 4))
ax = plt.axes(projection=proj)
if extents:
ax.set_extent(extents, ccrs.PlateCarree())
else:
ax.set_global()
ax.coastlines()
var_data = get_var_data(var, indexers, remaining_dims=('lon', 'lat'))
# transform keyword is for the coordinate our data is in, which in case of a
# 'normal' lat/lon dataset is PlateCarree.
if contour_plot:
var_data.plot.contourf(ax=ax,
transform=ccrs.PlateCarree(),
subplot_kws={'projection': proj},
**properties)
else:
var_data.plot.pcolormesh(ax=ax,
transform=ccrs.PlateCarree(),
subplot_kws={'projection': proj},
**properties)
if title:
ax.set_title(title)
figure.tight_layout()
if file:
try:
figure.savefig(file)
except MemoryError:
raise MemoryError(
'Not enough memory to save the plot. Try using a different file format'
' or enabling contour_plot.')
return figure if not in_notebook() else ax
def test_nominal(self):
"""
Nominal test
"""
dataset = xr.Dataset({
'first': (['lat', 'lon', 'time'], np.random.rand(5, 10, 2)),
'second': (['lat', 'lon', 'time'], np.random.rand(5, 10, 2)),
'lat':
np.linspace(-89.5, 89.5, 5),
'lon':
np.linspace(-179.5, 179.5, 10),
'time':
pd.date_range('2000-01-01', periods=2)
})
indexers = {'time': '2000-01-01', 'lat': -88}
out = get_var_data(dataset.second, indexers, remaining_dims=[
'lon',
])
self.assertEqual(out.time, np.datetime64('2000-01-01'))
self.assertEqual(out.lat, -89.5)
self.assertEqual(len(out.lon.values), 10)
# test on data with more dims
dataset2 = xr.Dataset({
'first': (['lat', 'lon', 'layers',
'time'], np.random.rand(5, 10, 16, 2)),
'second': (['lat', 'lon', 'layers',
'time'], np.random.rand(5, 10, 16, 2)),
'lat':
np.linspace(-89.5, 89.5, 5),
'lon':
np.linspace(-179.5, 179.5, 10),
'layers':
np.linspace(1, 16, 16),
'time':
pd.date_range('2000-01-01', periods=2)
})
indexers = {'lat': 0, 'lon': -179.5, 'layers': 5}
out = get_var_data(dataset2.second,
indexers,
remaining_dims=[
'time',
])
self.assertEqual(out.lat, 0)
self.assertEqual(out.lon, -179.5)
self.assertEqual(out.layers, 5)
self.assertEqual(len(out.time.values), 2)
# test when a dimension is neither in indexers nor remaining_dims specified,
# it will select the first element of that dimension (if remaining_dims is specified)
indexers = {'lat': 0, 'lon': -179.5}
out = get_var_data(dataset2.second,
indexers,
remaining_dims=[
'time',
])
self.assertEqual(out.lat, 0)
self.assertEqual(out.lon, -179.5)
self.assertEqual(out.layers, 1)
self.assertEqual(len(out.time.values), 2)
# when remaining_dims is not specified, it should only index based on the given indexers
indexers = {'lat': 0, 'lon': -179.5}
out = get_var_data(dataset2.second, indexers)
self.assertEqual(out.lat, 0)
self.assertEqual(out.lon, -179.5)
self.assertEqual(len(out.layers), 16)
self.assertEqual(len(out.time.values), 2)
# should raise a ValidationError when the specified dimension is not part of variable dimension names
indexers = {'lat': 0, 'lon': -179.5, 'time': '2000-01-01'}
with self.assertRaises(ValidationError) as cm:
get_var_data(dataset2.second, indexers, remaining_dims=[
'dummy',
])
self.assertEqual(
str(cm.exception),
"The specified dataset does not have a dimension called \'dummy\'."
)
# should raise a ValidationError when a dimension is specified as both indexers and remaining_dims
indexers = {'lat': 0, 'lon': -179.5, 'time': '2000-01-01'}
with self.assertRaises(ValidationError) as cm:
get_var_data(dataset2.second, indexers, remaining_dims=[
'time',
])
self.assertEqual(
str(cm.exception),
"Dimension 'time' is also specified as indexers. Please ensure that a "
"dimension is used exclusively either as indexers or as the selected "
"dimension.")
# should raise a ValidationError when a dimension is specified as indexers does not exist in the given variable
indexers = {'lat': 0, 'lon': -179.5, 'dummy': 1}
with self.assertRaises(ValidationError) as cm:
get_var_data(dataset2.second, indexers, remaining_dims=[
'time',
])
self.assertEqual(
str(cm.exception),
"The specified dataset does not have a dimension called 'dummy'.")