seisflows.tools.graphics
========================

.. py:module:: seisflows.tools.graphics

.. autoapi-nested-parse::

   Basic visualization tools for SeisFlows to visualize waveforms, models, etc.
   Includes utility functions for manipulating image files such as .png and .pdfs.
   Makes use use of the Python Pillow package if working with .png files, and
   the PyPDF2 package if manipulating pdf files. Internal imports for all functions
   to remove Pyatoa-wide dependencies on these packages for short functions.



Functions
---------

.. autoapisummary::

   seisflows.tools.graphics.merge_pdfs
   seisflows.tools.graphics.imgs_to_pdf
   seisflows.tools.graphics.tile_imgs
   seisflows.tools.graphics.tif_to_array
   seisflows.tools.graphics.plot_waveforms
   seisflows.tools.graphics.plot_optim_stats
   seisflows.tools.graphics.plot_2d_contour
   seisflows.tools.graphics.plot_2d_image


Module Contents
---------------

.. py:function:: merge_pdfs(fids, fid_out, remove_fids=False)

   Merge a list of pdfs into a single output pdf using the PyPDF2 package.
   Any desired order to the pdfs should be set in the list of input fids.

   :type fids: list
   :param fids: list of paths to .pdf files
   :type fid_out: str
   :param fid_out: path and name of the resulting output .pdf file
   :type remove_fids: bool
   :param remove_fids: remove the original input PDF files if the output PDF
       was successfully created. Defaults to False, original files are kept.


.. py:function:: imgs_to_pdf(fids, fid_out, remove_fids=False)

   Combine a list of .png files into a single PDF document

   :type fids: list
   :param fids: list of file ids with full pathnames to be combined
   :type fid_out: str
   :param fid_out: the name of the file to be saved with full pathname
   :type remove_fids: bool
   :param remove_fids: remove the original input PNG files if the output PDF
       was successfully created. Defaults to False, original files are kept.


.. py:function:: tile_imgs(fids, fid_out)

   Combine a list of images into a single, horizontally tiled image.

   :type fids: list
   :param fids: list of file ids with full pathnames to be tiled
   :type fid_out: str
   :param fid_out: the name of the file to be saved with full pathname


.. py:function:: tif_to_array(fid)

   Convert GeoTiff images (e.g., ETOPO1 topography) to a numpy array for
   conversion and processing

   :type fid: str
   :param fid: .tif(f) file
   :rtype: np.array
   :return: array of data contained within the tiff file


.. py:function:: plot_waveforms(tr_obs, tr_syn, tr_adj=None, fid_out=None, title=None, **kwargs)

   Very simple plotting routine to show waveforms and adjoint sources
   manipulated by the Default preprocessing module. Plots are simple and are
   provided in a default style that can be adjusted via keyword arguments.

   Cuts the x-axis (time) to the length of the synthetic seismogram as data
   may be longer which tends to obscure signal of interest.

   :type tr_obs: obspy.core.stream.Stream
   :param tr_obs: observed seismogram, data
   :type tr_syn: obspy.core.stream.Stream
   :param tr_syn: synthetic seismogram
   :type tr_adj: obspy.core.stream.Stream
   :param tr_adj: optional adjoint source. if not given, none will be plotted
   :type fid_out: str
   :param fid_out: name and path to save output file. If none given, output
       file will be saved to current working directory and named based on the
       trace ID of the obs data


.. py:function:: plot_optim_stats(fid='output_optim.txt', path_out='./')

   Line plot of optimization stats, which are written about by 
   Optimize.write_stats(). Intrinsically tied to the format of input file.

   :type fid: str
   :param fid: path to the optimization stats file to plot
   :type path_out: str
   :param path_out: full path (no filename) to save figures. filenames will
       be determined by the header values


.. py:function:: plot_2d_contour(x, z, data, cmap='viridis', zero_midpoint=False)

   Plots values of a SPECEFM2D model/gradient on an unstructured grid

   :type x: np.array
   :param x: x values of GLL mesh
   :type z: np.array
   :param z: z values of GLL mesh
   :type data: np.array
   :param data: D
   :type cmap: str
   :param cmap: matplotlib colormap to be applied to the contour plot. Defaults
       to 'viridis'
   :type zero_midpoint: bool
   :param zero_midpoint: set 0 as the midpoint for the colorbar. Useful for
       diverging colorscales (e.g., for gradients), where the neutral color
       (e.g., white) is set at value=0


.. py:function:: plot_2d_image(x, z, data, res_x=1000, res_z=1000, cmap='viridis', vmin=None, vmax=None, levels=101)

   Plots values of a SPECEFM2D model/gradient by interpolating onto a regular 
   grid. Used for the SeisFlows command `seisflows plot2d`

   :type x: np.array
   :param x: x values of GLL mesh
   :type z: np.array
   :param z: z values of GLL mesh
   :type data: np.array
   :param data: D
   :type cmap: str
   :param cmap: matplotlib colormap to be applied to the contour plot. Defaults
       to 'viridis'
   :type zero_midpoint: bool
   :param zero_midpoint: set 0 as the midpoint for the colorbar. Useful for
       diverging colorscales (e.g., for gradients), where the neutral color
       (e.g., white) is set at value=0
   :type resX: int
   :param resX: number of points for the interpolation in x- direction 
       (default=1000)
   :type resZ: int
   :param resZ: number of points for the interpolation in z- direction 
   (default=1000)