sensortoolkit.plotting._scatter.scatter_plotter

scatter_plotter(df_list, ref_df, stats_df=None, plot_subset=None, param=None, sensor_name=None, figure_path=None, write_to_file=True, averaging_interval=None, met_ref_df=None, deploy_dict=None, sensor_serials=None, ax=None, fig=None, report_fmt=False, return_axs=False, param_class=None, **kwargs)[source]

Front-end function for creating scatter plots.

Calls Draw_Scatter for lower-end tasks and sets formatting for plots based off passed parameters.

Parameters
  • df_list (list) – A list containing the sensor dataframes from which data is plotted

  • ref_df (pandas DataFrame) – Reference dataframe

  • stats_df (pandas DataFrame) – Regression statistics dataframe for the sensor evaluation set

  • plot_subset (Nonetype or list of strings) – To plot a subset of evaluated sensors, pass a list of the sensor numbers (‘1’, ‘2’, ‘3’, etc.) as assigned in the sensor serial dictionary. For example, plotting a subset for sensors ‘1’, ‘3’, and ‘5’ in an evaluation is achieved by passing plot_subset=[‘1’, ‘3’, ‘5’].

  • param (str) – Column header name for the pollutant values to be plotted

  • sensor_name (str) – Unformatted sensor name, passed to Formatted_Sensor_Name() for including formatted version on plot

  • figure_path (str) – Path to directory where the figure will be saved

  • write_to_file (bool) – If true, writes to file and figure is closed. False skips file writing and does not close the figure

  • averaging_interval (str) – The averaging interval of the sensor and reference datasets, either ‘1-hour’ or ‘24-hour’.

  • met_ref_df (Nonetype or pandas DataFrame) – Reference dataframe for met data. Used as an alternative to sensor met data for plotting colormap of relative humidity on scatterplot points. If passed, the reference met data takes precedence over any existing sensor met data.

  • deploy_dict (dict) – A dictionary containing descriptive statistics and textual information about the deployment (testing agency, site, time period, etc.), sensors tested, and site conditions during the evaluation.

  • sensor_serials (dict) – A dictionary of sensor serial identifiers for each unit in the testing deployment.

  • ax (matplotlib.axes._subplots.AxesSubplot, optional) – Optional, the Matplotlib Axes object on which plotting elements will be drawn. Useful is the user is iterating over the Axes elements of a Matplotlib figure in a for-loop outside this plotting function. Within the loop, calls to this function can be made to add elements for each axes object. Defaults to None.

  • fig (Matplotlib.figure.Figure, optional) – Optional, the Matplotlib figure on which axes object elements are drawn. Useful is the user is iterating over the Axes elements of a Matplotlib figure in a for-loop outside this plotting function. Within the loop, calls to this function can be made to add elements for each axes object. Defaults to None.

  • report_fmt (bool) – If true, select formatting presets for displaying figures on the reporting template for sensor performance evaluations included alongside US EPA’s performance targets documents for air sensors.

  • return_axs (bool, optional) – If true, will return a Matplotlib axes instance (useful for iteration over subplot axes if this plotting function is called within a for-loop that is iterating over the axes elements in a Matplotlib subplot object). Defaults to False.

  • param_class (str) – The parameter classification for the passed parameter to plot. E.g, if param is PM25, param_class = PM; if param is 03, param_class = Gases;if param is Temp, param_class = Met.

Keyword Arguments:

Parameters
  • color_palette (str) – Color palette assigned to relative-humidity colormapped scatter plot points. Defaults to 'seismic'.

  • colorbar_axespos (Four-element tuple) – Set the position of the colorbar axes object relative to the Matplotlib Figure coordinates. Four element tuple composed of (left-most x-coordinate, bottom-most y-coordinate, width, height) of the colobar axes object.

  • colorbar_orientation (str) – The orientation of the colorbar as drawn on the figure. Either ‘vertical’ or ‘horizontal’.

  • colorbar_title_fontsize – The size of the ‘Relative Humidity’ title assigned to the colorbar. Defaults to the value of 'detail_fontsize'.

  • colorbar_title_ypos – The y-position of the colorbar relative to the Matplotlib Figure coordinate dimensions.

  • colorbar_tick_labelsize (int or float) – The size of the label (percentage of RH) for the colorbar. Defaults to the value of 'detail_fontsize'.

  • colorbar_tick_length (int or float) – The length of the colorbar ticks. Defaults to 4.0.

  • colorbar_tick_width (float) – The thickness (width) of the colorbar ticks. Defaults to 1.0.

  • draw_cbar (bool) – If True, relative humidity values will be superimposed on to sensor-reference measurement pairs via the specified color palette ('color_palette') and a colorbar will be drawn alongside the scatter subplots as a legend for colored RH values.

  • fig_wspace (float) – Modify the width of padding between subplots. Passed to Matplotlib.subplots.subplots_adjust() 'wspace' argument.

  • fig_hspace (float) – Modify the height of padding between subplots. Passed to Matplotlib.subplots.subplots_adjust() 'hspace' argument.

  • fig_left (float) – Modify the left-most bounds of the figure. Passed to Matplotlib.subplots.subplots_adjust() 'left' argument.

  • fig_right (float) – Modify the right-most bounds of the figure. Passed to Matplotlib.subplots.subplots_adjust() 'right' argument.

  • fig_top (float) – Modify the upper-most bounds of the figure. Passed to Matplotlib.subplots.subplots_adjust() 'top' argument.

  • fig_bottom (float) – Modify the lower-most bounds of the figure. Passed to Matplotlib.subplots.subplots_adjust() 'bottom' argument.

  • filename_suffix (str) – Optional string added to end of filename. Defaults to empty string.

  • fontsize (str, passed to Draw_Scatter()) – The font size for the xlabel, ylabel, and plot text. Passed on to Draw_Scatter() which uses 0.85*font_size for tick labels.

  • monocolor (str, passed to Draw_Scatter()) – A single color (specified in hex) for scatter. Scatter are colored using monocolor if show_colorbar is False. Recommend #2251D0 (nice blue hue).

  • detail_fontsize (float) – Fontsize for axes tick labels and smaller plotting text elements.

  • point_size (int or float, passed to Draw_Scatter()) – The size of the scatter points. Defaults to 20.

  • point_alpha (float) – The transparency of the scatter plots. Defaults to 0.7.

  • plot_aspect (str, passed to Draw_Scatter()) – Aspect ratio for scatter plot dimensions. Defaults to ‘equal’.

  • plottext_alpha (float, passed to Draw_Scatter()) – The transparency of the text drawn on scatter plots indicating regression statistics. Defaults to 0.8.

  • plottext_size (float, passed to Draw_Scatter()) – The size of the text drawn on scatter plots indicating regression statistics as a fraction of the passed fontsize. Defaults to 90% the value of the fontsize.

  • plottext_color (str, passed to Draw_Scatter()) – The color of the text drawn on scatter plots indicating regression statistics. Defaults to ‘k’.

  • plottext_xloc (float, passed to Draw_Scatter()) – The left-most x-coordinate of the text drawn on scatter plots. Default depends on the value passed to the plottext_postion argument.

  • plottext_yloc (float, passed to Draw_Scatter()) – The top-most y-coordinate of the text drawn on scatter plots. Default depends on the value passed to the plottext_postion argument.

  • plottext_xdisplacement (float, passed to Draw_Scatter()) – The width displacement between text drawn on scatter plots. Defaults to 0.0.

  • plottext_ydisplacement (float, passed to Draw_Scatter()) – The height displacement between rows of text drawn on scatter plots. Defaults to 0.08.

  • plottext_position (TYPE, passed to Draw_Scatter()) – Determines position of plot text. Options include ‘upper_left’ or ‘bottom_right’. Defaults to ‘upper_left’ if the slope of the ‘ regression is greater than 1.75, else default is set to ‘bottom_right’.

  • ref_name (str) – The name of the reference monitor (make, model).

  • seaborn_style (str) – Seaborn plotting style for plots. Options include ['darkgrid', 'whitegrid', 'dark', 'white', 'ticks']. Defaults to 'darkgrid'.

  • show_colorbar (bool) – If true, relative humidity values will be used as a colormap on the scatterplot points.

  • show_title (bool) – Show the title at the top of the plot. Includes the name of the sensor, the averaging interval, the evaluation parameter, and the name of the reference against which sensor data are compared.

  • show_regression (bool) – If true, display the OLS regression equation on scatter plots. Defaults to True.

  • show_trendline (bool) – If true, display the OLS trendline on scatter plots. Defaults to True.

  • show_RMSE (bool, passed to Draw_Scatter()) – If true, display the root mean squared error on scatter plots. Defaults to True.

  • show_spearman (bool, passed to Draw_Scatter()) – If true, display the spearman correlation on scatterplots. Defaults to False.

  • show_N (bool, passed to Draw_Scatter()) – If true, display the number of scatter point pairs displayed on the plot. Defaults to True.

  • show_one_to_one (bool, passed to Draw_Scatter()) – If true, display the one-to-one line indicating ideal agreement between independent and depdendent variable. Defaults to True.

  • tight_layout (bool) – Passed to matplotlib’s fig.tight_layout() for narrow formatting

  • tick_spacing (int or float) – The spacing (in concentration units) between adjacent tick marks along the x and y-axes.

  • title_text (str) – The title text displayed above the figure subplots.

  • title_textwrap (int) – The number of characters to include on a single line of the title before inserting a new line.

  • title_xloc (float) – The center horizontal Matplotlib Axes location of the plot title.

  • title_yloc (float) – The center vertical Matplotlib Axes location of the plot title.

  • trendline_xmax (TYPE, passed to Draw_Scatter()) – The draw distance (based on the passed x-coordinate) of the OLS trendline. Defaults to 120% the maximum of the independent variable.

  • trendline_color (str, passed to Draw_Scatter()) – The color of the trendline. Defaults to ‘k’ (black).

  • trendline_alpha (float, passed to Draw_Scatter()) – The transparency of the trendline. Defaults to 0.65.

  • xlims (Two-element tuple of floats) –

    The x-limits of the scatter plot. Defaults to zero for the lower limit. For the upper limit, the following forumla is used:

    \[x_{max} = 1.25\times C_{max} + (\Delta_{tick} - 1.25\times C_{max}\%\Delta_{tick})\]

    where:

    • \(x_{max}\) is the upper limit of the x-axis

    • \(C_{max}\) is the maximum value for either dependent or independent variable

    • \(\%\) is the modulo operator

    • \(\Delta_{tick}\) is the spacing between ticks along the x and y-axes (set by the tick_spacing argument)

    This forumla can be described in the following way: The upper limit is set to 125% the nearest multiple of the tick_spacing argument to the maximum concentration recorded by either independent or dependent variable (e.g., if the max concentration recorded by either sensor or reference is 22.4 ug/m^3 and the tick_spacing is set to divisions of 5 ug/m^3, the x upper limit will be set to 1.25*22.4 = 28 -> rounded to the nearest multiple of 5 ug/m^3 becomes 30 ug/m^3.

  • ylims (Two-element tuple of floats) – The y-limits of the scatter plot. Defaults to zero for the lower limit. For the default upper y-limit, the value is set equal to the value computed for the x-limit above (i.e., the figure dimensions along both axes are set equal).

Returns

If an axis is passed to Scatter_Plotter(), the modified axis with plotting detail filled in will be returned. Otherwise, none will be returned.

Return type

(matplotlib axes instance or None)