Plotting Tools: Display models and data

The plot module provides mechanisms for plotting models, observations, and model fits.

The ModelPlot class can be used plotting models and observations without any \(\chi^2\) fitting. An example notebook for using ModelPlot is PDRT_Example_ModelPlotting.ipynb .

Some classes are paired with analysis tools in the tool module. LineRatioPlot which is used to plot the results of LineRatioFit, and H2ExcitationPlot that is used in H2Excitation. All plot classes are derived from PlotBase.

Plot Keywords

To manage the plots, the methods in Plot classes take keywords (**kwargs) that turn on or off various options, specify plot units, or map to matplotlib’s plot(), imshow(), contour() keywords. The methods have reasonable defaults, so try them with no keywords to see what they do before modifying keywords.

  • units (str or astropy.units.Unit) image data units to use in the plot. This can be either a string such as, ‘cm^-3’ or ‘Habing’, or it can be an astropy.units.Unit. Data will be converted to the desired unit. Note these are not the axis units, but the image data units. Modifying axis units is implemented via the xaxis_unit and yaxis_unit keywords.

  • image (bool) whether or not to display the image map (imshow).

  • show (str) which quantity to display in the Measurement, one of ‘data’, ‘error’, ‘mask’. For example, this can be used to plot the errors in observed ratios. Default: ‘data’

  • cmap (str) colormap name, Default: ‘plasma’

  • colorbar (str) whether or not to display colorbar

  • colors (str) color of the contours. Default: ‘whitecolor of the contours. Default: ‘white’

  • contours (bool), whether or not to plot contours

  • label (bool), whether or not to label contours

  • linewidths (float or sequence of float), the line width in points, Default: 1.0

  • legend (bool) Draw a legend on the plot. If False, a title is drawn above the plot with the value of the title keyword

  • levels (int or array-like) Determines the number and positions of the contour lines / regions. If an int n, use n data intervals; i.e. draw n+1 contour lines. The level heights are automatically chosen. If array-like, draw contour lines at the specified levels. The values must be in increasing order.

  • measurements (array-like) A list of single pixel Measurements that can be contoured over a model ratio or intensity map.

  • meas_color (array of str) A list of colors to use when overlaying Measurement contours. There should be one color for each Measurement in the measurement keyword. The Default of None will use a color-blind friendly color cycle.

  • norm (str or astropy.visualization normalization object) The normalization to use in the image. The string ‘simple’ will normalize with simple_norm() and ‘zscale’ will normalize with IRAF’s zscale algorithm. See ZScaleInterval.

  • stretch (str) {‘linear’, ‘sqrt’, ‘power’, log’, ‘asinh’}. The stretch function to apply to the image for simple_norm. The Default is ‘linear’.

  • aspect (str) aspect ratio, ‘equal’ or ‘auto’ are typical defaults.

  • origin (str) Origin of the image. Default: ‘lower’

  • title (str) A title for the plot. LaTeX allowed.

  • vmin (float) Minimum value for colormap normalization

  • vmax (float) Maximum value for colormap normalization

  • xaxis_unit (str or astropy.units.Unit) X axis (density) units to use when plotting models, such as in overlay_all_ratios() or modelratio(). If None, the native model axis units are used.

  • yaxis_unit (str or astropy.units.Unit) Y axis (FUV radiation field flux) units to use when plotting models, such as in overlay_all_ratios() or modelratio(). If None, the native model axis units are used.

The following keywords are available, but you probably won’t touch.

  • nrows (int) Number of rows in the subplot

  • ncols (int) Number of columns in the subplot

  • index (int) Index of the subplot

  • reset (bool) Whether or not to reset the figure.

Providing keywords other than these has undefined results, but may just work!


PlotBase

class pdrtpy.plot.plotbase.PlotBase(tool)[source]

Bases: object

Base class for plotting.

Parameters

tool (Any class derived from ToolBase) – Reference to a tool object or None. This is used for classes that inherit from PlotBase and are coupled to a specific tool, e.g. LineRatioPlot and LineRatioFit.

Attributes
axis

The last axis that was drawn.

figure

The last figure that was drawn.

Methods

savefig(fname, **kwargs)

Save the current figure to a file.

usetex(use)

Control whether plots use LaTeX formatting in axis labels and other text components.

property axis

The last axis that was drawn.

Return type

matplotlib.axes._subplots.AxesSubplot

property figure

The last figure that was drawn.

Return type

matplotlib.figure.Figure

savefig(fname, **kwargs)[source]

Save the current figure to a file.

Parameters

fname (str) – filename to save in

Keyword Arguments

Additional arguments (**kwargs) are passed to matplotlib.pyplot.savefig(). e.g. bbox_inches=’tight’ for a tight layout.

usetex(use)[source]

Control whether plots use LaTeX formatting in axis labels and other text components. This method sets matplotlib parameter rcParams[“text.usetex”] in the local pyplot instance.

Parameters

use (bool) – whether to use LaTeX or not

H2ExcitationPlot

class pdrtpy.plot.h2excitationplot.H2ExcitationPlot(tool, **kwargs)[source]

Bases: pdrtpy.plot.plotbase.PlotBase

Class to plot various results from H2 Excitation diagram fitting.

Attributes
axis

The last axis that was drawn.

figure

The last figure that was drawn.

Methods

plot_diagram(x, y, xsize, ysize[, norm])

Plot the excitation diagram

savefig(fname, **kwargs)

Save the current figure to a file.

usetex(use)

Control whether plots use LaTeX formatting in axis labels and other text components.

plot_diagram(x, y, xsize, ysize, norm=True)[source]

Plot the excitation diagram

Parameters
  • norm (bool) – if True, normalize the column densities by the statistical weight of the upper state, \(g_u\).

  • x (int) – bottom left corner x

  • y (int) – bottom left corner y

  • xsize (int) – box width, pixels

  • ysize (int) – box height, pixels

  • line (bool) – if True, the returned dictionary index is the Line name, otherwise it is the upper state \(J\) number.

LineRatioPlot

class pdrtpy.plot.lineratioplot.LineRatioPlot(tool)[source]

Bases: pdrtpy.plot.plotbase.PlotBase

Class to plot various results from PDR Toolbox model fitting.

Keyword Arguments

The methods of this class can take a variety of optional keywords. See the general Plot Keywords documentation

Attributes
axis

The last axis that was drawn.

figure

The last figure that was drawn.

Methods

chisq(**kwargs)

Plot the \(\chi^2\) map that was computed by the LineRatioFit tool.

confidence_intervals(**kwargs)

Plot the confidence intervals from the \(\chi^2\) map computed by the LineRatioFit tool.

density(**kwargs)

Plot the hydrogen nucleus volume density map that was computed by LineRatioFit tool.

modelintensity(id, **kwargs)

Plot one of the model intensities

modelratio(id, **kwargs)

Plot one of the model ratios

observedratio(id, **kwargs)

Plot one of the observed ratios

overlay_all_ratios(**kwargs)

Overlay all the measured ratios and their errors on the \((n,G_0)\) space.

radiation_field(**kwargs)

Plot the radiation field map that was computed by LineRatioFit tool.

ratios_on_models(**kwargs)

Overlay all the measured ratios and their errors on the individual models for those ratios.

reduced_chisq(**kwargs)

Plot the reduced \(\chi^2\) map that was computed by the LineRatioFit tool.

savefig(fname, **kwargs)

Save the current figure to a file.

show_both([units])

Plot both radiation field and volume density maps computed by the LineRatioFit tool in a 1x2 panel subplot.

usetex(use)

Control whether plots use LaTeX formatting in axis labels and other text components.

chisq(**kwargs)[source]

Plot the \(\chi^2\) map that was computed by the LineRatioFit tool.

confidence_intervals(**kwargs)[source]

Plot the confidence intervals from the \(\chi^2\) map computed by the LineRatioFit tool. Default levels: [50., 68., 80., 95., 99.]

Currently only works for single-pixel Measurements

density(**kwargs)[source]

Plot the hydrogen nucleus volume density map that was computed by LineRatioFit tool. Default units: cm \(^{-3}\)

modelintensity(id, **kwargs)[source]

Plot one of the model intensities

Parameters
  • id (str) – the intensity identifier, such as CO_32`.

  • **kwargs – see class documentation above

Raises

KeyError – if is id not in existing model intensities

modelratio(id, **kwargs)[source]

Plot one of the model ratios

Parameters
  • id (str) – the ratio identifier, such as CII_158/CO_32.

  • **kwargs – see class documentation above

Raises

KeyError – if is id not in existing model ratios

observedratio(id, **kwargs)[source]

Plot one of the observed ratios

Parameters

id – the ratio identifier, such as CII_158/CO_32.

Raises

KeyError – if id is not in existing observed ratios

overlay_all_ratios(**kwargs)[source]

Overlay all the measured ratios and their errors on the \((n,G_0)\) space.

Currently only works for single-pixel Measurements

radiation_field(**kwargs)[source]

Plot the radiation field map that was computed by LineRatioFit tool. Default units: Habing.

ratios_on_models(**kwargs)[source]

Overlay all the measured ratios and their errors on the individual models for those ratios. Plots are displayed in multi-column format, controlled the ncols keyword. Default: ncols=2

Currently only works for single-pixel Measurements

reduced_chisq(**kwargs)[source]

Plot the reduced \(\chi^2\) map that was computed by the LineRatioFit tool.

show_both(units=['Habing', 'cm^-3'], **kwargs)[source]

Plot both radiation field and volume density maps computed by the LineRatioFit tool in a 1x2 panel subplot. Default units: [‘Habing’,’cm^-3’]

ModelPlot

class pdrtpy.plot.modelplot.ModelPlot(modelset, figure=None, axis=None)[source]

Bases: pdrtpy.plot.plotbase.PlotBase

Class to plot models and optionally Measurements. It does not require LineRatioFit first.

Keyword Arguments

The methods of this class can take a variety of optional keywords. See the general Plot Keywords documentation

Attributes
axis

The last axis that was drawn.

figure

The last figure that was drawn.

Methods

intensity(identifier, **kwargs)

Plot a model ratio

overlay(measurements, **kwargs)

Overlay one or more single-pixel measurements in the model space ($n,G_0).

phasespace(identifiers[, nax1_clip, …])

Plot lines of constant density and radiation field on a ratio-ratio, ratio-intensity, or intensity-intensity map

plot(identifier, **kwargs)

Plot a model intensity or ratio

ratio(identifier, **kwargs)

Plot a model ratio

savefig(fname, **kwargs)

Save the current figure to a file.

usetex(use)

Control whether plots use LaTeX formatting in axis labels and other text components.

intensity(identifier, **kwargs)[source]

Plot a model ratio

Parameters

identifier (str) – Identifier tag for the model to plot, e.g., “OI_63”, “CII_158”, “CO_10”]

See also

supported_intensities() for a list of available identifer tags

overlay(measurements, **kwargs)[source]

Overlay one or more single-pixel measurements in the model space ($n,G_0).

Parameters
  • measurements (list) – a list of one or more pdrtpy.measurement.Measurement to overlay.

  • shading (float) – Controls how measurements and errors are drawn. If shading is zero, Measurements will be drawn in solid contour for the value and dashed for the +/- errors. If shading is between 0 and 1, Measurements are drawn with as filled contours representing the size of the errors (see contourf()) with alpha set to the shading value. Default value: 0.4

phasespace(identifiers, nax1_clip=<Quantity [1.e+01, 1.e+07] 1 / cm3>, nax2_clip=<Quantity [1.e+01, 1.e+06] Habing>, reciprocal=[False, False])[source]

Plot lines of constant density and radiation field on a ratio-ratio, ratio-intensity, or intensity-intensity map

Parameters
  • identifiers (list of str) – list of two identifier tags for the model to plot, e.g., [“OI_63/CO_21”, “CII_158”]

  • nax1_clip (array like, must contain Quantity) – The range of model densities on NAXIS1 to show in the plot. For most model NAXIS1 is hydrogen number density $n_H$ in cm$^{-3}$. For ionized gas models, it is electron temperature $T_e$ in K. Must be given as a range of astropy quanitities. Default: [10,1E7]*Unit(“cm-3”)

  • nax2_clip (array like, must contain Quantity) – The range of model parameters on NAXIS2 to show in the plot. For most models NAXIS2 is radiation field intensities in Habing or cgs units. For ionized gas models, it is electron volume density $n_e$. Must be given as a range of astropy quantities. Default: nax1_clip=[10,1E6]*utils.habing_unit.

  • reciprocal (list of bool) – Whether or not the plot the reciprocal of the model on each axis. Given as a pair of booleans. e.g. [False,True] means don’t flip the quantity X axis, but flip quantity the Y axis. i.e. if the model is “CII/OI”, and reciprocal=True then the axis will be “OI/CII”. Default: [False, False]

plot(identifier, **kwargs)[source]

Plot a model intensity or ratio

Parameters

identifier (str) – Identifier tag for the model to plot, e.g., “CII_158”,”OI_145”,”CO_43/CO_21’]

See also

supported_lines() for a list of available identifer tags

ratio(identifier, **kwargs)[source]

Plot a model ratio

Parameters

identifier (str) – Identifier tag for the model to plot, e.g., “OI_63+CII_158/FIR”, “CO_43/CO_21’]

See also

supported_ratios() for a list of available identifer tags