Merge branch 'master' into develop

examples/README.rst

@@ -3,7 +3,7 @@ numbered examples aim to provide a tutorial of how the package in
 general works, while the rest show some more concrete examples you
 might find in published work.
 
-The data files provided are mostly from published work\ :sup`1`, which
+The data files provided are mostly from published work\ :sup:`1`, which
 looks at the effectiveness of four transparent conducting oxides (TCOs)
 as thermoelectrics. Using a pre-release version of this code, the main
 problem was found to be their large lattice thermal conductivities,

examples/heatmaps/README.rst

@@ -84,4 +84,8 @@ using an axes template with multiple sets of axes, the ``custom``
 argument must be used in ``add_legend`` to enable manual manipulation
 of the handles and labels. ``add_ztdiff`` and its power factor
 equivalent, ``add_pfdiff``, also make sure the colour scale is centred
-on zero (i.e. where both are equal).
+on zero (i.e. where both are equal).
+
+Some users may find adding contours with the ``contours`` argument or making
+the colour scale discrete with the ``discrete`` argument more legible or
+informative.

tp/cli/cli.py

@@ -956,16 +956,17 @@ def avg_rates(mesh_h5, mfp, total, x, crt, exclude, doping, direction,
         elif ymax is not None:
             ax.set_ylim(top=ymax)
 
-    if ymin is not None:
-        if ymax is not None:
-            for a in ax:
-                a.set_ylim(ymin, ymax)
-        else:
+    else:
+        if ymin is not None:
+            if ymax is not None:
+                for a in ax:
+                    a.set_ylim(ymin, ymax)
+            else:
+                for a in ax:
+                    a.set_ylim(bottom=ymin)
+        elif ymax is not None:
             for a in ax:
-                a.set_ylim(bottom=ymin)
-    elif ymax is not None:
-        for a in ax:
-            a.set_ylim(top=ymax)
+                a.set_ylim(top=ymax)
 
     if save:
         for ext in extension:
@@ -1434,12 +1435,14 @@ def kappa(kfile, efile, component, direction, tmin, tmax, dtype, doping,
               help='Colour for values below --cmin.',
               default='grey',
               show_default=True)
+@heatmap_options
 
 @axes_limit_function(c=True)
 @plot_io_function('tp-kappa-target')
 
 def kappa_target(transport_file, zt, direction, interpolate, kind, colour,
-                 negativecolour, xmin, xmax, ymin, ymax, cmin, cmax, style,
+                 negativecolour, discrete, levels, contours, contourcolours,
+                 xmin, xmax, ymin, ymax, cmin, cmax, style,
                  large, save, show, extension, output):
     """Plots lattice thermal conductivity to reach a target ZT.
 
@@ -1466,6 +1469,9 @@ def kappa_target(transport_file, zt, direction, interpolate, kind, colour,
                                             xinterp=interpolate,
                                             yinterp=interpolate,
                                             kind=kind, colour=colour,
+                                            discrete=discrete, levels=levels,
+                                            contours=contours,
+                                            contourcolours=contourcolours,
                                             negativecolour=negativecolour,
                                             xmin=xmin, xmax=xmax, ymin=ymin,
                                             ymax=ymax, cmin=cmin, cmax=cmax)
@@ -2220,11 +2226,13 @@ def wideband(band_yaml, kappa_hdf5, temperature, poscar, colour, smoothing, styl
               multiple=True,
               default=['viridis'],
               show_default=True)
+@heatmap_options
 
 @axes_limit_function(c=True)
 @plot_io_function('tp-ztmap')
 
-def ztmap(transport_file, pf, kappa, direction, dtype, interpolate, kind, colour,
+def ztmap(transport_file, pf, kappa, direction, dtype, interpolate, kind,
+          colour, discrete, levels, contours, contourcolours,
           xmin, xmax, ymin, ymax, cmin, cmax, style, large, save, show,
           extension, output):
     """Plots ZT or PF against temperature and carrier concentration."""
@@ -2243,7 +2251,9 @@ def ztmap(transport_file, pf, kappa, direction, dtype, interpolate, kind, colour
     if pf:
         tp.plot.heatmap.add_pfmap(ax, edata, direction=direction,
                                   xinterp=interpolate, yinterp=interpolate,
-                                  kind=kind, colour=colour, xmin=xmin,
+                                  kind=kind, colour=colour, discrete=discrete,
+                                  levels=levels, contours=contours,
+                                  contourcolours=contourcolours, xmin=xmin,
                                   xmax=xmax, ymin=ymin, ymax=ymax, cmin=cmin,
                                   cmax=cmax)
     else:
@@ -2254,7 +2264,9 @@ def ztmap(transport_file, pf, kappa, direction, dtype, interpolate, kind, colour
 
         tp.plot.heatmap.add_ztmap(ax, edata, kdata=kdata, direction=direction,
                                   xinterp=interpolate, yinterp=interpolate,
-                                  kind=kind, colour=colour, xmin=xmin,
+                                  kind=kind, colour=colour, discrete=discrete,
+                                  levels=levels, contours=contours,
+                                  contourcolours=contourcolours, xmin=xmin,
                                   xmax=xmax, ymin=ymin, ymax=ymax, cmin=cmin,
                                   cmax=cmax)
 
@@ -2293,15 +2305,16 @@ def ztmap(transport_file, pf, kappa, direction, dtype, interpolate, kind, colour
                    'colour recognised by matplotlib.',
               default='white',
               show_default=True)
+@heatmap_options
 
 @axes_limit_function(c=True)
 @legend_function()
 @plot_io_function('tp-ztdiff')
 
 def ztdiff(transport_files, pf, kappa, direction, dtype, interpolate, kind,
-           colour, midcolour, xmin, xmax, ymin, ymax, cmin, cmax, legend,
-           label, legend_title, location, style, large, save, show, extension,
-           output):
+           colour, midcolour, discrete, levels, contours, contourcolours,
+           xmin, xmax, ymin, ymax, cmin, cmax, legend, label, legend_title,
+           location, style, large, save, show, extension, output):
     """Plots ZT or PF difference against temperature and carrier concentration.
     
     Requires two input datasets. --kappa and --colour take exactly two values
@@ -2329,7 +2342,9 @@ def ztdiff(transport_files, pf, kappa, direction, dtype, interpolate, kind,
         _, h, l = tp.plot.heatmap.add_pfdiff(ax, *edata, direction=direction,
                    xinterp=interpolate, yinterp=interpolate, kind=kind,
                    colour1=colour[0], colour2=colour[1], midcolour=midcolour,
-                   label1=label[0], label2=label[1], xmin=xmin, xmax=xmax,
+                   label1=label[0], label2=label[1], discrete=discrete,
+                   levels=levels, contours=contours,
+                   contourcolours=contourcolours, xmin=xmin, xmax=xmax,
                    ymin=ymin, ymax=ymax, cmin=cmin, cmax=cmax)
     else:
         kdata = []
@@ -2344,12 +2359,14 @@ def ztdiff(transport_files, pf, kappa, direction, dtype, interpolate, kind,
                 except OSError:
                     raise Exception(
                                     "--kappa must be valid filepaths or floats.")
-        _, h, l = tp.plot.heatmap.add_ztdiff(ax, edata[0], edata[1], kdata1=kdata[0],
-                   kdata2=kdata[1], direction=direction, xinterp=interpolate,
-                   yinterp=interpolate, kind=kind, colour1=colour[0],
-                   colour2=colour[1], midcolour=midcolour, label1=label[0],
-                   label2=label[1], xmin=xmin, xmax=xmax, ymin=ymin,
-                   ymax=ymax, cmin=cmin, cmax=cmax)
+        _, h, l = tp.plot.heatmap.add_ztdiff(ax, edata[0], edata[1],
+                   kdata1=kdata[0], kdata2=kdata[1], direction=direction,
+                   xinterp=interpolate, yinterp=interpolate, kind=kind,
+                   colour1=colour[0], colour2=colour[1], midcolour=midcolour,
+                   label1=label[0], label2=label[1], discrete=discrete,
+                   levels=levels, contours=contours,
+                   contourcolours=contourcolours, xmin=xmin, xmax=xmax,
+                   ymin=ymin, ymax=ymax, cmin=cmin, cmax=cmax)
 
     if legend and label != [None, None]:
         if location is None:

tp/cli/options.py

@@ -147,6 +147,31 @@ def doping_option(f):
         return f
     return doping_option
 
+def heatmap_options(f):
+    """Options for heatmaps."""
+
+    f = click.option('--discrete/--continuous',
+                     help='Discretise colourmap.  [default: continuous]',
+                     default=False,
+                     show_default=False)(f)
+    f = click.option('-l', '--levels',
+                     help='Levels for discrete plots. Lists directly '
+                          'specify the contour levels, while integers '
+                          'specify the maximum-1 number of "nice" '
+                          'levels to plot.',
+                     multiple=True,
+                     default=None)(f)
+    f = click.option('--contours',
+                     help='Contours to plot.',
+                     multiple=True,
+                     type=float,
+                     default=None)(f)
+    f = click.option('--contourcolours',
+                     help='contour colours',
+                     multiple=True,
+                     default='black')(f)
+    return f
+
 def dos_function(dosargs=['-c', '--colour']):
     """Function for creating DoS options.
 

tp/data/load.py

@@ -159,9 +159,6 @@ def amset(filename, quantities='all', doping='n'):
         if q2 in dimensions:
             data2['meta']['dimensions'][q2] = dimensions[q2]
 
-    if 'doping' in data2:
-        data2['doping'] = np.array(data2['doping'])[di]
-
     for c in aconversions:
         if c in data2:
             data2[c] = np.multiply(data2[c], float(aconversions[c]))
@@ -404,9 +401,6 @@ def resolve_spin(data, q, spin):
             if q2 in dimensions:
                 data['meta']['dimensions'][q2] = dimensions[q2]
 
-    if 'doping' in data:
-        data['doping'] = np.array(data['doping'])[di]
-
     if 'stype' in data:
         data['stype'] = [l.decode('UTF-8') for l in data['stype']]
         data['stype'].append('Total')
@@ -896,8 +890,8 @@ def get_path(yamldata):
         ticks.append(yamldata['labels'][-1][1])
     except: # new phonopy/ sumo
         ticks = [yamldata['phonon'][i - 1]['label'] for i in tickindex]
-    ticks = ['$\mathregular{\Gamma}$' if i == 'G' or 'gamma' in i.lower() else
-             '$\mathregular{{{}}}$'.format(i.strip('$')) for i in ticks]
+    ticks = [r'$\mathregular{\Gamma}$' if i == 'G' or 'gamma' in i.lower() else
+             r'$\mathregular{{{}}}$'.format(i.strip('$')) for i in ticks]
 
     return tickpos, ticks
 

tp/plot/frequency.py

@@ -472,7 +472,7 @@ def add_cum_kappa(ax, data, temperature=300, direction='avg', label=None,
         marker = [marker]
     if label is None:
         if len(data) == 1 and len(direction) == 1:
-            label = ['$\mathregular{\kappa_l}$']
+            label = [r'$\mathregular{\kappa_l}$']
         else:
             label = direction
     elif isinstance(label, str):