xyzpy.plot.plotter_matplotlib ============================= .. py:module:: xyzpy.plot.plotter_matplotlib .. autoapi-nested-parse:: Functions for plotting datasets nicely. Attributes ---------- .. autoapisummary:: xyzpy.plot.plotter_matplotlib._SCATTER_ALT_DEFAULTS xyzpy.plot.plotter_matplotlib._HISTOGRAM_SPECIFIC_OPTIONS xyzpy.plot.plotter_matplotlib._HISTOGRAM_ALT_DEFAULTS xyzpy.plot.plotter_matplotlib._HEATMAP_ALT_DEFAULTS Classes ------- .. autoapisummary:: xyzpy.plot.plotter_matplotlib.PlotterMatplotlib xyzpy.plot.plotter_matplotlib.LinePlot xyzpy.plot.plotter_matplotlib.AutoLinePlot xyzpy.plot.plotter_matplotlib.Scatter xyzpy.plot.plotter_matplotlib.AutoScatter xyzpy.plot.plotter_matplotlib.Histogram xyzpy.plot.plotter_matplotlib.AutoHistogram xyzpy.plot.plotter_matplotlib.HeatMap xyzpy.plot.plotter_matplotlib.AutoHeatMap Functions --------- .. autoapisummary:: xyzpy.plot.plotter_matplotlib.mpl_multi_plot xyzpy.plot.plotter_matplotlib.lineplot xyzpy.plot.plotter_matplotlib.auto_lineplot xyzpy.plot.plotter_matplotlib.scatter xyzpy.plot.plotter_matplotlib.auto_scatter xyzpy.plot.plotter_matplotlib.histogram xyzpy.plot.plotter_matplotlib.auto_histogram xyzpy.plot.plotter_matplotlib.heatmap xyzpy.plot.plotter_matplotlib.auto_heatmap xyzpy.plot.plotter_matplotlib.setup_fig_ax xyzpy.plot.plotter_matplotlib.show_and_close xyzpy.plot.plotter_matplotlib.choose_squarest_grid xyzpy.plot.plotter_matplotlib._compute_hue xyzpy.plot.plotter_matplotlib.to_colors xyzpy.plot.plotter_matplotlib.add_visualize_legend xyzpy.plot.plotter_matplotlib.make_ax_square_after_plotted xyzpy.plot.plotter_matplotlib.handle_sequence_of_arrays xyzpy.plot.plotter_matplotlib.visualize_matrix xyzpy.plot.plotter_matplotlib.visualize_tensor xyzpy.plot.plotter_matplotlib._draw_tensor_tree_branch xyzpy.plot.plotter_matplotlib.visualize_tensor_tree Module Contents --------------- .. py:class:: PlotterMatplotlib(ds, x, y, z=None, y_err=None, x_err=None, **kwargs) Bases: :py:obj:`xyzpy.plot.core.Plotter` .. py:method:: prepare_axes() .. py:method:: set_axes_labels() .. py:method:: set_axes_scale() .. py:method:: set_axes_range() .. py:method:: set_spans() .. py:method:: set_gridlines() .. py:method:: set_tick_marks() .. py:method:: _cax_rel2abs_rect(rel_rect, cax=None) Turn a relative axes specification into a absolute one. .. py:method:: plot_legend(grid=False, labels_handles=None) Add a legend .. py:method:: set_mappable() Mappale object for colorbars. .. py:method:: plot_colorbar(grid=False) Add a colorbar to the data. .. py:method:: set_panel_label() .. py:method:: show() .. py:method:: prepare_plot() Do all the things that every plot has. .. py:function:: mpl_multi_plot(fn) Decorate a plotting function to plot a grid of values. .. py:class:: LinePlot(ds, x, y, z=None, *, y_err=None, x_err=None, **kwargs) Bases: :py:obj:`PlotterMatplotlib`, :py:obj:`xyzpy.plot.core.AbstractLinePlot` .. py:method:: plot_lines() .. py:method:: __call__() .. py:function:: lineplot(ds, x, y, z=None, y_err=None, x_err=None, **plot_opts) From ``ds`` plot lines of ``y`` as a function of ``x``, optionally for varying ``z``. :param ds: Dataset to plot from. :type ds: xarray.Dataset :param x: Dimension to plot along the x-axis. :type x: str :param y: Variable(s) to plot along the y-axis. If tuple, plot each of the variables - instead of ``z``. :type y: str or tuple[str] :param z: Dimension to plot into the page. :type z: str, optional :param y_err: Variable to plot as y-error. :type y_err: str, optional :param x_err: Variable to plot as x-error. :type x_err: str, optional :param row: Dimension to vary over as a function of rows. :type row: str, optional :param col: Dimension to vary over as a function of columns. :type col: str, optional :param plot_opts: See ``xyzpy.plot.core.PLOTTER_DEFAULTS``. .. py:class:: AutoLinePlot(x, y_z, **lineplot_opts) Bases: :py:obj:`LinePlot` .. py:function:: auto_lineplot(x, y_z, **lineplot_opts) Auto version of :func:`~xyzpy.lineplot` that accepts array arguments by converting them to a ``Dataset`` first. .. py:data:: _SCATTER_ALT_DEFAULTS :value: (('legend_handlelength', 0),) .. py:class:: Scatter(ds, x, y, z=None, **kwargs) Bases: :py:obj:`PlotterMatplotlib`, :py:obj:`xyzpy.plot.core.AbstractScatter` .. py:method:: plot_scatter() .. py:method:: __call__() .. py:function:: scatter(ds, x, y, z=None, y_err=None, x_err=None, **plot_opts) From ``ds`` plot a scatter of ``y`` against ``x``, optionally for varying ``z``. :param ds: Dataset to plot from. :type ds: xarray.Dataset :param x: Quantity to plot along the x-axis. :type x: str :param y: Quantity(s) to plot along the y-axis. If tuple, plot each of the variables - instead of ``z``. :type y: str or tuple[str] :param z: Dimension to plot into the page. :type z: str, optional :param y_err: Variable to plot as y-error. :type y_err: str, optional :param x_err: Variable to plot as x-error. :type x_err: str, optional :param row: Dimension to vary over as a function of rows. :type row: str, optional :param col: Dimension to vary over as a function of columns. :type col: str, optional :param plot_opts: See ``xyzpy.plot.core.PLOTTER_DEFAULTS``. .. py:class:: AutoScatter(x, y_z, **scatter_opts) Bases: :py:obj:`Scatter` .. py:function:: auto_scatter(x, y_z, **scatter_opts) Auto version of :func:`~xyzpy.scatter` that accepts array arguments by converting them to a ``Dataset`` first. .. py:data:: _HISTOGRAM_SPECIFIC_OPTIONS .. py:data:: _HISTOGRAM_ALT_DEFAULTS .. py:class:: Histogram(ds, x, z=None, **kwargs) Bases: :py:obj:`PlotterMatplotlib`, :py:obj:`xyzpy.plot.core.AbstractHistogram` .. py:method:: plot_histogram() .. py:method:: __call__() .. py:function:: histogram(ds, x, z=None, **plot_opts) Dataset histogram. :param ds: The dataset to plot. :type ds: xarray.Dataset :param x: The variable(s) to plot the probability density of. If sequence, plot a histogram of each instead of using a ``z`` coordinate. :type x: str, sequence of str :param z: If given, range over this coordinate a plot a histogram for each. :type z: str, optional :param row: Dimension to vary over as a function of rows. :type row: str, optional :param col: Dimension to vary over as a function of columns. :type col: str, optional :param plot_opts: See ``xyzpy.plot.core.PLOTTER_DEFAULTS``. .. py:class:: AutoHistogram(x, **histogram_opts) Bases: :py:obj:`Histogram` .. py:function:: auto_histogram(x, **histogram_opts) Auto version of :func:`~xyzpy.histogram` that accepts array arguments by converting them to a ``Dataset`` first. .. py:data:: _HEATMAP_ALT_DEFAULTS :value: (('legend', False), ('colorbar', True), ('colormap', 'inferno'), ('method', 'pcolormesh'),... .. py:class:: HeatMap(ds, x, y, z, **kwargs) Bases: :py:obj:`PlotterMatplotlib`, :py:obj:`xyzpy.plot.core.AbstractHeatMap` .. py:method:: plot_heatmap() Plot the data as a heatmap. .. py:method:: __call__() .. py:function:: heatmap(ds, x, y, z, **kwargs) From ``ds`` plot variable ``z`` as a function of ``x`` and ``y`` using a 2D heatmap. :param ds: Dataset to plot from. :type ds: xarray.Dataset :param x: Dimension to plot along the x-axis. :type x: str :param y: Dimension to plot along the y-axis. :type y: str :param z: Variable to plot as colormap. :type z: str, optional :param row: Dimension to vary over as a function of rows. :type row: str, optional :param col: Dimension to vary over as a function of columns. :type col: str, optional :param plot_opts: See ``xyzpy.plot.core.PLOTTER_DEFAULTS``. .. py:class:: AutoHeatMap(x, **heatmap_opts) Bases: :py:obj:`HeatMap` .. py:function:: auto_heatmap(x, **heatmap_opts) Auto version of :func:`~xyzpy.heatmap` that accepts array arguments by converting them to a ``Dataset`` first. .. py:function:: setup_fig_ax(nrows=1, ncols=1, facecolor=None, rasterize=False, rasterize_dpi=300, figsize=(5, 5), ax=None, **kwargs) .. py:function:: show_and_close(fn) .. py:function:: choose_squarest_grid(x) .. py:function:: _compute_hue(z) .. py:function:: to_colors(zs, magscale='linear', max_mag=None, alpha_map=True, alpha_pow=1 / 2) Convert complex array to RGBA colors. :param zs: Complex array to convert to colors. :type zs: array_like :param magscale: Scale to apply to the magnitude before mapping to saturation. If "linear", no scaling is applied. If "log", logarithmic scaling is applied. If float, the magnitude is raised to this power. Default is "linear". :type magscale: {"linear", "log", float}, optional :param max_mag: Maximum magnitude to map to full saturation. If None, the maximum magnitude in `zs` is used. :type max_mag: float, optional :param alpha_map: Whether to append an alpha channel based on magnitude. Default is True. :type alpha_map: bool, optional :param alpha_pow: Power to raise the magnitude to when computing the alpha channel. Default is 1/2. :type alpha_pow: float, optional :returns: * **colors** (*ndarray*) -- Array of shape (..., 3) or (..., 4) of RGB(A) colors. * **mapped_mag** (*ndarray*) -- The mapped magnitudes used for saturation and alpha. * **max_mag** (*float*) -- The maximum magnitude used for saturation mapping. .. py:function:: add_visualize_legend(ax, complexobj, max_mag, legend_inside=False, auto_pad=0.03, legend_loc='auto', legend_size=0.15, legend_bounds=None, legend_resolution=3) .. py:function:: make_ax_square_after_plotted(ax) .. py:function:: handle_sequence_of_arrays(f) Simple wrapper to handle sequence of arrays as input to e.g. ``visualize_tensor``. .. py:function:: visualize_matrix(array, max_mag=None, magscale='linear', alpha_map=True, alpha_pow=1 / 2, legend=True, legend_loc='auto', legend_size=0.15, legend_bounds=None, legend_resolution=3, facecolor=None, rasterize=4096, rasterize_dpi=300, figsize=(5, 5), ax=None) Visualize ``array`` as a 2D colormapped image. :param array: A 2D (or 1D) array or sequence of arrays to visualize. :type array: array_like or Sequence[array_like] :param max_mag: The maximum magnitude to use for the color mapping. If not provided, the maximum magnitude in the array will be used. :type max_mag: float, optional :param magscale: How to scale the magnitude of the array values. If "linear", then the magnitude is used directly. If a float, then the magnitude is raised to this power before being used, which can help to show variation among small values. :type magscale: "linear" or float, optional :param alpha_map: Whether to map the tensor value magnitudes to pixel alpha. :type alpha_map: bool, optional :param alpha_pow: The power to raise the magnitude to when mapping to alpha. :type alpha_pow: float, optional :param legend: Whether to show a legend (colorbar). If the array has complex dtype then the legend will be a colorwheel. :type legend: bool, optional :param legend_loc: Where to place the legend. If "auto", then the legend will be placed outside the plot rectangle, otherwise it should be a tuple of ``(x, y)`` coordinates in axes space. :type legend_loc: str or tuple[float], optional :param legend_size: The size of the legend, in relation to the size of the plot axes. :type legend_size: float, optional :param legend_bounds: The bounds of the legend, as ``(x, y, width, height)`` in axes space. If not provided, the bounds will be computed from ``legend_loc`` and ``legend_size``. :type legend_bounds: tuple[float], optional :param legend_resolution: The number of different colors to show in the legend. :type legend_resolution: int, optional :param facecolor: The background color of the plot, by default transparent. :type facecolor: str, optional :param rasterize: Whether to rasterize the plot. If a number, then rasterize if the number of pixels in the plot is greater than this value. :type rasterize: int or float, optional :param rasterize_dpi: The dpi to use when rasterizing. :type rasterize_dpi: float, optional :param figsize: The size of the figure to create, if ``ax`` is not provided. :type figsize: tuple[float], optional :param ax: The axis to draw to. If not provided, a new figure will be created. :type ax: matplotlib.Axis, optional :param show_and_close: If ``True`` (the default) then show and close the figure, otherwise return the figure and axis. :type show_and_close: bool, optional :returns: * **fig** (*matplotlib.Figure*) -- The figure containing the plot, or ``None`` if ``ax`` was provided. * **ax** (*matplotlib.Axis*) -- The axis or axes containing the plot(s). .. py:function:: visualize_tensor(array, spacing_factor=1.0, max_projections=None, projection_overlap_spacing=1.05, angles=None, scales=None, skew_angle_factor='auto', skew_scale_factor=0.05, max_mag=None, magscale='linear', size_map=True, size_pow=1 / 2, size_scale=1.0, alpha_map=True, alpha_pow=1 / 2, alpha=0.8, marker='o', linewidths=0, show_lattice=True, lattice_opts=None, compass=False, compass_loc='auto', compass_size=0.1, compass_bounds=None, compass_labels=None, compass_opts=None, legend=True, legend_loc='auto', legend_size=0.15, legend_bounds=None, legend_resolution=3, interleave_projections=False, reverse_projections=False, facecolor=None, rasterize=4096, rasterize_dpi=300, figsize=(5, 5), ax=None) Visualize all entries of a tensor, with indices mapped into the plane and values mapped into a color wheel. :param array: The tensor to visualize. :type array: numpy.ndarray :param spacing_factor: How to scale the dimensions relative to each other. If 1.0, then each dimension will have the same extent, and smaller dimensions will be sparser. If 0.0, the each dimension will have an extent propoertional to its size, with matching density. :type spacing_factor: float, optional :param max_projections: The maximum number of different projection directions / angles to use. If specified and less than the number of dimensions, then multiple dimensions will share the same angle but with different scales. :type max_projections: int, optional :param projection_overlap_spacing: When grouping multiple dimensions to the same angle, how much to increase the spacing at each scale so as to emphasize each. :type projection_overlap_spacing: float, optional :param angles: An explicit list of angles to use for each direction, in radians, with zero pointing straight down. If not provided, then the angles will be calculated automatically. :type angles: sequence[float], optional :param scales: An explicit list of scales to use for each direction. If not provided, then the scales will be calculated automatically. :type scales: sequence[float], optional :param skew_angle_factor: When there are more than two dimensions, a factor to scale the rotations by to avoid overlapping data points. If 0.0 then the angles will be evenly spaced. :type skew_angle_factor: float, optional :param skew_scale_factor: When there are more than two dimensions, a factor to scale the scales by to avoid overlapping data points, that shortens non-perpendicular directions. :type skew_scale_factor: float, optional :param max_mag: The maximum magnitude to use for the color mapping. If not provided, the maximum magnitude in the array will be used. :type max_mag: float, optional :param magscale: How to scale the magnitude of the array values. If "linear", then the magnitude is used directly. If a float, then the magnitude is raised to this power before being used, which can help to show variation among small values. :type magscale: "linear" or float, optional :param size_map: Whether to map the tensor value magnitudes to marker size. :type size_map: bool, optional :param size_scale: An overall factor to scale the marker size by. :type size_scale: float, optional :param alpha_map: Whether to map the tensor value magnitudes to marker alpha. :type alpha_map: bool, optional :param alpha_pow: The power to raise the magnitude to when mapping to alpha. :type alpha_pow: float, optional :param alpha: The overall alpha to use for all markers if ``not alpha_map``. :type alpha: float, optional :param marker: The marker to use for the markers. :type marker: str, optional :param linewidths: The linewidth to use for the markers. :type linewidths: float, optional :param show_lattice: Show a thin grey line connecting adjacent array coordinate points. :type show_lattice: bool, optional :param lattice_opts: Options to pass to ``maplotlib.Axis.scatter`` for the lattice grid. :type lattice_opts: dict, optional :param compass: Whether to show a compass indicating the orientation of each dimension. :type compass: bool, optional :param compass_loc: Where to place the compass. :type compass_loc: (float, float), optional :param compass_size: The size of the compass. :type compass_size: float, optional :param compass_bounds: Explicit bounds of the compass, as ``(x, y, width, height)``. :type compass_bounds: tuple[float], optional :param compass_labels: Explicit labels for the compass, in order of the dimensions. :type compass_labels: sequence[str], optional :param compass_opts: Extra options for the compass arrows. :type compass_opts: dict, optional :param legend: Whether to show a legend (colorbar). If the array has complex dtype then the legend will be a colorwheel. :type legend: bool, optional :param legend_loc: Where to place the legend. If "auto", then the legend will be placed outside the plot rectangle, otherwise it should be a tuple of ``(x, y)`` coordinates in axes space. :type legend_loc: str or tuple[float], optional :param legend_size: The size of the legend, in relation to the size of the plot axes. :type legend_size: float, optional :param legend_bounds: Explicit bounds of the legend, as ``(x, y, width, height)`` in axes space. :type legend_bounds: tuple[float], optional :param legend_resolution: The number of different colors to show in the legend. :type legend_resolution: int, optional :param interleave_projections: If ``True`` and grouping dimensions, then they are assigned round robin fashion rather than blocks. ``False`` matches the behavior of fusing. :type interleave_projections: bool, optional :param reverse_projections: Whether to reverse the order of the projections. :type reverse_projections: bool, optional :param facecolor: The background color of the plot, by default transparent. :type facecolor: str, optional :param rasterize: Whether to rasterize the plot. If a number, then rasterize if the size of the array is greater than this value. :type rasterize: int or float, optional :param rasterize_dpi: The dpi to use when rasterizing. :type rasterize_dpi: float, optional :param figsize: The size of the figure to create, if ``ax`` is not provided. :type figsize: tuple, optional :param ax: The axis to draw to. If not provided, a new figure will be created. :type ax: matplotlib.Axis, optional :returns: * **fig** (*matplotlib.Figure*) -- The figure containing the plot, or ``None`` if ``ax`` was provided. * **ax** (*matplotlib.Axis*) -- The axis containing the plot. .. py:function:: _draw_tensor_tree_branch(lines, widths, colors, array, x=0.0, y=0.0, phi_center=np.pi / 2, phi_range=np.pi, level=1, z=None, mag=None, mag_weight=None, linewidth=10) .. py:function:: visualize_tensor_tree(array, phi_center=np.pi / 2, phi_range=np.pi, linewidth=10, legend=True, legend_loc='top right', legend_size=0.15, legend_bounds=None, legend_resolution=3, facecolor=None, rasterize=4096, rasterize_dpi=300, figsize=(5, 5), ax=None)