Repository navigation
Expand file tree
/
Copy pathproject.py
More file actions
executable file
·2479 lines (2134 loc) · 89.9 KB
/
Copy pathproject.py
File metadata and controls
executable file
·2479 lines (2134 loc) · 89.9 KB
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
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
"""Project module of the psyplot Package
This module contains the :class:`Project` class that serves as the main
part of the psyplot API. One instance of the :class:`Project` class serves as
coordinator of multiple plots and can be distributed into subprojects that
keep reference to the main project without holding all array instances
Furthermore this module contains an easy pyplot-like API to the current
subproject."""
import os
import sys
import six
from copy import deepcopy as _deepcopy
import logging
import inspect
import pickle
from importlib import import_module
from itertools import chain, repeat, cycle, count, islice
from collections import Iterable, defaultdict
from functools import wraps, partial
import xarray
import pandas as pd
import matplotlib as mpl
import matplotlib.figure as mfig
import numpy as np
import psyplot
from psyplot import rcParams, get_versions
import psyplot.utils as utils
from psyplot.warning import warn, critical
from psyplot.docstring import docstrings, dedent, safe_modulo
import psyplot.data as psyd
from psyplot.data import (
ArrayList, open_dataset, open_mfdataset, _MissingModule,
to_netcdf, Signal, CFDecoder, safe_list, InteractiveList)
from psyplot.plotter import unique_everseen, Plotter
from psyplot.compat.pycompat import (OrderedDict, range, getcwd,
get_default_value as _get_default_value)
try:
from cdo import Cdo as _CdoBase
with_cdo = True
except ImportError as e:
Cdo = _MissingModule(e)
with_cdo = False
try: # try import show_colormaps for convenience
from psy_simple.colors import show_colormaps, get_cmap
except ImportError:
pass
if rcParams['project.import_seaborn'] is not False:
try:
import seaborn as _sns
except ImportError as e:
if rcParams['project.import_seaborn']:
raise
_sns = _MissingModule(e)
_open_projects = [] # list of open projects
_current_project = None # current main project
_current_subproject = None # current subproject
# the informations on the psyplot and plugin versions
_versions = get_versions(requirements=False)
_concat_dim_default = _get_default_value(xarray.open_mfdataset, 'concat_dim')
def _update_versions():
"""Update :attr:`_versions` with the registered plotter methods"""
for pm_name in plot._plot_methods:
pm = getattr(plot, pm_name)
plugin = pm._plugin
if (plugin is not None and plugin not in _versions and
pm.module in sys.modules):
_versions.update(get_versions(key=lambda s: s == plugin))
@docstrings.get_sectionsf('multiple_subplots')
@docstrings.dedent
def multiple_subplots(rows=1, cols=1, maxplots=None, n=1, delete=True,
for_maps=False, *args, **kwargs):
"""
Function to create subplots.
This function creates so many subplots on so many figures until the
specified number `n` is reached.
Parameters
----------
rows: int
The number of subplots per rows
cols: int
The number of subplots per column
maxplots: int
The number of subplots per figure (if None, it will be row*cols)
n: int
number of subplots to create
delete: bool
If True, the additional subplots per figure are deleted
for_maps: bool
If True this is a simple shortcut for setting
``subplot_kw=dict(projection=cartopy.crs.PlateCarree())`` and is
useful if you want to use the :attr:`~ProjectPlotter.mapplot`,
:attr:`~ProjectPlotter.mapvector` or
:attr:`~ProjectPlotter.mapcombined` plotting methods
``*args`` and ``**kwargs``
anything that is passed to the :func:`matplotlib.pyplot.subplots`
function
Returns
-------
list
list of maplotlib.axes.SubplotBase instances"""
import matplotlib.pyplot as plt
axes = np.array([])
maxplots = maxplots or rows * cols
kwargs.setdefault('figsize', [
min(8.*cols, 16), min(6.5*rows, 12)])
if for_maps:
import cartopy.crs as ccrs
subplot_kw = kwargs.setdefault('subplot_kw', {})
subplot_kw['projection'] = ccrs.PlateCarree()
for i in range(0, n, maxplots):
fig, ax = plt.subplots(rows, cols, *args, **kwargs)
try:
axes = np.append(axes, ax.ravel()[:maxplots])
if delete:
for iax in range(maxplots, rows * cols):
fig.delaxes(ax.ravel()[iax])
except AttributeError: # got a single subplot
axes = np.append(axes, [ax])
if i + maxplots > n and delete:
for ax2 in axes[n:]:
fig.delaxes(ax2)
axes = axes[:n]
return axes
def _is_slice(val):
return isinstance(val, slice)
def _only_main(func):
"""Call the given `func` only from the main project"""
@wraps(func)
def wrapper(self, *args, **kwargs):
if not self.is_main:
return getattr(self.main, func.__name__)(*args, **kwargs)
return func(self, *args, **kwargs)
return wrapper
def _first_main(func):
"""Call the given `func` with the same arguments but after the function
of the main project"""
@wraps(func)
def wrapper(self, *args, **kwargs):
if not self.is_main:
getattr(self.main, func.__name__)(*args, **kwargs)
return func(self, *args, **kwargs)
return wrapper
class Project(ArrayList):
"""A manager of multiple interactive data projects"""
_main = None
_registered_plotters = {} #: registered plotter identifiers
#: signal to be emiitted when the current main and/or subproject changes
oncpchange = Signal(name='oncpchange', cls_signal=True)
# block the signals of this class
block_signals = utils._TempBool()
@property
def main(self):
""":class:`Project`. The main project of this subproject"""
return self._main if self._main is not None else self
@main.setter
def main(self, value):
self._main = value
@property
@dedent
def plot(self):
"""
Plotting instance of this :class:`Project`. See the
:class:`ProjectPlotter` class for method documentations"""
return self._plot
@property
def _fmtos(self):
"""An iterator over formatoption objects
Contains only the formatoption whose keys are in all plotters in this
list"""
plotters = self.plotters
if len(plotters) == 0:
return {}
p0 = plotters[0]
if len(plotters) == 1:
return p0._fmtos
return (getattr(p0, key) for key in set(p0).intersection(
*map(set, plotters[1:])))
@property
def figs(self):
"""A mapping from figures to data objects with the plotter in this
figure"""
ret = utils.DefaultOrderedDict(lambda: self[1:0])
for arr in self:
if arr.psy.plotter is not None:
ret[arr.psy.plotter.ax.get_figure()].append(arr)
return OrderedDict(ret)
@property
def axes(self):
"""A mapping from axes to data objects with the plotter in this axes
"""
ret = utils.DefaultOrderedDict(lambda: self[1:0])
for arr in self:
if arr.psy.plotter is not None:
ret[arr.psy.plotter.ax].append(arr)
return OrderedDict(ret)
@property
def is_main(self):
""":class:`bool`. True if this :class:`Project` is a main project"""
return self._main is None
@property
def logger(self):
""":class:`logging.Logger` of this instance"""
if not self.is_main:
return self.main.logger
try:
return self._logger
except AttributeError:
name = '%s.%s.%s' % (self.__module__, self.__class__.__name__,
self.num)
self._logger = logging.getLogger(name)
self.logger.debug('Initializing...')
return self._logger
@logger.setter
def logger(self, value):
self._logger = value
def with_plotter(self):
ret = super(Project, self).with_plotter
ret.main = self.main
return ret
with_plotter = property(with_plotter, doc=ArrayList.with_plotter.__doc__)
@property
def arr_names(self):
"""Names of the arrays (!not of the variables!) in this list
This attribute can be set with an iterable of unique names to change
the array names of the data objects in this list."""
return list(arr.psy.arr_name for arr in self)
@arr_names.setter
def arr_names(self, value):
value = list(islice(value, len(self)))
if not len(set(value)) == len(self):
raise ValueError(
"Got %i unique array names for %i data objects!" % (
len(set(value)), len(self)))
elif not self.is_main and set(value) & (
set(self.main.arr_names) - set(self.arr_names)):
raise ValueError(
"Cannot rename arrays because there are duplicates with the "
"main project: %s" % (
set(value) & (
set(self.main.arr_names) - set(self.arr_names)), ))
for arr, n in zip(self, value):
arr.psy.arr_name = n
if self.main is gcp(True):
for arr in self:
arr.psy.onupdate.emit()
@property
def plotters(self):
"""A list of all the plotters in this instance"""
return [arr.psy.plotter for arr in self.with_plotter]
@property
def datasets(self):
"""A mapping from dataset numbers to datasets in this list"""
return {key: val['ds'] for key, val in six.iteritems(
self._get_ds_descriptions(self.array_info(ds_description=['ds'])))}
@property
def dsnames_map(self):
"""A dictionary from the dataset numbers in this list to their
filenames"""
return {key: val['fname'] for key, val in six.iteritems(
self._get_ds_descriptions(self.array_info(
ds_description=['num', 'fname']), ds_description={'fname'}))}
@property
def dsnames(self):
"""The set of dataset names in this instance"""
return {t[0] for t in self._get_dsnames(self.array_info()) if t[0]}
@docstrings.get_sectionsf('Project')
@docstrings.dedent
def __init__(self, *args, **kwargs):
"""
Parameters
----------
%(ArrayList.parameters)s
main: Project
The main project this subproject belongs to (or None if this
project is the main project)
num: int
The number of the project
"""
self.main = kwargs.pop('main', None)
self._plot = ProjectPlotter(self)
self.num = kwargs.pop('num', 1)
self._ds_counter = count()
with self.block_signals:
super(Project, self).__init__(*args, **kwargs)
@classmethod
@docstrings.get_sectionsf('Project._register_plotter')
@dedent
def _register_plotter(cls, identifier, module, plotter_name,
plotter_cls=None):
"""
Register a plotter in the :class:`Project` class to easy access it
Parameters
----------
identifier: str
Name of the attribute that is used to filter for the instances
belonging to this plotter
module: str
The module from where to import the `plotter_name`
plotter_name: str
The name of the plotter class in `module`
plotter_cls: type
The imported class of `plotter_name`. If None, it will be imported
when it is needed
"""
if plotter_cls is not None: # plotter has already been imported
def get_x(self):
return self(plotter_cls)
else:
def get_x(self):
return self(getattr(import_module(module), plotter_name))
setattr(cls, identifier, property(get_x, doc=(
"List of data arrays that are plotted by :class:`%s.%s`"
" plotters") % (module, plotter_name)))
cls._registered_plotters[identifier] = (module, plotter_name)
def disable(self):
"""Disables the plotters in this list"""
for arr in self:
if arr.psy.plotter:
arr.psy.plotter.disabled = True
def enable(self):
for arr in self:
if arr.psy.plotter:
arr.psy.plotter.disabled = False
def __call__(self, *args, **kwargs):
ret = super(Project, self).__call__(*args, **kwargs)
ret.main = self.main
return ret
@_first_main
def extend(self, *args, **kwargs):
len0 = len(self)
ret = super(Project, self).extend(*args, **kwargs)
if len(self) > len0 and (self is gcp() or self is gcp(True)):
self.oncpchange.emit(self)
return ret
extend.__doc__ = ArrayList.extend.__doc__
@_first_main
def append(self, *args, **kwargs):
len0 = len(self)
ret = super(Project, self).append(*args, **kwargs)
if len(self) > len0 and (self is gcp() or self is gcp(True)):
self.oncpchange.emit(self)
return ret
append.__doc__ = ArrayList.append.__doc__
__call__.__doc__ = ArrayList.__call__.__doc__
@docstrings.get_sectionsf('Project.close')
@dedent
def close(self, figs=True, data=False, ds=False, remove_only=False):
"""
Close this project instance
Parameters
----------
figs: bool
Close the figures
data: bool
delete the arrays from the (main) project
ds: bool
If True, close the dataset as well
remove_only: bool
If True and `figs` is True, the figures are not closed but the
plotters are removed"""
import matplotlib.pyplot as plt
close_ds = ds
for arr in self[:]:
if figs and arr.psy.plotter is not None:
if remove_only:
for fmto in arr.psy.plotter._fmtos:
try:
fmto.remove()
except Exception:
pass
else:
plt.close(arr.psy.plotter.ax.get_figure().number)
arr.psy.plotter = None
if data:
self.remove(arr)
if not self.is_main:
self.main.remove(arr)
if close_ds:
if isinstance(arr, InteractiveList):
for ds in [val['ds'] for val in six.itervalues(
arr._get_ds_descriptions(
arr.array_info(ds_description=['ds'],
standardize_dims=False)))]:
ds.close()
else:
arr.psy.base.close()
if self.is_main and self is gcp(True) and data:
scp(None)
elif self.is_main and self is gcp(True):
self.oncpchange.emit(self)
elif self.main is gcp(True):
self.oncpchange.emit(self.main)
docstrings.keep_params('multiple_subplots.parameters', 'delete')
docstrings.delete_params('ArrayList.from_dataset.parameters', 'base')
docstrings.delete_kwargs('ArrayList.from_dataset.other_parameters',
kwargs='kwargs')
docstrings.keep_params('xarray.open_mfdataset.parameters', 'concat_dim')
@_only_main
@docstrings.get_sectionsf('Project._add_data',
sections=['Parameters', 'Other Parameters',
'Returns'])
@docstrings.dedent
def _add_data(self, plotter_cls, filename_or_obj, fmt={}, make_plot=True,
draw=False, mf_mode=False, ax=None, engine=None, delete=True,
share=False, clear=False, enable_post=None,
concat_dim=_concat_dim_default,
*args, **kwargs):
"""
Extract data from a dataset and visualize it with the given plotter
Parameters
----------
plotter_cls: type
The subclass of :class:`psyplot.plotter.Plotter` to use for
visualization
filename_or_obj: filename, :class:`xarray.Dataset` or data store
The object (or file name) to open. If not a dataset, the
:func:`psyplot.data.open_dataset` will be used to open a dataset
fmt: dict
Formatoptions that shall be when initializing the plot (you can
however also specify them as extra keyword arguments)
make_plot: bool
If True, the data is plotted at the end. Otherwise you have to
call the :meth:`psyplot.plotter.Plotter.initialize_plot` method or
the :meth:`psyplot.plotter.Plotter.reinit` method by yourself
%(InteractiveBase.start_update.parameters.draw)s
mf_mode: bool
If True, the :func:`psyplot.open_mfdataset` method is used.
Otherwise we use the :func:`psyplot.open_dataset` method which can
open only one single dataset
ax: None, tuple (x, y[, z]) or (list of) matplotlib.axes.Axes
Specifies the subplots on which to plot the new data objects.
- If None, a new figure will be created for each created plotter
- If tuple (x, y[, z]), `x` specifies the number of rows, `y` the
number of columns and the optional third parameter `z` the
maximal number of subplots per figure.
- If :class:`matplotlib.axes.Axes` (or list of those, e.g. created
by the :func:`matplotlib.pyplot.subplots` function), the data
will be plotted on these subplots
%(open_dataset.parameters.engine)s
%(multiple_subplots.parameters.delete)s
share: bool, fmt key or list of fmt keys
Determines whether the first created plotter shares it's
formatoptions with the others. If True, all formatoptions are
shared. Strings or list of strings specify the keys to share.
clear: bool
If True, axes are cleared before making the plot. This is only
necessary if the `ax` keyword consists of subplots with projection
that differs from the one that is needed
enable_post: bool
If True, the :attr:`~psyplot.plotter.Plotter.post` formatoption is
enabled and post processing scripts are allowed. If ``None``, this
parameter is set to True if there is a value given for the `post`
formatoption in `fmt` or `kwargs`
%(xarray.open_mfdataset.parameters.concat_dim)s
This parameter only does have an effect if `mf_mode` is True.
%(ArrayList.from_dataset.parameters.no_base)s
Other Parameters
----------------
%(ArrayList.from_dataset.other_parameters.no_args_kwargs)s
``**kwargs``
Any other dimension or formatoption that shall be passed to `dims`
or `fmt` respectively.
Returns
-------
Project
The subproject that contains the new (visualized) data array"""
if not isinstance(filename_or_obj, xarray.Dataset):
if mf_mode:
filename_or_obj = open_mfdataset(filename_or_obj,
engine=engine,
concat_dim=concat_dim)
else:
filename_or_obj = open_dataset(filename_or_obj,
engine=engine)
fmt = dict(fmt)
possible_fmts = list(plotter_cls._get_formatoptions())
additional_fmt, kwargs = utils.sort_kwargs(
kwargs, possible_fmts)
fmt.update(additional_fmt)
if enable_post is None:
enable_post = bool(fmt.get('post'))
# create the subproject
sub_project = self.from_dataset(filename_or_obj, **kwargs)
sub_project.main = self
sub_project.no_auto_update = not (
not sub_project.no_auto_update or not self.no_auto_update)
# create the subplots
proj = plotter_cls._get_sample_projection()
if isinstance(ax, tuple):
axes = iter(multiple_subplots(
*ax, n=len(sub_project), subplot_kw={'projection': proj}))
elif ax is None or isinstance(ax, (mpl.axes.SubplotBase,
mpl.axes.Axes)):
axes = repeat(ax)
else:
axes = iter(ax)
clear = clear or (isinstance(ax, tuple) and proj is not None)
for arr in sub_project:
plotter_cls(arr, make_plot=(not bool(share) and make_plot),
draw=False, ax=next(axes), clear=clear,
project=self, enable_post=enable_post, **fmt)
if share:
if share is True:
share = possible_fmts
elif isinstance(share, six.string_types):
share = [share]
else:
share = list(share)
sub_project[0].psy.plotter.share(
[arr.psy.plotter for arr in sub_project[1:]], keys=share,
draw=False)
if make_plot:
for arr in sub_project:
arr.psy.plotter.reinit(draw=False, clear=clear)
if draw is None:
draw = rcParams['auto_draw']
if draw:
sub_project.draw()
if rcParams['auto_show']:
self.show()
self.extend(sub_project, new_name=True)
if self is gcp(True):
scp(sub_project)
return sub_project
def __getitem__(self, key):
"""Overwrites lists __getitem__ by returning subproject if `key` is a
slice"""
if isinstance(key, slice): # return a new project
ret = self.__class__(
super(Project, self).__getitem__(key))
ret.main = self.main
else: # return the item
ret = super(Project, self).__getitem__(key)
return ret
if six.PY2: # for compatibility to python 2.7
def __getslice__(self, *args):
return self[slice(*args)]
def __add__(self, other):
# overwritte to return a subproject
ret = self.__class__(super(Project, self).__add__(other))
ret.main = self.main
return ret
@staticmethod
def show():
"""Shows all open figures"""
import matplotlib.pyplot as plt
plt.show(block=False)
docstrings.keep_params('join_dicts.parameters', 'delimiter')
docstrings.keep_params('join_dicts.parameters', 'keep_all')
@docstrings.with_indent(8)
def joined_attrs(self, delimiter=', ', enhanced=True, plot_data=False,
keep_all=True):
"""Join the attributes of the arrays in this project
Parameters
----------
%(join_dicts.parameters.delimiter)s
enhanced: bool
If True, the :meth:`psyplot.plotter.Plotter.get_enhanced_attrs`
method is used, otherwise the :attr:`xarray.DataArray.attrs`
attribute is used.
plot_data: bool
It True, use the :attr:`psyplot.plotter.Plotter.plot_data`
attribute of the plotters rather than the raw data in this project
%(join_dicts.parameters.keep_all)s
Returns
-------
dict
A mapping from the attribute to the joined attributes which are
either strings or (if there is only one attribute value), the
data type of the corresponding value"""
if enhanced:
all_attrs = [
plotter.get_enhanced_attrs(
getattr(plotter, 'plot_data' if plot_data else 'data'))
for plotter in self.plotters]
else:
if plot_data:
all_attrs = [plotter.plot_data.attrs
for plotter in self.plotters]
else:
all_attrs = [arr.attrs for arr in self]
return utils.join_dicts(all_attrs, delimiter=delimiter,
keep_all=keep_all)
def export(self, output, tight=False, concat=True, close_pdf=None,
use_time=False, **kwargs):
"""Exports the figures of the project to one or more image files
Parameters
----------
output: str, iterable or matplotlib.backends.backend_pdf.PdfPages
if string or list of strings, those define the names of the output
files. Otherwise you may provide an instance of
:class:`matplotlib.backends.backend_pdf.PdfPages` to save the
figures in it.
If string (or iterable of strings), attribute names in the
xarray.DataArray.attrs attribute as well as index dimensions
are replaced by the respective value (see examples below).
Furthermore a single format string without key (e.g. %i, %s, %d,
etc.) is replaced by a counter.
tight: bool
If True, it is tried to figure out the tight bbox of the figure
(same as bbox_inches='tight')
concat: bool
if True and the output format is `pdf`, all figures are
concatenated into one single pdf
close_pdf: bool or None
If True and the figures are concatenated into one single pdf,
the resulting pdf instance is closed. If False it remains open.
If None and `output` is a string, it is the same as
``close_pdf=True``, if None and `output` is neither a string nor an
iterable, it is the same as ``close_pdf=False``
use_time: bool
If True, formatting strings for the
:meth:`datetime.datetime.strftime` are expected to be found in
`output` (e.g. ``'%m'``, ``'%Y'``, etc.). If so, other formatting
strings must be escaped by double ``'%'`` (e.g. ``'%%i'`` instead
of (``'%i'``))
``**kwargs``
Any valid keyword for the :func:`matplotlib.pyplot.savefig`
function
Returns
-------
matplotlib.backends.backend_pdf.PdfPages or None
a PdfPages instance if output is a string and close_pdf is False,
otherwise None
Examples
--------
Simply save all figures into one single pdf::
>>> p = psy.gcp()
>>> p.export('my_plots.pdf')
Save all figures into separate pngs with increasing numbers (e.g.
``'my_plots_1.png'``)::
>>> p.export('my_plots_%i.png')
Save all figures into separate pngs with the name of the variables
shown in each figure (e.g. ``'my_plots_t2m.png'``)::
>>> p.export('my_plots_%(name)s.png')
Save all figures into separate pngs with the name of the variables
shown in each figure and with increasing numbers (e.g.
``'my_plots_1_t2m.png'``)::
>>> p.export('my_plots_%i_%(name)s.png')
Specify the names for each figure directly via a list::
>>> p.export(['my_plots1.pdf', 'my_plots2.pdf'])
"""
from matplotlib.backends.backend_pdf import PdfPages
if tight:
kwargs['bbox_inches'] = 'tight'
if use_time:
def insert_time(s, attrs):
time = attrs[tname]
try: # assume a valid datetime.datetime instance
s = pd.to_datetime(time).strftime(s)
except ValueError:
pass
return s
tnames = self._get_tnames()
tname = next(iter(tnames)) if len(tnames) == 1 else None
else:
def insert_time(s, attrs):
return s
tname = None
if isinstance(output, six.string_types): # a single string
out_fmt = kwargs.pop('format', os.path.splitext(output))[1][1:]
if out_fmt.lower() == 'pdf' and concat:
attrs = self.joined_attrs('-')
if tname is not None and tname in attrs:
output = insert_time(output, attrs)
pdf = PdfPages(safe_modulo(output, attrs))
def save(fig):
pdf.savefig(fig, **kwargs)
def close():
if close_pdf is None or close_pdf:
pdf.close()
return
return pdf
else:
def save(fig):
attrs = self.figs[fig].joined_attrs('-')
out = output
if tname is not None and tname in attrs:
out = insert_time(out, attrs)
try:
out = safe_modulo(out, i, print_warning=False)
except TypeError:
pass
fig.savefig(safe_modulo(out, attrs), **kwargs)
def close():
pass
elif isinstance(output, Iterable): # a list of strings
output = cycle(output)
def save(fig):
attrs = self.figs[fig].joined_attrs('-')
out = next(output)
if tname is not None and tname in attrs:
out = insert_time(out, attrs)
try:
out = safe_modulo(next(output), i, print_warning=False)
except TypeError:
pass
fig.savefig(safe_modulo(out, attrs), **kwargs)
def close():
pass
else: # an instances of matplotlib.backends.backend_pdf.PdfPages
def save(fig):
output.savefig(fig, **kwargs)
def close():
if close_pdf:
output.close()
for i, fig in enumerate(self.figs, 1):
save(fig)
return close()
docstrings.keep_params('Plotter.share.parameters', 'keys')
docstrings.delete_params('Plotter.share.parameters', 'keys', 'plotters')
@docstrings.dedent
def share(self, base=None, keys=None, by=None, **kwargs):
"""
Share the formatoptions of one plotter with all the others
This method shares specified formatoptions from `base` with all the
plotters in this instance.
Parameters
----------
base: None, Plotter, xarray.DataArray, InteractiveList, or list of them
The source of the plotter that shares its formatoptions with the
others. It can be None (then the first instance in this project
is used), a :class:`~psyplot.plotter.Plotter` or any data object
with a *psy* attribute. If `by` is not None, then it is expected
that `base` is a list of data objects for each figure/axes
%(Plotter.share.parameters.keys)s
by: {'fig', 'figure', 'ax', 'axes'}
Share the formatoptions only with the others on the same
``'figure'`` or the same ``'axes'``. In this case, base must either
be ``None`` or a list of the types specified for `base`
%(Plotter.share.parameters.no_keys|plotters)s
See Also
--------
psyplot.plotter.share"""
if by is not None:
if base is not None:
if hasattr(base, 'psy') or isinstance(base, Plotter):
base = [base]
if by.lower() in ['ax', 'axes']:
bases = {ax: p[0] for ax, p in six.iteritems(
Project(base).axes)}
elif by.lower() in ['fig', 'figure']:
bases = {fig: p[0] for fig, p in six.iteritems(
Project(base).figs)}
else:
raise ValueError(
"*by* must be out of {'fig', 'figure', 'ax', 'axes'}. "
"Not %s" % (by, ))
else:
bases = {}
projects = self.axes if by == 'axes' else self.figs
for obj, p in projects.items():
p.share(bases.get(obj), keys, **kwargs)
else:
plotters = self.plotters
if not plotters:
return
if base is None:
if len(plotters) == 1:
return
base = plotters[0]
plotters = plotters[1:]
elif not isinstance(base, Plotter):
base = getattr(getattr(base, 'psy', base), 'plotter', base)
base.share(plotters, keys=keys, **kwargs)
@docstrings.dedent
def unshare(self, **kwargs):
"""
Unshare the formatoptions of all the plotters in this instance
This method uses the :meth:`psyplot.plotter.Plotter.unshare_me`
method to release the specified formatoptions in `keys`.
Parameters
----------
%(Plotter.unshare_me.parameters)s
See Also
--------
psyplot.plotter.Plotter.unshare, psyplot.plotter.Plotter.unshare_me"""
for plotter in self.plotters:
plotter.unshare_me(**kwargs)
docstrings.delete_params('ArrayList.array_info.parameters', 'pwd', 'copy')
@docstrings.get_sectionsf('Project.save_project')
@docstrings.dedent
def save_project(self, fname=None, pwd=None, pack=False, **kwargs):
"""
Save this project to a file
Parameters
----------
fname: str or None
If None, the dictionary will be returned. Otherwise the necessary
information to load this project via the :meth:`load` method is
saved to `fname` using the :mod:`pickle` module
pwd: str or None, optional
Path to the working directory from where the data can be imported.
If None and `fname` is the path to a file, `pwd` is set to the
directory of this file. Otherwise the current working directory is
used.
pack: bool
If True, all datasets are packed into the folder of `fname`
and will be used if the data is loaded
%(ArrayList.array_info.parameters.no_pwd|copy)s
Notes
-----
You can also store the entire data in the pickled file by setting
``ds_description={'ds'}``"""
# store the figure informatoptions and array informations
if fname is not None and pwd is None and not pack:
pwd = os.path.dirname(fname)
if pack and fname is not None:
target_dir = os.path.dirname(fname)
if not os.path.exists(target_dir):
os.makedirs(target_dir)
def tmp_it():
from tempfile import NamedTemporaryFile
while True:
yield NamedTemporaryFile(
dir=target_dir, suffix='.nc').name
kwargs.setdefault('paths', tmp_it())
if fname is not None:
kwargs['copy'] = True
_update_versions()
ret = {'figs': dict(map(_ProjectLoader.inspect_figure, self.figs)),
'arrays': self.array_info(pwd=pwd, **kwargs),
'versions': _deepcopy(_versions)}
if pack and fname is not None:
# we get the filenames out of the results and copy the datasets
# there. After that we check the filenames again and force them
# to the desired directory
from shutil import copyfile
fnames = (f[0] for f in self._get_dsnames(ret['arrays']))
alternative_paths = kwargs.pop('alternative_paths', {})
counters = defaultdict(int)
if kwargs.get('use_rel_paths', True):
get_path = partial(os.path.relpath, start=target_dir)
else:
get_path = os.path.abspath
for ds_fname in unique_everseen(chain(alternative_paths, fnames)):
if ds_fname is None or utils.is_remote_url(ds_fname):
continue
dst_file = alternative_paths.get(
ds_fname, os.path.join(target_dir, os.path.basename(
ds_fname)))
orig_dst_file = dst_file
if counters[dst_file] and (
not os.path.exists(dst_file) or
not os.path.samefile(ds_fname, dst_file)):
dst_file, ext = os.path.splitext(dst_file)
dst_file += '-' + str(counters[orig_dst_file]) + ext
if (not os.path.exists(dst_file) or
not os.path.samefile(ds_fname, dst_file)):
copyfile(ds_fname, dst_file)
counters[orig_dst_file] += 1
alternative_paths.setdefault(ds_fname, get_path(dst_file))
ret['arrays'] = self.array_info(
pwd=pwd, alternative_paths=alternative_paths, **kwargs)
# store the plotter settings
for arr, d in zip(self, six.itervalues(ret['arrays'])):
if arr.psy.plotter is None:
continue
plotter = arr.psy.plotter
d['plotter'] = {
'ax': _ProjectLoader.inspect_axes(plotter.ax),
'fmt': {key: getattr(plotter, key).value2pickle
for key in plotter},
'cls': (plotter.__class__.__module__,
plotter.__class__.__name__),
'shared': {}}
d['plotter']['ax']['shared'] = set(
other.psy.arr_name for other in self
if other.psy.ax == plotter.ax)
if plotter.ax._sharex:
d['plotter']['ax']['sharex'] = next(
(other.psy.arr_name for other in self
if other.psy.ax == plotter.ax._sharex), None)
if plotter.ax._sharey:
d['plotter']['ax']['sharey'] = next(
(other.psy.arr_name for other in self
if other.psy.ax == plotter.ax._sharey), None)
shared = d['plotter']['shared']
for fmto in plotter._fmtos:
if fmto.shared:
shared[fmto.key] = [other_fmto.plotter.data.psy.arr_name
for other_fmto in fmto.shared]
if fname is not None:
with open(fname, 'wb') as f:
pickle.dump(ret, f)
return None
return ret