.. _plotting: .. public Plotting Functions ################## Plotting functions commonly required for geostatistical work have been wrapped within pygeostat. While most are coded with the intention of being plug and play, they can be used as a starting point and altered to your needs. Please report any bugs, annoyances, or possible enhancements. Introduction to Plotting with pygeostat *************************************** The following section introduces some thoughts on plotting figures and utility functions. Figure Sizes ============ The CCG paper template margin allows for 6 inches of working width space, if two plots are to be put side by side, they would have to be no more than 3 inches. This is why many of the plotting functions have a default width of 3 inches. The UofA's minimum requirement for a thesis states that the left and right margins can not be less than 1 inch each. As the CCG paper template is the limiting factor, a maximum figure size of 3 inches is still a good guideline. Fonts ===== The CCG paper template uses Calibri, figure text should be the same. The minimum font size for CCG papers is 8 pt. The UofA's minimum requirement for a thesis allows the user to select their own fonts keeping readability in mind. If you are exporting postscript figures, some odd behavior may occur. Matplotlib needs to be instructed which type of fonts to export with them, this is handled by using :func:`gs.set_style() ` which is within many of the plotting functions. The font may also be called within the postscript file as a byte string, the function :func:`gs.exportimg() ` converts this into a working string. You may find that when saving to a PDF document, the font you select is appearing bold. This happens due to matplotlib using the same name for fonts within the same faimly. For example, if you specify ``mpl.rcParams['font.family'] = 'Times New Roman'`` the bold and regular font may have the same name causing the bold to be selected by default. A fix can be found `here `_. Selection of Colormaps and Colour Palettes ========================================== **Continuous Colormaps** While the selection of colormaps may appear to based on personal preference, there are many factors that must be accounted for when selecting a colormap. Will your figures be viewed by colour blind individuals? Will the figure possibly be printed in black and white? Is the colormap perceived by our minds as intended? See http://www.research.ibm.com/people/l/lloydt/color/color.HTM for a more in depth discussion on colormap theory. **Example** Which illustrates the most detail in the data? Spoiler: inferno does, in my opinion :) (Warren Black) Colour theory research has shown that the colormap jet may appear detailed due to the colour differential; however, our perception of the colours distort the data's representation. The blue-white-red colormap is diverging, therefore structure in the data is implied. Diverging colormaps should only be used if the underlying structure is understood and needs special representation. The inferno and viridis colormaps are sequential, are perceptually uniform, can be printed as black and white, and are accessible to colour blind viewers. Unfortunately, the inferno color map is some what jarring, therefore pygeostat's default colormap is viridis as it is more pleasing. Both are not available as of version 1.5.1 in matplotlib. For more info check out http://bids.github.io/colormap/ and http://matplotlib.org/style_changes.html .. image:: ./figures/colormaps.png **Digital Elevation Models** There are two custom colormaps available through pygeostat for visualizing digital elevation models. ``topo1`` and ``topo2`` are available through the :func:`gs.get_cmap() ` function. They won't look as pixelated as the examples below...I promise! ``topo1`` .. image:: ./figures/cmap_topo1.png ``topo2`` .. image:: ./figures/cmap_topo2.png **Categorical Colour Palettes** There are three colour palettes available through pygeostat for visualizing categorical data. ``cat_pastel`` and ``cat_vibrant`` consist of 12 colours, and the third, ``cat_dark``, has 6 available colours. They are available through the :func:`gs.get_palette() ` function. Issues arise when trying to represent a large number of categorical variables at once as colours will being to converge, meaning categories may appear to be the same colour. ``cat_pastel`` .. image:: ./figures/catpalette1.png ``cat_vibrant`` .. image:: ./figures/catpalette2.png ``cat_dark`` .. image:: ./figures/catpalette3.png Changing Figure Aesthetics ========================== Matplotlib is highly customizable in that font sizes, line widths, and other styling options can all be changed to the users desires. However, this process can be confusing due to the number of options. Matplotlib sources these settings from a dictionary called ``mpl.rcParams``. These can either be changed within a python session or permanently within the matplotlibrc file. For more discussion on ``mpl.rcParams`` and what each setting is, visit http://matplotlib.org/users/customizing.html As a means of creating a standard, a base pre-set style is set within pygeostat ``ccgpaper`` and some variables of it. They are accessible through the function :func:`gs.set_style() `. If you'd like to review their settings, the source can be easily viewed from this documentation. If users with to use their own defined ``mpl.rcParams``, the influence of :func:`gs.set_style() ` can be easily turned off so the custom settings are honored, or custom settings can be set through :func:`gs.set_style() `. Make sure to check out the functionality of :class:`gs.gsPlotStyle() `. Dealing with Memory Leaks from Plotting ======================================= As HDF5 functionality is enhanced within pygoestat (see :func:`gs.DataFile() `), loading large datasets into memory will become a viable option. Some plotting functions are beginning updated to be able to handle these file types, such as :func:`gs.histpltsim() `. If numerous plots are being generated in a loop, you may also notice that your systems physical memory is increasing without being dumped. This is a particular problem if large datasets are being loaded into memory. Not sure as to the reason, but even if you reuse a name space, the old data attached to it is not removed until your systems memory is maxed out. Matplotlib also stores figures in a loop. The module `gc `_ has a function ``gc.collect()`` that will dump data not connected to a namespace in python. The function :func:`gs.clrmplmem() ` dumps figure objects currently loaded and clears unused data from memory. An example of its usage: >>> pdfpages = '../99-Figures/hier/sim_NShistrep/0-Histrep.pdf' >>> if not os.path.isfile(pdfpages) or overwrite: >>> pdfpages = PdfPages(pdfpages) >>> else: >>> pdfpages = None >>> for var in variables: >>> var = 'NS_'+var >>> simfl = '../03-Simulation/hier/sgsim_%s.h5' % var >>> outfl = '../99-Figures/hier/sim_NShistrep/%s_histrep.pdf' % var >>> ax = gs.histpltsim(refdat=syndat.data[var], simdat=simfl, griddef=griddef, pltstyle=False, ... outfl=outfl, out_kws={'pdfpages':pdfpages}) >>> gs.clrmplmem() >>> if pdfpages: >>> pdfpages.close() Accuracy Plot ************* .. autofunction:: pygeostat.plotting.accplt Contour Plot ************ .. autofunction:: pygeostat.plotting.contourplt Correlation Matrix Plot *********************** .. autofunction:: pygeostat.plotting.corrmat Cross-Validation Scatter Plot ***************************** .. autofunction:: pygeostat.plotting.scatxval Drill Plot ********** .. autofunction:: pygeostat.plotting.drillplt.drillplt Exporting Figures ***************** .. autofunction:: pygeostat.plotting.exportimg Histogram Plot ************** .. autofunction:: pygeostat.plotting.histplt Histogram Reproduction Plot *************************** .. autofunction:: pygeostat.plotting.histpltsim Image Grid Plotter ****************** .. autofunction:: pygeostat.plotting.imagegrid.imagegrid Kernel Density Plot ******************* .. autofunction:: pygeostat.plotting.kdeplot Location Map ************ .. autofunction:: pygeostat.plotting.locmap Loadings Plot ************* .. autofunction:: pygeostat.plotting.loadingsplt Log Plot ******** .. autofunction:: pygeostat.plotting.logplot LVA Vector Plot *************** .. autofunction:: pygeostat.plotting.lvaplt Matrix Plot *********** .. autofunction:: pygeostat.plotting.matrixplot Pit Plot ******** .. autofunction:: pygeostat.plotting.pitplt Pixel Plot ********** .. autofunction:: pygeostat.plotting.pixelplt Pixel Plot 3D Grid Slicer ************************* .. autofunction:: pygeostat.plotting.gridslicer Probability Plot **************** .. autofunction:: pygeostat.plotting.probplt Quantity Metal Plot ******************* .. autofunction:: pygeostat.plotting.qmplt Quantile-Quantile Plot ********************** .. autofunction:: pygeostat.plotting.qqplt Scatter Plot ************ .. autofunction:: pygeostat.plotting.scatplt Scatter Plots ************* .. autofunction:: pygeostat.plotting.scatplts Scatter Plot Lower Upper ************************ .. autofunction:: pygeostat.plotting.scatplts_lu Subplots ******** .. autofunction:: pygeostat.plotting.subplots.subplots Variogram Plot ************** .. autofunction:: pygeostat.plotting.varplt Variogram Reproduction Plot *************************** .. autofunction:: pygeostat.plotting.varpltsim Pygeostat Plotting Styles ************************* .. autofunction:: pygeostat.plotting.set_style Plotting Utility Functions ************************** Variogram Plotting Utils ======================== One of the challenges with variogram plotting is handling the output variogram information from varcalc, varmodel, and varsim. While output from varmodel can only contain multiple directions, varcalc and varsim output can also contain multiple variables. This makes it difficult to collect the right information for plotting. The utility function :func:`gs.get_uniquevarids() ` can be used with both plotting functions :func:`gs.varplt() ` and :func:`gs.varpltsim() ` as a means of determining what variograms exist within datafiles as well creating a set of variogram IDs that can be called upon. Examples of its usage is shown throughout the aforementioned functions documentation. Get Unique Variograms --------------------- .. autofunction:: pygeostat.plotting.varutils.get_uniquevarids Trim Experimental Variogram --------------------------- .. autofunction:: pygeostat.plotting.varutils.trimylim Add Scale-bar ============= .. autofunction:: pygeostat.plotting.utils.scalebar Add X-tick Labels on ImageGrid ============================== .. autofunction:: pygeostat.plotting.utils.addxticks Annotate Scatter Plot ===================== .. autofunction:: pygeostat.plotting.utils.smart_annotate Apply Number of Ticks to Axis ============================= .. autofunction:: pygeostat.plotting.utils.applytickbins Clear Plotting Memory Leaks =========================== .. autofunction:: pygeostat.plotting.utils.clrmplmem Format Subplot Axis =================== .. autofunction:: pygeostat.plotting.utils.format_subplot_axis Format Plot =========== .. autofunction:: pygeostat.plotting.utils.formatplt Get a Colormap ============== .. autofunction:: pygeostat.plotting.utils.get_cmap Get Continous Colorbar Values ============================= .. autofunction:: pygeostat.plotting.utils.get_contcbarargs Get a Palette ============== .. autofunction:: pygeostat.plotting.utils.get_palette Get a Label from pd Sources =========================== .. autofunction:: pygeostat.plotting.utils.getlabel Get Logical Min/Max Values ========================== .. autofunction:: pygeostat.plotting.utils.getminmax Get Coordinates for Superaxis Label =================================== .. autofunction:: pygeostat.plotting.utils.get_supaxislocs Palette from Continuous Colormap ================================ .. autofunction:: pygeostat.plotting.utils.catcmapfromcontinuous Restore Matplotlib Plotting Style ================================= .. autofunction:: pygeostat.plotting.set_style.restore_mpl_style Set-up Figure Utility ===================== .. autofunction:: pygeostat.plotting.utils.setup_plot Statistics Block Utility ======================== .. autofunction:: pygeostat.plotting.utils.get_statblk Subplot Clean ============= .. autofunction:: pygeostat.plotting.subplots.subplots_clean Super Axis Label ================ .. autofunction:: pygeostat.plotting.utils.supaxislabel Title Overlap Check =================== .. autofunction:: pygeostat.plotting.utils.titleoverlap