`bin.MarsPlot`

The MarsPlot executable is for generating plots from Custom.in template files. It sources variables from netCDF files in a specified directory.

The executable requires:

[-template --generate_template] Generates a Custom.in template

[-i --inspect] Triggers ncdump-like text to console

[Custom.in] To create plots in Custom.in template

Third-party Requirements:

numpy

netCDF4

sys

argparse

os

warnings

subprocess

matplotlib

pypdf

Module Contents

Classes

`CustomTicker`	Format values following scientific notation in a logarithmic axis.
`Fig_1D`	Fig_1D is a parent class for generating and handling 1D plots of
`Fig_2D`	Base class for 2D figures. This class is not intended to be
`Fig_2D_lat_lev`	A subclass of Fig_2D for generating 2D plots with latitude and
`Fig_2D_lon_lat`	Fig_2D_lon_lat is a class for creating 2D longitude-latitude plots.
`Fig_2D_lon_lev`	A subclass of Fig_2D for generating 2D plots with longitude and
`Fig_2D_lon_time`	A specialized 2D plotting class for visualizing data as a function
`Fig_2D_time_lat`	A 2D plotting class for visualizing data as a function of time (Ls)
`Fig_2D_time_lev`	A specialized 2D plotting class for visualizing data as a function

Functions

`MY_func`(Ls_cont)	Returns the Mars Year.
`clean_comma_whitespace`(raw_input)	Remove commas and whitespaces inside an expression.
`create_exec`(raw_input, varfull_list)
`create_name`(root_name)	Modify file name if a file with that name already exists.
`debug_wrapper`(func)	A decorator that wraps a function with error handling
`fig_layout`(subID, nPan[, vertical_page])	Return figure layout.
`filter_input`(txt[, typeIn])	Read template for the type of data expected.
`format_lon_lat`(lon_lat, type)	Format latitude and longitude as labels (e.g., 30°S, 30°N, 45°W,
`get_Ncdf_num`()	Return the prefix numbers for the netCDF files in the directory.
`get_figure_header`(line_txt)	Returns the plot type by confirming that template = `True`.
`get_lat_index`(lat_query, lats)	Returns the indices for a range of latitudes in a file.
`get_level_index`(level_query, levs)	Returns the indices for a range of pressures in a file.
`get_list_varfull`(raw_input)	Return requested variable from a complex `varfull` object with `[]`.
`get_lon_index`(lon_query_180, lons)	Returns the indices for a range of longitudes in a file.
`get_overwrite_dim_1D`(varfull_bracket, t_in, lat_in, ...)	1D plot: overwrite dimensions in `varfull` object with `{}`.
`get_overwrite_dim_2D`(varfull_bracket, plot_type, ...)	2D plot: overwrite dimensions in `varfull` object with `{}`.
`get_time_index`(Ls_query_360, LsDay)	Returns the indices for a range of solar longitudes in a file.
`get_tod_index`(tod_query, tods)	Returns the indices for a range of times of day in a file.
`give_permission`(filename)	Sets group permissions for files created on NAS.
`main`()	Main entry point for the MarsPlot script.
`make_template`()	Generate the `Custom.in` template file.
`mean_func`(arr, axis)	Calculate the mean of an array along a specified axis.
`namelist_parser`(Custom_file)	Parse a `Custom.in` template.
`prep_file`(var_name, file_type, simuID, sol_array)	Open the file as a Dataset or MFDataset object depending on its
`progress`(k, Nmax[, txt, success])	Display a progress bar when performing heavy calculations.
`rT`([typeIn])	Read template for the type of data expected.
`read_axis_options`(axis_options_txt)	Return axis customization options.
`remove_whitespace`(raw_input)	Remove whitespace inside an expression.
`select_range`(Ncdf_num, bound)	Return the prefix numbers for the netCDF files in the directory
`shift_data`(lon, data)	Shifts the longitude data from 0-360 to -180/180 and vice versa.
`split_varfull`(varfull)	Split `varfull` object into its component parts

Attributes

`add_sol_time_axis`
`args`
`current_version`
`debug`
`degr`
`exit_code`
`include_NaNs`
`lon_coord_type`
`namespace`
`parser`

class CustomTicker(base=10.0, labelOnlyBase=False, minor_thresholds=None, linthresh=None)

Bases: matplotlib.ticker.LogFormatterSciNotation

Format values following scientific notation in a logarithmic axis.

axis

locs = []

__call__(x, pos=None): Return the format for tick value x at position pos. pos=None indicates an unspecified location.

create_dummy_axis(**kwargs)

static fix_minus(s): Some classes may want to replace a hyphen for minus with the proper Unicode symbol (U+2212) for typographical correctness. This is a helper method to perform such a replacement when it is enabled via axes.unicode_minus.

format_data(value): Return the full string representation of the value with the position unspecified.

format_data_short(value)

Return a short string version of the tick value.

Defaults to the position-independent long value.

format_ticks(values): Return the tick labels for all the ticks at once.

get_offset()

set_axis(axis)

set_base(base): Change the base for labeling.

Warning

Should always match the base used for LogLocator

set_label_minor(labelOnlyBase)

Switch minor tick labeling on or off.

Parameters

labelOnlyBasebool: If True, label ticks only at integer powers of base.

set_locs(locs=None)

Use axis view limits to control which ticks are labeled.

The locs parameter is ignored in the present algorithm.

class Fig_1D(varfull='atmos_average.ts', doPlot=True)

Bases: object

Fig_1D is a parent class for generating and handling 1D plots of Mars atmospheric data.

Attributes:

titlestr: Title of the plot.
legendstr: Legend label for the plot.
varfullstr: Full variable specification, including file and variable name.
tstr or float: Time axis or identifier for the varying dimension.
latfloat or str: Latitude value or identifier.
lonfloat or str: Longitude value or identifier.
levfloat or str: Vertical level value or identifier.
ftodfloat or str: Time of day requested.
hourfloat or str: Hour of day, used for diurnal plots.
doPlotbool: Whether to generate the plot.
plot_typestr: Type of 1D plot (e.g., “1D_time”, “1D_lat”).
sol_arraystr: Sol array extracted from varfull.
filetypestr: File type extracted from varfull.
varstr: Variable name extracted from varfull.
simuIDstr: Simulation ID extracted from varfull.
nPanint: Number of panels in the plot.
subIDint: Subplot ID.
addLinebool: Whether to add a line to an existing plot.
layoutlist or None: Page layout for multipanel plots.
fdim_txtstr: Annotation for free dimensions.
successbool: Indicates if the plot was successfully created.
vert_unitstr: Vertical unit, either “m” or “Pa”.
Dlimlist or None: Dimension limits for the axis.
Vlimlist or None: Variable limits for the axis.
axis_opt1str: Line style or axis option.
axis_opt2str: Additional axis option (optional).

Methods:

make_template():: Writes a template for the plot configuration to a file.
read_template():: Reads plot configuration from a template file.
get_plot_type():: Determines the type of 1D plot to create based on which dimension is set to “AXIS” or -88888.
data_loader_1D(varfull, plot_type):: Loads 1D data for plotting, handling variable expressions and dimension overwrites.

read_NCDF_1D(var_name, file_type, simuID, sol_array, plot_type, t_req, lat_req, lon_req, lev_req, ftod_req):

Reads and processes 1D data from a NetCDF file for the specified variable and dimensions.

exception_handler(e, ax):: Handles exceptions during plotting, displaying an error message on the plot.
fig_init():: Initializes the figure and subplot for plotting.
fig_save():: Saves the generated figure to disk.
do_plot():: Main method to generate the 1D plot, handling all plotting logic and exceptions.

data_loader_1D(varfull, plot_type)

do_plot()

exception_handler(e, ax)

fig_init()

fig_save()

get_plot_type()

Note that the self.t == "AXIS" test and the self.t = -88888 assignment are only used when MarsPlot is not passed a template.

Returns:: type of 1D plot to create (1D_time, 1D_lat, etc.)

make_template()

read_NCDF_1D(var_name, file_type, simuID, sol_array, plot_type, t_req, lat_req, lon_req, lev_req, ftod_req)

Parse a Main Variable expression object that includes a square bracket [] (for variable calculations) for the variable to plot.

Parameters:

var_name (str) – variable name (e.g., temp)
file_type (str) – MGCM output file type. Must be fixed or average
simuID (str) – number identifier for netCDF file directory
sol_array (str) – sol if different from default (e.g., 02400)
plot_type (str) – 1D_lon, 1D_lat, 1D_lev, or 1D_time
t_req (str) – Ls requested
lat_req (str) – lat requested
lon_req (str) – lon requested
lev_req (str) – level [Pa/m] requested
ftod_req (str) – time of day requested

Returns:

(dim_array) the axis (e.g., an array of longitudes), (var_array) the variable extracted

read_template()

class Fig_2D(varfull='fileYYY.XXX', doPlot=False, varfull2=None)

Bases: object

Base class for 2D figures. This class is not intended to be instantiated directly. Instead, it is used as a base class for specific 2D figure classes (e.g., Fig_2D_lon_lat, Fig_2D_time_lat, Fig_2D_lat_lev, etc.). It provides common attributes and methods for all 2D figures, such as the variable name, file type, simulation ID, and plotting options. The class also includes methods for creating a template for the figure, reading the template from a file, and loading data for 2D plots. The class is designed to be extended by subclasses that implement specific plotting functionality for different types of 2D figures.

Parameters:

varfull (str) – full variable name (e.g., fileYYY.XXX)
doPlot (bool) – whether to plot the figure (default: False)
varfull2 (str) – second variable name (default: None)

Returns:

None

Return type:

None

Raises:

ValueError – If the input varfull is not a valid type for variable name.
TypeError – If the input doPlot is not a valid type for plotting.
Exception – If the input varfull2 is not a valid type for variable name.

data_loader_2D(varfull, plot_type)

exception_handler(e, ax)

fig_init()

fig_save()

filled_contour(xdata, ydata, var)

make_colorbar(levs)

make_template(plot_txt, fdim1_txt, fdim2_txt, Xaxis_txt, Yaxis_txt)

make_title(var_info, xlabel, ylabel)

plot_dimensions()

read_NCDF_2D(var_name, file_type, simuID, sol_array, plot_type, fdim1, fdim2, ftod)

read_template()

return_norm_levs()

solid_contour(xdata, ydata, var, contours)

class Fig_2D_lat_lev(varfull='fileYYY.XXX', doPlot=False, varfull2=None)

Bases: Fig_2D

A subclass of Fig_2D for generating 2D plots with latitude and vertical level (pressure or altitude) axes.

This class customizes the plotting template and plotting logic for visualizing data as a function of latitude and vertical level. It supports filled contour plots for a primary variable, and optionally overlays solid contour lines for a secondary variable.

Methods:

make_template():: Sets up the plot template with appropriate titles and axis labels for latitude vs. level plots.
do_plot():: Loads data, creates a filled contour plot of the primary variable, optionally overlays contours of a secondary variable, configures axis scaling and formatting (including logarithmic pressure axis if needed), sets axis limits and tick formatting, handles exceptions, and saves the resulting figure.

Attributes (inherited and/or used):

varfullstr: Name of the primary variable to plot.
varfull2str or None: Name of the secondary variable to overlay as contours, if any.
plot_typestr: Type of plot or data selection.
vert_unitstr: Unit for the vertical axis (“Pa” for pressure, otherwise altitude in meters).
Xlimtuple or None: Limits for the x-axis (latitude).
Ylimtuple or None: Limits for the y-axis (level).
contour2list or None: Contour levels for the secondary variable.
nPanint: Number of panels in the plot (affects tick label size).
successbool: Indicates if the plot was successfully created.

data_loader_2D(varfull, plot_type)

do_plot()

Generates a 2D latitude-level plot for the specified variable(s). This method initializes the figure, loads the required data, and creates a filled contour plot of the primary variable. If a secondary variable is specified, it overlays solid contours for that variable. The y-axis is set to logarithmic scale and inverted if the vertical unit is pressure. Axis limits, labels, and tick formatting are applied as specified by the instance attributes. The plot title is generated based on the variable information. Handles exceptions during plotting and saves the resulting figure.

Raises:: Exception: Any exception encountered during plotting is handled and logged.

exception_handler(e, ax)

fig_init()

fig_save()

filled_contour(xdata, ydata, var)

make_colorbar(levs)

make_template()

Creates and configures a plot template for a 2D latitude versus level plot. This method calls the parent class’s make_template method with predefined titles and axis labels suitable for a plot displaying latitude against atmospheric level data. The plot is labeled as “Plot 2D lat X lev” with the following axis labels:

X-axis: “Ls 0-360 “

Y-axis: “Lon +/-180”

Additional axes: “Lat”, “Level[Pa/m]”

Returns:: None

make_title(var_info, xlabel, ylabel)

plot_dimensions()

read_NCDF_2D(var_name, file_type, simuID, sol_array, plot_type, fdim1, fdim2, ftod)

read_template()

return_norm_levs()

solid_contour(xdata, ydata, var, contours)

class Fig_2D_lon_lat(varfull='fileYYY.XXX', doPlot=False, varfull2=None)

Bases: Fig_2D

Fig_2D_lon_lat is a class for creating 2D longitude-latitude plots.

Fig_2D_lon_lat is a subclass of Fig_2D designed for generating 2D plots of longitude versus latitude, primarily for visualizing Mars climate data. It provides methods for figure creation, data loading, plotting, and overlaying topography contours, with support for various map projections and customization options.

Attributes:

varfull (str): Full variable name (e.g., “fileYYY.XXX”) to plot. doPlot (bool): Whether to plot the figure (default: False). varfull2 (str, optional): Second variable name for overlaying

contours (default: None).

plot_type (str): Type of plot (default: “2D_lon_lat”). fdim1 (str, optional): First free dimension (default: None). fdim2 (str, optional): Second free dimension (default: None). ftod (str, optional): Time of day (default: None). axis_opt1 (str, optional): First axis option, e.g., colormap

(default: None).

axis_opt2 (str, optional): Second axis option (default: None). axis_opt3 (str, optional): Projection type (e.g., “cart”,

“robin”, “moll”, “Npole”, “Spole”, “ortho”).

Xlim (tuple, optional): Longitude axis limits. Ylim (tuple, optional): Latitude axis limits. range (bool, optional): Whether to use a specified range for

color levels.

contour2 (float or list, optional): Contour levels for the: second variable.

title (str, optional): Custom plot title. nPan (int): Number of panels (for multi-panel plots). fdim_txt (str): Text describing free dimensions. success (bool): Status flag indicating if plotting succeeded.

Methods:

make_template():: Sets up the plot template with appropriate axis labels and titles.
get_topo_2D(varfull, plot_type):: Loads and returns topography data (zsurf) for overlaying as contours, matching the simulation and file type of the main variable.
do_plot():: Main plotting routine. Loads data, applies projection, overlays topography and optional second variable contours, customizes axes, and saves the figure. Handles both standard and special map projections (cartesian, Robinson, Mollweide, polar, orthographic).

Usage:

This class is intended to be used within the MarsPlot software for visualizing Mars climate model outputs as longitude-latitude maps, with optional overlays and advanced projection support.

data_loader_2D(varfull, plot_type)

do_plot()

Generate a 2D longitude-latitude plot with various projection options and optional overlays.

This method creates a 2D plot of a variable (and optionally a second variable as contours) on a longitude-latitude grid. It supports multiple map projections, including cartesian, Robinson, Mollweide, and azimuthal (north pole, south pole, orthographic) projections. Topography contours can be added if available. The method handles axis formatting, colorbars, titles, and annotation of meridians and parallels.

The plotting behavior is controlled by instance attributes such as:

self.varfull: Main variable to plot.
self.varfull2: Optional second variable for contour overlay.
self.plot_type: Type of plot to generate.
self.axis_opt1: Colormap or colormap option.
self.axis_opt3: Projection type.
self.contour2: Contour levels for the second variable.
self.Xlim, self.Ylim: Axis limits for cartesian projection.
self.range: Whether to use a specific range for color levels.
self.title: Custom plot title.
self.fdim_txt: Additional dimension text for the title.
self.nPan: Panel index for multi-panel plots.

The method handles exceptions and saves the figure upon completion.

Raises:: Exception: Any error encountered during plotting is handled and reported.

exception_handler(e, ax)

fig_init()

fig_save()

filled_contour(xdata, ydata, var)

get_topo_2D(varfull, plot_type)

This function returns the longitude, latitude, and topography to overlay as contours in a 2D_lon_lat plot. Because the main variable requested may be complex (e.g., [01336.atmos_average_psdt2.temp]/1000.), we will ensure to load the matching topography (here 01336.fixed.nc from the 2nd simulation). This function essentially does a simple task in a complicated way. Note that a great deal of the code is borrowed from the data_loader_2D() function.

Parameters:

varfull (str) – variable input to main_variable in Custom.in (e.g., 03340.atmos_average.ucomp)
plot_type (str) – plot type (e.g., Plot 2D lon X time)

Returns:

topography or None if no matching fixed file

make_colorbar(levs)

make_template()

Creates and configures a plot template for 2D longitude vs latitude data. This method calls the parent class’s make_template method with predefined parameters to set up the plot title and axis labels specific to a 2D longitude-latitude plot. The template includes:

Title: “Plot 2D lon X lat”

X-axis label: “Ls 0-360”

Y-axis label: “Level Pa/m”

Additional axis labels: “Lon” (longitude), “Lat” (latitude)

make_title(var_info, xlabel, ylabel)

plot_dimensions()

read_NCDF_2D(var_name, file_type, simuID, sol_array, plot_type, fdim1, fdim2, ftod)

read_template()

return_norm_levs()

solid_contour(xdata, ydata, var, contours)

class Fig_2D_lon_lev(varfull='fileYYY.XXX', doPlot=False, varfull2=None)

Bases: Fig_2D

A subclass of Fig_2D for generating 2D plots with longitude and vertical level (pressure or altitude) axes.

This class customizes the template and plotting routines to visualize data as a function of longitude and vertical level. It supports plotting filled contours for a primary variable and optional solid contours for a secondary variable. The vertical axis can be displayed in pressure (Pa, logarithmic scale) or altitude (m).

Methods:

make_template():: Sets up the plot template with appropriate titles and axis labels for longitude vs. level plots.
do_plot():: Loads data, applies longitude shifting, creates filled and optional solid contour plots, configures axis scales and labels, and handles exceptions during plotting.

data_loader_2D(varfull, plot_type)

do_plot()

Generates a 2D plot of a variable as a function of longitude and vertical level (pressure or altitude).

This method initializes the figure, loads the required data, applies longitude shifting, and creates filled and/or solid contour plots.

It handles plotting of a secondary variable if specified, sets axis scales and labels based on the vertical coordinate unit, applies axis limits if provided, customizes tick formatting and font sizes, and manages exceptions during plotting. The resulting figure is saved to file.

Raises:: Exception: If any error occurs during the plotting process, it is handled and logged by the exception handler.

exception_handler(e, ax)

fig_init()

fig_save()

filled_contour(xdata, ydata, var)

make_colorbar(levs)

make_template()

Creates and configures a plot template for 2D lon x lev data.

This method sets up the plot with predefined titles and axis labels: - Title: “Plot 2D lon X lev” - X-axis: “Ls 0-360” - Y-axis: “Latitude” - Additional labels: “Lon +/-180” and “Level[Pa/m]”

Overrides the base class method to provide specific configuration for this plot type.

make_title(var_info, xlabel, ylabel)

plot_dimensions()

read_NCDF_2D(var_name, file_type, simuID, sol_array, plot_type, fdim1, fdim2, ftod)

read_template()

return_norm_levs()

solid_contour(xdata, ydata, var, contours)

class Fig_2D_lon_time(varfull='fileYYY.XXX', doPlot=False, varfull2=None)

Bases: Fig_2D

A specialized 2D plotting class for visualizing data as a function of longitude and time (Ls).

Inherits from: Fig_2D

Methods:

make_template():: Sets up the plot template with appropriate titles and axis labels for longitude vs. time plots.
do_plot():: Generates a 2D plot with longitude on the x-axis and solar longitude (Ls) on the y-axis. Loads and processes data, applies shifting if necessary, and creates filled and/or solid contours. Handles axis formatting, tick labeling (including optional sol time annotation), and plot saving. Catches and handles exceptions during plotting.

data_loader_2D(varfull, plot_type)

do_plot()

exception_handler(e, ax)

fig_init()

fig_save()

filled_contour(xdata, ydata, var)

make_colorbar(levs)

make_template()

make_title(var_info, xlabel, ylabel)

plot_dimensions()

read_NCDF_2D(var_name, file_type, simuID, sol_array, plot_type, fdim1, fdim2, ftod)

read_template()

return_norm_levs()

solid_contour(xdata, ydata, var, contours)

class Fig_2D_time_lat(varfull='fileYYY.XXX', doPlot=False, varfull2=None)

Bases: Fig_2D

A 2D plotting class for visualizing data as a function of time (Ls) and latitude. Inherits from: Fig_2D

Methods:

make_template():: Sets up the plot template with appropriate titles and axis labels for a 2D time vs latitude plot.
do_plot():: Loads 2D data (time and latitude), creates a filled contour plot of the primary variable, and optionally overlays a solid contour of a secondary variable. Formats axes, customizes tick labels to show both Ls and sol time (if enabled), and applies axis limits if specified. Handles exceptions during plotting and saves the resulting figure.

Attributes (inherited and used):

varfullstr: Name of the primary variable to plot.
varfull2str or None: Name of the secondary variable to overlay as contours (optional).
plot_typestr: Type of plot/data to load.
Xlimtuple or None: Limits for the x-axis (sol time).
Ylimtuple or None: Limits for the y-axis (latitude).
contour2list or None: Contour levels for the secondary variable.
nPanint: Number of panels (used for label sizing).
successbool: Indicates if the plot was successfully created.

data_loader_2D(varfull, plot_type)

do_plot()

Generates a 2D time-latitude plot for the specified variable(s). This method initializes the figure, loads the required 2D data arrays (time and latitude), and creates a filled contour plot of the primary variable. If a secondary variable is specified, it overlays solid contours for that variable. The method also formats the axes, including custom tick labels for solar longitude (Ls) and optionally sol time, and applies axis limits if specified. Additional plot formatting such as tick intervals and font sizes are set. The plot is saved at the end of the method. Any exceptions encountered during plotting are handled and reported.

Raises:: Exception: If any error occurs during the plotting process, it is handled and reported.

exception_handler(e, ax)

fig_init()

fig_save()

filled_contour(xdata, ydata, var)

make_colorbar(levs)

make_template()

Creates and configures a plot template for a 2D time versus latitude figure. This method calls the superclass’s make_template method with predefined titles and axis labels suitable for a plot displaying data across longitude, level, solar longitude (Ls), and latitude.

Returns:: None

make_title(var_info, xlabel, ylabel)

plot_dimensions()

read_NCDF_2D(var_name, file_type, simuID, sol_array, plot_type, fdim1, fdim2, ftod)

read_template()

return_norm_levs()

solid_contour(xdata, ydata, var, contours)

class Fig_2D_time_lev(varfull='fileYYY.XXX', doPlot=False, varfull2=None)

Bases: Fig_2D

A specialized 2D plotting class for visualizing data as a function of time (Ls) and vertical level (pressure or altitude).

Inherits from: Fig_2D

Methods:

make_template():: Sets up the plot template with appropriate axis labels and titles for 2D time vs. level plots.
do_plot():: Loads data and generates a filled contour plot of the primary variable as a function of solar longitude (Ls) and vertical level. Optionally overlays a solid contour of a secondary variable. Handles axis formatting, tick labeling (including optional sol time axis), and y-axis scaling (logarithmic for pressure). Sets plot titles and saves the figure. Catches and handles exceptions during plotting.

Attributes (inherited and/or used):

varfullstr: Name of the primary variable to plot.
varfull2str or None: Name of the secondary variable to overlay as contours (optional).
plot_typestr: Type of plot/data selection.
Xlimtuple or None: Limits for the x-axis (solar day).
Ylimtuple or None: Limits for the y-axis (vertical level).
vert_unitstr: Unit for the vertical axis (“Pa” for pressure or other for altitude).
nPanint: Number of panels/subplots (affects label size).
contour2list or None: Contour levels for the secondary variable.
successbool: Indicates if the plot was successfully generated.

data_loader_2D(varfull, plot_type)

do_plot()

Generates a 2D time-level plot for Mars atmospheric data.

This method initializes the figure, loads the required data, and creates a filled contour plot of the primary variable over solar longitude (Ls) and pressure or altitude. If a secondary variable is specified, it overlays solid contours for that variable. The method also formats axes, applies custom tick labels (optionally including sol time), and adjusts axis scales and labels based on the vertical unit (pressure or altitude). The plot is titled and saved to file. Handles exceptions by invoking a custom exception handler and always attempts to save the figure.

Attributes used:: varfull (str): Name of the primary variable to plot. plot_type (str): Type of plot/data to load. varfull2 (str, optional): Name of the secondary variable for contour overlay. contour2 (list, optional): Contour levels for the secondary variable. Xlim (tuple, optional): Limits for the x-axis (solar day). Ylim (tuple, optional): Limits for the y-axis (pressure or altitude). vert_unit (str): Vertical axis unit, either “Pa” for pressure or other for altitude. nPan (int): Number of panels (affects label size). success (bool): Set to True if plotting succeeds.
Raises:: Handles all exceptions internally and logs them via a custom handler.

exception_handler(e, ax)

fig_init()

fig_save()

filled_contour(xdata, ydata, var)

make_colorbar(levs)

make_template()

Creates and configures a plot template for 2D time versus level visualization. This method calls the superclass’s make_template method with predefined titles and axis labels suitable for plotting data with latitude, longitude, solar longitude (Ls), and atmospheric level (in Pa/m).

Returns:: None

make_title(var_info, xlabel, ylabel)

plot_dimensions()

read_NCDF_2D(var_name, file_type, simuID, sol_array, plot_type, fdim1, fdim2, ftod)

read_template()

return_norm_levs()

solid_contour(xdata, ydata, var, contours)

MY_func(Ls_cont)

Returns the Mars Year.

Parameters:: Ls_cont (array [areo]) – solar longitude (areo; continuous)
Returns:: the Mars year
Return type:: int
Raises:: ValueError – If the input Ls_cont is not a valid type for year calculation.

clean_comma_whitespace(raw_input)

Remove commas and whitespaces inside an expression.

Parameters:: raw_input (str) – dimensions specified by user input to Variable (e.g., lat=3. , lon=2 , lev = 10.)
Returns:: raw_input without whitespaces (e.g., lat=3.,lon=2,lev=10.)
Return type:: str

create_exec(raw_input, varfull_list)

create_name(root_name)

Modify file name if a file with that name already exists.

Parameters:

root_name (str) – path + default name for the file type (e.g., /path/custom.in or /path/figure.png)

Returns:

the modified name if the file already exists (e.g., /path/custom_01.in or /path/figure_01.png)

Return type:

str

Raises:

ValueError – If the input root_name is not a valid type for file name.
TypeError – If the input root_name is not a valid type for file name.
Exception – If the file name creation fails for any reason.

debug_wrapper(func)

A decorator that wraps a function with error handling based on the –debug flag. If the –debug flag is set, it prints the full traceback of any exception that occurs. Otherwise, it prints a simplified error message.

Parameters:

func (function) – The function to wrap.

Returns:

The wrapped function.

Return type:

function

Raises:

Exception – If an error occurs during the function call.
TypeError – If the function is not callable.
ValueError – If the function is not found.
NameError – If the function is not defined.
AttributeError – If the function does not have the specified attribute.
ImportError – If the function cannot be imported.
RuntimeError – If the function cannot be run.
KeyError – If the function does not have the specified key.
IndexError – If the function does not have the specified index.
IOError – If the function cannot be opened.
OSError – If the function cannot be accessed.
EOFError – If the function cannot be read.
MemoryError – If the function cannot be allocated.
OverflowError – If the function cannot be overflowed.
ZeroDivisionError – If the function cannot be divided by zero.
StopIteration – If the function cannot be stopped.
KeyboardInterrupt – If the function cannot be interrupted.
SystemExit – If the function cannot be exited.
AssertionError – If the function cannot be asserted.

fig_layout(subID, nPan, vertical_page=False)

Return figure layout.

Parameters:

subID (int) – current subplot number
nPan (int) – number of panels desired on page (max = 64, 8x8)
vertical_page (bool) – reverse the tuple for portrait format if True

Returns:

plot layout (e.g., plt.subplot(nrows = out[0], ncols = out[1], plot_number = out[2]))

Return type:

tuple

Raises:

ValueError – If the input subID is not a valid type for subplot number.
TypeError – If the input nPan is not a valid type for subplot number.
Exception – If the input vertical_page is not a valid type for subplot number.
Exception – If the figure layout calculation fails for any reason.

filter_input(txt, typeIn='char')

Read template for the type of data expected.

Returns value to rT().

Parameters:

txt (str) – text input into Custom.in to the right of an equal sign
typeIn (str, optional) – type of data expected: char, float, int, bool, defaults to char

Returns:

text input reformatted to [val1, val2]

Return type:

float or array

Raises:

ValueError – If the input txt is not a valid type for filtering.
TypeError – If the input typeIn is not a valid type for filtering.
Exception – If the filtering operation fails for any reason.

format_lon_lat(lon_lat, type)

Format latitude and longitude as labels (e.g., 30°S, 30°N, 45°W, 45°E)

Parameters:

lon_lat (float) – latitude or longitude (+180/-180)
type (str) – lat or lon

Returns:

formatted label

Return type:

str

Raises:

ValueError – If the input lon_lat is not a valid type for latitude or longitude.
TypeError – If the input type is not a valid type for latitude or longitude.
Exception – If the formatting fails for any reason.

get_Ncdf_num()

Return the prefix numbers for the netCDF files in the directory. Requires at least one fixed file in the directory.

Returns:: a sorted array of sols
Return type:: array
Raises:: ValueError – If the input input_paths is not a valid type for file name.

get_figure_header(line_txt)

Returns the plot type by confirming that template = True.

Parameters:

line_txt (str) – template header from Custom.in (e.g., <<<<<<<<<| Plot 2D lon X lat = True |>>>>>>>>)

Returns:

(figtype) figure type (e.g., Plot 2D lon X lat)

Return type:

str

Returns:

(boolPlot) whether to plot (True) or skip (False) figure

Return type:

bool

Raises:

ValueError – If the input line_txt is not a valid type for figure header.
TypeError – If the input line_txt is not a valid type for figure header.
Exception – If the figure header parsing fails for any reason.

get_lat_index(lat_query, lats)

Returns the indices for a range of latitudes in a file.

Parameters:

lat_query (list) – requested latitudes (-90/+90)
lats (array [lat]) – latitude

Returns:

1d array of file indices

Return type:

text descriptor for the extracted longitudes

Return type:

str

Raises:

ValueError – If the input lat_query is not a valid type for latitude calculation.

get_level_index(level_query, levs)

Returns the indices for a range of pressures in a file.

Parameters:

level_query (float) – requested pressure [Pa] (depth [m])
levs (array [lev]) – levels (in the native coordinates)

Returns:

file indices

Return type:

array

Returns:

descriptor for the extracted pressure (depth)

Return type:

str

Raises:

ValueError – If the input level_query is not a valid type for level calculation.

Note

The keyword all is passed as -99999 by the rT() functions

get_list_varfull(raw_input)

Return requested variable from a complex varfull object with [].

Parameters:: raw_input (str) – complex user input to Variable (e.g., 2*[atmos_average.temp]+[atmos_average2.ucomp]*1000)
Returns:: list required variables (e.g., [atmos_average.temp, atmos_average2.ucomp])
Return type:: str
Raises:: ValueError – If the input raw_input is not a valid type for variable extraction.

get_lon_index(lon_query_180, lons)

Returns the indices for a range of longitudes in a file.

Parameters:

lon_query_180 (list) – longitudes in -180/180: value, [min, max], or None
lons (array [lon]) – longitude in 0-360

Returns:

1D array of file indices

Return type:

array

Returns:

text descriptor for the extracted longitudes

Return type:

str

Raises:

ValueError – If the input lon_query_180 is not a valid type for longitude calculation.

Note

The keyword all passed as -99999 by the rT() functions

get_overwrite_dim_1D(varfull_bracket, t_in, lat_in, lon_in, lev_in, ftod_in)

1D plot: overwrite dimensions in varfull object with {}.

(e.g., atmos_average.temp{lev=10;ls=350;lon=155;lat=25}) This function is used to overwrite the default dimensions in a varfull object with {} (e.g., atmos_average.temp{lev=10; ls=350;lon=155;lat=25}) for a 1D plot. The function will return the new dimensions that will overwrite the default dimensions for the varfull object. The function will also return the required file and variable (e.g., atmos_average.temp) and the X and Y axis dimensions for the plot.

Parameters:

varfull_bracket (str) – a varfull object with {} (e.g., atmos_average.temp{lev=10;ls=350;lon=155;lat=25})
t_in (array [time]) – self.t variable
lat_in (array [lat]) – self.lat variable
lon_in (array [lon]) – self.lon variable
lev_in (array [lev]) – self.lev variable
ftod_in (array [tod]) – self.ftod variable

Returns:

varfull object without brackets (e.g., atmos_average.temp);

Returns:

(t_out) dimension to update;

Returns:

(lat_out) dimension to update;

Returns:

(lon_out) dimension to update;

Returns:

(lev_out) dimension to update;

Returns:

(ftod_out) dimension to update;

Return type:

str

Raises:

ValueError – If the input varfull_bracket is not a valid type for variable extraction.
TypeError – If the input t_in, lat_in, lon_in, lev_in, ftod_in are not valid types for variable extraction.
Exception – If the variable extraction fails for any reason.

Note

This function is used for 1D plots only. The function will return the new dimensions that will overwrite the default dimensions for the varfull object. The function will also return the required file and variable (e.g., atmos_average.temp) and the X and Y axis dimensions for the plot.

get_overwrite_dim_2D(varfull_bracket, plot_type, fdim1, fdim2, ftod)

2D plot: overwrite dimensions in varfull object with {}.

(e.g., atmos_average.temp{lev=10;ls=350;lon=155;lat=25})

This function is used to overwrite the default dimensions in a varfull object with {} (e.g., atmos_average.temp{lev=10; ls=350;lon=155;lat=25}) for a 2D plot. The function will return the new dimensions that will overwrite the default dimensions for the varfull object. The function will also return the required file and variable (e.g., atmos_average.temp) and the X and Y axis dimensions for the plot.

2D_lon_lat: fdim1 = ls, fdim2 = lev 2D_lat_lev: fdim1 = ls, fdim2 = lon 2D_time_lat: fdim1 = lon, fdim2 = lev 2D_lon_lev: fdim1 = ls, fdim2 = lat 2D_time_lev: fdim1 = lat, fdim2 = lon 2D_lon_time: fdim1 = lat, fdim2 = lev

Parameters:

varfull_bracket (str) – a varfull object with {} (e.g., atmos_average.temp{lev=10;ls=350;lon=155;lat=25})
plot_type (str) – the type of the plot template
fdim1 (str) – X axis dimension for plot
fdim2 (str) – Y axis dimension for plot

Returns:

(varfull) required file and variable (e.g., atmos_average.temp); (fdim_out1) X axis dimension for plot; (fdim_out2) Y axis dimension for plot; (ftod_out) if X or Y axis dimension is time of day

Return type:

str

Raises:

ValueError – If the input varfull_bracket is not a valid type for variable extraction.
TypeError – If the input plot_type is not a valid type for variable extraction.
Exception – If the variable extraction fails for any reason.

get_time_index(Ls_query_360, LsDay)

Returns the indices for a range of solar longitudes in a file.

First try the Mars Year of the last timestep, then try the year before that. Use whichever Ls period is closest to the requested date.

Parameters:

Ls_query_360 (list) – requested solar longitudes
LsDay (array [areo]) – continuous solar longitudes

Returns:

file indices

Return type:

array

Returns:

descriptor for the extracted solar longitudes

Return type:

str

Raises:

ValueError – If the input Ls_query_360 is not a valid type for solar longitude calculation.
TypeError – If the input LsDay is not a valid type for solar longitude calculation.
Exception – If the time index calculation fails for any reason.

Note

The keyword all is passed as -99999 by the rT() function

get_tod_index(tod_query, tods)

Returns the indices for a range of times of day in a file.

Parameters:

tod_query (list) – requested time of day (0-24)
tods (array [tod]) – times of day

Returns:

file indices

Return type:

array [tod]

Returns:

descriptor for the extracted time of day

Return type:

str

Raises:

ValueError – If the input tod_query is not a valid type for time of day calculation.

Note

The keyword all is passed as -99999 by the rT() function

give_permission(filename)

Sets group permissions for files created on NAS.

Parameters:: filename (str) – name of the file
Raises:: ValueError – If the input filename is not a valid type for file name.

main()

Main entry point for the MarsPlot script.

Handles argument parsing, global variable setup, figure object initialization, and execution of the main plotting workflow. Depending on the provided arguments, this function can:

Inspect the contents of a NetCDF file and print variable

information or statistics. - Generate a template configuration file. - Parse a provided template file, select data based on optional date bounds, and generate

diagnostic plots as individual files or as a merged multipage PDF.

Manage output directories and file naming conventions.

Display progress and handle debug output.

Global variables are set for configuration and figure formatting. The function also manages error handling and user feedback for invalid arguments or file operations.

make_template()

Generate the Custom.in template file.

Returns:

Custom.in blank template

Return type:

file

Raises:

ValueError – If the input customFileIN is not a valid type for template generation.
TypeError – If the input customFileIN is not a valid type for template generation.
Exception – If the template generation fails for any reason.

mean_func(arr, axis)

Calculate the mean of an array along a specified axis.

This function calculates a mean over the selected axis, ignoring or including NaN values as specified by show_NaN_in_slice in amescap_profile.

Parameters:

arr (array) – the array to be averaged
axis (int) – the axis over which to average the array

Returns:

the mean over the time axis

Return type:

array

Raises:

ValueError – If the array is empty or the axis is out of bounds.
RuntimeWarning – If the mean calculation encounters NaN values.
TypeError – If the input array is not a valid type for mean calculation.
Exception – If the mean calculation fails for any reason.

namelist_parser(Custom_file)

Parse a Custom.in template.

Parameters:: Custom_file (str) – full path to Custom.in file
Returns:: updated global variables, FigLayout, objectList panelList, subplotList, addLineList, layoutList
Return type:: list
Raises:: ValueError – If the input Custom_file is not a valid type for file name.

prep_file(var_name, file_type, simuID, sol_array)

Open the file as a Dataset or MFDataset object depending on its status on Lou. Note that the input arguments are typically extracted from a varfull object (e.g., 03340.atmos_average.ucomp) and not from a file whose disk status is known beforehand.

Parameters:

var_name (str) – variable to extract (e.g., ucomp)
file_type – MGCM output file type (e.g., average)
simuID (int) – simulation ID number (e.g., 2 for 2nd simulation)
sol_array (list) – date in file name (e.g., [3340,4008])

Returns:

Dataset or MFDataset object;

Returns:

(var_info) longname and units;

Returns:

(dim_info) dimensions e.g., (time, lat,``lon``);

Returns:

(dims) shape of the array e.g., [133,48,96]

Return type:

Dataset or MFDataset object, str, tuple, list

Raises:

ValueError – If the input var_name is not a valid type for variable name.
TypeError – If the input file_type is not a valid type for file type.
Exception – If the file preparation fails for any reason.
IOError – If the file is not found or cannot be opened.

progress(k, Nmax, txt='', success=True)

Display a progress bar when performing heavy calculations.

Parameters:

k (float) – current iteration of the outer loop
Nmax (float) – max iteration of the outer loop

Returns:

progress bar (EX: Running... [#---------] 10.64 %)

Return type:

str

Raises:

ValueError – If the input k is not a valid type for progress bar.
TypeError – If the input Nmax is not a valid type for progress bar.
Exception – If the progress bar creation fails for any reason.

rT(typeIn='char')

Read template for the type of data expected.

Returns value to filter_input().

Parameters:

typeIn (str, optional) – type of data expected: char, float, int, bool, defaults to char

Returns:

text input reformatted to [val1, val2]

Return type:

float or array

Raises:

ValueError – If the input typeIn is not a valid type for filtering.
TypeError – If the input typeIn is not a valid type for filtering.
Exception – If the filtering operation fails for any reason.

read_axis_options(axis_options_txt)

Return axis customization options.

Parameters:: axis_options_txt (str) – a copy of the last line Axis Options in Custom.in templates
Returns:: X-axis bounds as a numpy array or None if undedefined
Return type:: array or None
Returns:: Y-axis bounds as a numpy array or None if undedefined
Return type:: array or None
Returns:: colormap (e.g., jet, nipy_spectral) or line options (e.g., --r for dashed red)
Return type:: str
Returns:: linear (lin) or logarithmic (log) color scale
Return type:: str
Returns:: projection (e.g., ortho -125,45)
Return type:: str
Raises:: ValueError – If the input axis_options_txt is not a valid type for axis options.

remove_whitespace(raw_input)

Remove whitespace inside an expression.

This is different from the .strip() method, which only removes whitespaces at the edges of a string.

Parameters:: raw_input (str) – user input for variable, (e.g., [atmos_average.temp] + 2)
Returns:: raw_input without whitespaces (e.g., [atmos_average.temp]+2)
Return type:: str
Raises:: ValueError – If the input raw_input is not a valid type for whitespace removal.

select_range(Ncdf_num, bound)

Return the prefix numbers for the netCDF files in the directory within the user-defined range.

Parameters:

Ncdf_num (array) – a sorted array of sols
bound (int or array) – a sol (e.g., 0350) or range of sols [min max]

Returns:

a sorted array of sols within the bounds

Return type:

array

Raises:

ValueError – If the input Ncdf_num is not a valid type for file name.
TypeError – If the input bound is not a valid type for file name.
Exception – If the range selection fails for any reason.

shift_data(lon, data)

Shifts the longitude data from 0-360 to -180/180 and vice versa.

Parameters:

lon (array [lon]) – 1D array of longitude
data (array [1,lon]) – 2D array with last dimension = longitude

Returns:

1D array of longitude in -180/180 or 0-360

Return type:

array [lon]

Returns:

2D array with last dimension = longitude

Return type:

array [1,lon]

Raises:

ValueError – If the longitude coordinate type is invalid.
TypeError – If the input data is not a valid type for shifting.
Exception – If the shifting operation fails for any reason.

Note

Use np.ma.hstack instead of np.hstack to keep the masked array properties

split_varfull(varfull)

Split varfull object into its component parts

Parameters:: varfull (str) – a varfull object (e.g, atmos_average@2.zsurf, 02400.atmos_average@2.zsurf)
Returns:: (sol_array) a sol number or None (if none provided)
Return type:: int or None
Returns:: (filetype) file type (e.g, atmos_average)
Return type:: str
Returns:: (var) variable of interest (e.g, zsurf)
Return type:: str
Returns:: (simuID) simulation ID (Python indexing starts at 0)
Return type:: int
Raises:: ValueError – If the input varfull is not a valid type for splitting.

add_sol_time_axis

args

current_version = 3.5

debug

degr = '°'

exit_code

include_NaNs

lon_coord_type

namespace

parser

bin.MarsPlot

Module Contents

Classes

Functions

Attributes

Parameters

`bin.MarsPlot`