../../_images/cs_light.jpg

Cross Sections#

class seismoviz.components.cross_section.CrossSection(instance)#

Represents a seismic cross section.

Attributes:
datapd.DataFrame

A DataFrame containing the seismic event data for each cross-sectional slice.

catalogCatalog

An instance of the Catalog class containing seismic event data.

centertuple[float, float]

A tuple representing the geographical coordinates (longitude, latitude) of the center of the cross-section.

num_sectionstuple[int, int]

A tuple specifying the number of sections to create to the left and right of the center (e.g., (2, 2) will create 2 sections on each side of the center).

thicknessint

The maximum distance (in km) that events can be from the cross-section plane to be included in the section.

strikeint

The strike angle (in degrees) of the cross-section, measured clockwise from north. Cross section will be computed perpendicular to strike.

map_lengthfloat

The length of the cross-section (in km), which determines the horizontal extent of the plotted data.

depth_rangetuple[float, float]

A tuple specifying the minimum and maximum depth (in km) of events to include in the cross-section.

section_distancefloat, optional

The distance (in km) between adjacent sections. Must be greater than 0. Default is 1.

Raises:
ValueError

If the provided catalog is not an instance of the Catalog class.

Operation methods#

CrossSection.filter(**kwargs)#

Filters the instance’s dataset based on multiple specified conditions.

Note

Each keyword argument should be in the form attribute=('criteria', value) or attribute=('criteria', [value1, value2]) for range criteria. This allows for intuitive and flexible filtering based on the attributes of the data.

Parameters:
instanceobject

The instance containing the dataset (must have an attribute data).

**kwargsdict

Arbitrary keyword arguments representing the filtering conditions. Each key is an attribute name in the dataset, and the value is a tuple specifying the criteria ('greater', 'lower', 'between', 'outside') and the comparison value(s).

Returns:
object

The same instance, with its dataset filtered.

CrossSection.sort(by, ascending=True)#

Sorts the instance’s dataset by a specific attribute.

Parameters:
instanceobject

The instance containing the dataset (must have an attribute data).

bystr

The attribute in the dataset to sort by.

ascendingbool, optional

Determines the sorting order. If True (default), sorts in ascending order; if False, in descending order.

Returns:
object

The same instance, with its dataset sorted.

CrossSection.deduplicate_events(**kwargs)#

Removes duplicate entries based on specific attributes.

Returns:
object

The same instance, with duplicate entries removed.

Visualization methods#

CrossSection.plot_sections(color_by=None, cmap='jet', title='Section', hl_ms=None, hl_size=200, hl_marker='*', hl_color='red', hl_edgecolor='darkred', color='black', edgecolor=None, size=5, size_scale_factor=(1, 2), alpha=0.5, legend=None, legend_loc='lower left', size_legend=False, size_legend_loc='upper right', scale_legend=True, scale_legend_loc='lower right', ylabel='Depth [km]', xlim=None, ylim=None, fig_size=(12, 6), facecolor=('#F0F0F0', '#FFFFFF'), save_figure=False, save_name='cross_section', save_extension='jpg')#

Plots a cross-section of seismic events with customizable appearance.

Parameters:
color_bystr, optional

Specifies the column in the DataFrame used to color the seismic events. Default is None, which applies a single color to all points.

cmapstr, optional

The colormap to use for coloring events if color_by is specified. Default is 'jet'.

titlestr, optional

Title of the map. If None, no title is displayed. Default is Section.

hl_msint, optional

If specified, highlights seismic events with a magnitude greater than this value using different markers. Default is None.

hl_sizefloat, optional

Size of the markers used for highlighted seismic events (if hl_ms is specified). Default is 200.

hl_markerstr, optional

Marker style for highlighted events. Default is '*'.

hl_colorstr, optional

Color of the highlighted event markers. Default is 'red'.

hl_edgecolorstr, optional

Edge color for highlighted event markers. Default is 'darkred'.

sizefloat or str, optional

The size of the markers representing seismic events. If a string is provided, it should refer to a column in the DataFrame to scale point sizes proportionally. Default is 10.

size_scale_factortuple[float, float], optional

A tuple to scale marker sizes when size is based on a DataFrame column. The first element scales the values, and the second element raises them to a power. Default is (1, 3).

colorstr, optional

Default color for event markers when color_by is None. Default is 'grey'.

edgecolorstr, optional

Edge color for event markers. Default is 'black'.

alphafloat, optional

Transparency level for markers, ranging from 0 (transparent) to 1 (opaque). Default is 0.50.

legendstr, optional

Text for the legend describing the seismic events. If None, no legend is displayed. Default is None.

legend_locstr, optional

Location of the legend for the seismic event markers. Default is 'lower left'.

size_legendbool, optional

If True, displays a legend that explains marker sizes. Default is False.

size_legend_locstr, optional

Location of the size legend when size_legend is True. Default is 'lower right'.

scale_legend: bool, optional

If True, displays a legend that shows a scale bar on the plot to indicate real-world distances. Default is True.

scale_legend_locstr, optional

Location of the size legend when scale_legend is True. Default is 'lower right'.

ylabelstr, optional

Label for the y-axis. Default is 'Depth [km]'.

xlimtuple[float, float], optional

Distance from center limits for the map’s horizontal extent. If None, the limits are determined automatically based on the map_length attribute. Default is None.

ylimtuple[float, float], optional

Depth limits for the map’s vertical extent. If None, the limits are determined automatically based on the depth_range attribute. Default is None.

fig_sizetuple[float, float], optional

Figure size for the plot. Default is (12, 6).

facecolortuple[str, str], optional

Tuple specifying the background colors of the plot, with two values for gradient-like effects. Default is ('#F0F0F0', '#FFFFFF').

save_figurebool, optional

If True, saves the plot to a file. Default is False.

save_namestr, optional

Base name for the file if save_figure is True. Default is 'cross_section'.

save_extensionstr, optional

File format for the saved figure (e.g., 'jpg', 'png'). Default is 'jpg'.

Returns:
None

A cross-section plot.

CrossSection.plot_section_lines(color_by=None, cmap='jet', title=None, hl_ms=None, hl_size=200, hl_marker='*', hl_color='red', hl_edgecolor='darkred', size=10, size_scale_factor=(1, 3), color='grey', edgecolor='black', alpha=0.75, legend=None, legend_loc='lower left', size_legend=False, size_legend_loc='lower right', sl_color='black', sl_linewidth=1.5, sl_text_size=10, sl_text_color='white', sl_text_weight='bold', sl_box_style='circle', sl_box_color='black', sl_box_edgecolor='black', sl_box_pad=0.3, terrain_style='satellite', terrain_cmap='gray_r', terrain_alpha=0.35, inset=False, inset_size=(1.8, 1.8), inset_loc='upper right', inset_buffer=3, xlim=None, ylim=None, bounds_res='50m', bmap_res=5, projection=<Projected CRS: +proj=merc +ellps=WGS84 +lon_0=0.0 +x_0=0.0 +y_0=0 ...> Name: unknown Axis Info [cartesian]: - E[east]: Easting (metre) - N[north]: Northing (metre) Area of Use: - undefined Coordinate Operation: - name: unknown - method: Mercator (variant A) Datum: Unknown based on WGS 84 ellipsoid - Ellipsoid: WGS 84 - Prime Meridian: Greenwich, transform=<Projected CRS: +proj=eqc +ellps=WGS84 +a=6378137.0 +lon_0=0.0 +to ...> Name: unknown Axis Info [cartesian]: - E[east]: Easting (unknown) - N[north]: Northing (unknown) - h[up]: Ellipsoidal height (metre) Area of Use: - undefined Coordinate Operation: - name: unknown - method: Equidistant Cylindrical Datum: Unknown based on WGS 84 ellipsoid - Ellipsoid: WGS 84 - Prime Meridian: Greenwich, save_figure=False, save_name='section_lines', save_extension='jpg')#

Visualizes section lines on a map.

Parameters:
color_bystr, optional

Specifies the column in the DataFrame used to color the seismic events. Default is None, which applies a single color to all points.

cmapstr, optional

The colormap to use for coloring events if color_by is specified. Default is 'jet'.

titlestr, optional

Title of the map. If None, no title is displayed. Default is None.

hl_msint, optional

If specified, highlights seismic events with a magnitude greater than this value using different markers. Default is None.

hl_sizefloat, optional

Size of the markers used for highlighted seismic events (if hl_ms is specified). Default is 200.

hl_markerstr, optional

Marker style for highlighted events. Default is '*'.

hl_colorstr, optional

Color of the highlighted event markers. Default is 'red'.

hl_edgecolorstr, optional

Edge color for highlighted event markers. Default is 'darkred'.

sizefloat or str, optional

The size of the markers representing seismic events. If a string is provided, it should refer to a column in the DataFrame to scale point sizes proportionally. Default is 10.

size_scale_factortuple[float, float], optional

A tuple to scale marker sizes when size is based on a DataFrame column. The first element scales the values, and the second element raises them to a power. Default is (1, 3).

colorstr, optional

Default color for event markers when color_by is None. Default is 'grey'.

edgecolorstr, optional

Edge color for event markers. Default is 'black'.

alphafloat, optional

Transparency level for markers, ranging from 0 (transparent) to 1 (opaque). Default is 0.75.

sl_colorstr, optional

Line color for section lines. Default is 'blue'.

sl_linewidthfloat, optional

Line width for section lines. Default is 1.5.

sl_text_sizefloat, optional

Font size for section line labels. Default is 10.

sl_text_colorstr, optional

Text color for section line labels. Default is 'white'.

sl_text_weightstr, optional

Text weight for section line labels. Default is 'bold'.

sl_box_stylestr, optional

Style for the bounding box around section line labels. Default is 'circle'.

sl_box_colorstr, optional

Fill color for the bounding box around section line labels. Default is 'black'.

sl_box_edgecolorstr, optional

Edge color for the bounding box around section line labels. Default is 'black'.

sl_box_padfloat, optional

Padding inside the bounding box for section line labels. Default is 0.3.

legendstr, optional

Text for the legend describing the seismic events. If None, no legend is displayed. Default is None.

legend_locstr, optional

Location of the legend for the seismic event markers. Default is 'lower left'.

size_legendbool, optional

If True, displays a legend that explains marker sizes. Default is False.

size_legend_locstr, optional

Location of the size legend when size_legend is True. Default is 'lower right'.

xlimtuple[float, float], optional

Longitude limits for the map’s horizontal extent. If None, the limits are determined automatically based on the data. Default is None.

ylimtuple[float, float], optional

Latitude limits for the map’s vertical extent. If None, the limits are determined automatically based on the data. Default is None.

terrain_cmapstr, optional

The colormap to be applied to the terrain layer. Defaults to 'gray_r'.

terrain_stylestr, optional

The style of the terrain background for the map. Common values include 'satellite', 'terrain' or 'street'.Defaults to 'satellite'.

terrain_alphafloat, optional

The transparency level for the terrain layer, where 0 is fully transparent and 1 is fully opaque. Defaults to 0.35.

projectioncartopy.crs projection, optional

The map projection used to display the map. Defaults to ccrs.Mercator().

transformcartopy.crs projection, optional

The coordinate reference system of the data to be plotted. Defaults to ccrs.PlateCarree().

insetbool, optional

If True, adds an inset map for broader geographic context. Default is False.

inset_locstr, optional

The location of the inset within the main axis. Options include 'upper right', 'upper left', 'lower right', 'lower left', or 'center'. Default is 'upper right'.

inset_sizetuple[float, float], optional

The size of the inset in inches (width, height). Default is (1.8, 1.8).

inset_bufferfloat, optional

Scaling factor for the area surrounding the selection shape in the inset map. Default is 3.

bounds_resstr, optional

Resolution of geographical boundaries (coastlines, borders) on the map. Options are '10m' (highest resolution), '50m', and '110m' (lowest resolution). Default is ‘50m’.

bmap_resint, optional

Resolution level for the base map image (e.g., satellite or terrain). Higher values provide more detail. Default is 12.

save_figurebool, optional

If True, saves the plot to a file. Default is False.

save_namestr, optional

Base name for the file if save_figure is True. Default is 'section_lines'.

save_extensionstr, optional

File format for the saved figure (e.g., 'jpg', 'png'). Default is 'jpg'.

Returns:
None

A map showing section lines.

Magnitude analysis methods#

CrossSection.magnitude_time(color_by=None, cmap='jet', size=10, size_scale_factor=(1, 2), color='grey', edgecolor='black', alpha=0.75, size_legend=False, size_legend_loc='upper right', ms_line=None, ms_line_color='red', ms_line_width=1, ms_line_style='-', ms_line_gradient=True, fig_size=(10, 5), save_figure=False, save_name='magnitude_time', save_extension='jpg')#

Plot seismic event magnitudes over time.

Parameters:
color_bystr, optional

Column name to color the markers by (default is None).

cmapstr, optional

The colormap to use if coloring by a variable (default is 'jet').

sizefloat or str, optional

Marker size or a column name to scale marker sizes (default is 10).

size_scale_factortuple of float, optional

Factor to scale the marker sizes (default is (1, 2)).

colorstr, optional

Color for the markers if not coloring by a variable (default is 'grey').

edgecolorstr, optional

Edge color for the markers (default is 'black').

alphafloat, optional

Alpha transparency for the markers (default is 0.75).

size_legendbool, optional

If True, create a legend for the marker sizes (default is False).

size_legend_locstr, optional

Location for the size legend (default is 'upper right').

ms_linefloat, optional

Value to add vertical lines representing a magnitude scale (default is None).

ms_line_colorstr, optional

Color for the vertical lines (default is 'red').

ms_line_widthfloat, optional

Line width for the vertical lines (default is 1).

ms_line_stylestr, optional

Line style for the vertical lines (default is '-').

ms_line_gradientbool, optional

If True, apply a gradient to the vertical lines (default is True).

fig_sizetuple of float, optional

Figure size for the plot. Default is (10, 5).

save_figurebool, optional

If True, saves the plot to a file. Default is False.

save_namestr, optional

Base name for the file if save_figure is True. Default is 'magnitude_time'.

save_extensionstr, optional

File format for the saved figure (e.g., 'jpg', 'png'). Default is 'jpg'.

CrossSection.fmd(bin_size, plot=True, return_values=False, mags=None, **kwargs)#

Calculate the frequency-magnitude distribution (FMD) for seismic events.

Parameters:
bin_sizefloat

The size of the bin for the frequency-magnitude distribution.

plotbool, optional

If True, plot the FMD (default is True).

return_valuesbool, optional

If True, return the computed values (default is False).

magslist[float], optional

Array of magnitudes to use (default is None).

save_figurebool, optional

If True, saves the plot to a file. Default is False.

save_namestr, optional

Base name for the file if save_figure is True. Default is 'fmd'.

save_extensionstr, optional

File format for the saved figure (e.g., 'jpg', 'png'). Default is 'jpg'.

Returns:
tuple of list[float]
A tuple containing:

  • bins: The centers of the magnitude bins.

  • events_per_bin: The number of events per bin.

  • cumulative_events: The cumulative number of events.

Statistical analysis methods#

CrossSection.event_timeline(ms_line=None, ms_line_color='red', ms_line_width=1.5, ms_line_style='-', ms_line_gradient=True, fig_size=(10, 5), save_figure=False, save_name='event_timeline', save_extension='jpg')#

Plots a timeline of seismic events to visualize the cumulative number of events over time.

Parameters:
ms_linefloat, optional

The magnitude threshold above which vertical lines will be added to the plot. If None, no vertical lines are added. Default is None.

ms_line_colorstr, optional

The color of the vertical lines. Accepts any Matplotlib-compatible color string. Default is 'red'.

ms_line_widthfloat, optional

The thickness of the vertical lines. Default is 1.5.

ms_line_stylestr, optional

The style of the vertical lines. Default is '-'.

ms_line_gradientbool, optional

If True, the vertical lines will have a gradient effect, fading from the specified color to transparent along the y-axis. If False, the lines will be solid. Default is True.

fig_sizetuple[float, float], optional

Figure size for the plot. Default is (10, 5).

save_figurebool, optional

If True, saves the plot to a file. Default is False.

save_namestr, optional

Base name for the file if save_figure is True. Default is 'event_timeline'.

save_extensionstr, optional

File format for the saved figure (e.g., 'jpg', 'png'). Default is 'jpg'.

Returns:
None

An event timeline plot.

CrossSection.seismicity_rate(unit='1D', fig_size=(10, 5), color='grey', ms_line=None, ms_line_color='red', ms_line_width=1.5, ms_line_style='-', ms_line_gradient=True, save_figure=False, save_name='seismicity_rate', save_extension='jpg', **kwargs)#

Calculates and plots the seismicity rate as a histogram showing the frequency of events over time.

Parameters:
unitstr, optional

Time unit for grouping events. Accepts pandas time frequency strings such as ‘1D’ (daily), ‘1H’ (hourly), ‘1W’ (weekly), etc. Default is ‘1D’.

fig_sizetuple[float, float], optional

Figure size for the plot. Default is (10, 5).

colorstr, optional

Color of the histogram bars. Default is 'steelblue'.

ms_linefloat, optional

The magnitude threshold above which vertical lines will be added to the plot. If None, no vertical lines are added. Default is None.

ms_line_colorstr, optional

The color of the vertical lines. Accepts any Matplotlib-compatible color string. Default is 'red'.

ms_line_widthfloat, optional

The thickness of the vertical lines. Default is 1.5.

ms_line_stylestr, optional

The style of the vertical lines. Default is '-'.

ms_line_gradientbool, optional

If True, the vertical lines will have a gradient effect, fading from the specified color to transparent along the y-axis. If False, the lines will be solid. Default is True.

save_figurebool, optional

If True, saves the plot to a file. Default is False.

save_namestr, optional

Base name for the file if save_figure is True. Default is 'seismicity_rate'.

save_extensionstr, optional

File format for the saved figure (e.g., 'jpg', 'png'). Default is 'jpg'.

Returns:
None

A seismicity rate histogram plot.

CrossSection.interevent_time(unit='sec', plot=True, **kwargs)#

Calculates the inter-event time for sequential events in the instance.

Note

After executing this method, a new column named interevent_time will be created in the instance.data DataFrame. This column will contain the calculated inter-event times, making the data accessible for further analysis or visualization.

Parameters:
unitstr, optional

The time unit for the inter-event times. Supported values are: - 'sec': seconds (default) - 'min': minutes - 'hour': hours - 'day': days

plotbool, optional

If True, plots the interevent time distribution. Default is True.

plot_vsstr, optional

Specifies the column to plot inter-event times against. Default is 'time'.

plot_event_timelinebool, optional

If True and plot_vs='time', adds a secondary y-axis (twiny) to plot a cumulative event timeline. The timeline represents the cumulative number of events over time. Default is True.

et_colorstr, optional

Specifies the color used for the secondary y-axis (event timeline axis), including the ticks, labels, axis line, and the line representing the cumulative number of events. Default is 'red'.

color_bystr, optional

Specifies the column in the DataFrame used to color the seismic events. Default is None, which applies a single color to all points.

cmapstr, optional

The colormap to use for coloring events if color_by is specified. Default is 'jet'.

sizefloat or str, optional

The size of the markers representing seismic events. If a string is provided, it should refer to a column in the DataFrame to scale point sizes proportionally. Default is 10.

size_scale_factortuple[float, float], optional

A tuple to scale marker sizes when size is based on a DataFrame column. The first element scales the values, and the second element raises them to a power. Default is (1, 2).

yscalestr, optional

Specifies the scale of the y-axis. Common options include 'linear', 'log', 'symlog', and 'logit'. Default is 'log'.

colorstr, optional

Default color for event markers when color_by is None. Default is 'grey'.

edgecolorstr, optional

Edge color for event markers. Default is 'black'.

alphafloat, optional

Transparency level for markers, ranging from 0 (transparent) to 1 (opaque). Default is 0.75.

size_legendbool, optional

If True, displays a legend that explains marker sizes. Default is False.

size_legend_locstr, optional

Location of the size legend when size_legend is True. Default is 'upper right'.

ms_linefloat, optional

The magnitude threshold above which vertical lines will be added to the plot. If None, no vertical lines are added. Default is None.

ms_line_colorstr, optional

The color of the vertical lines. Accepts any Matplotlib-compatible color string. Default is 'orange'.

ms_line_widthfloat, optional

The thickness of the vertical lines. Default is 1.5.

ms_line_stylestr, optional

The style of the vertical lines. Default is '-'.

ms_line_gradientbool, optional

If True, the vertical lines will have a gradient effect, fading from the pecified color to transparent along the y-axis. If False, the lines will be solid. Default is True.

fig_sizetuple[float, float], optional

Figure size for the plot. Default is (10, 5).

save_figurebool, optional

If True, saves the plot to a file. Default is False.

save_namestr, optional

Base name for the file if save_figure is True. Default is 'interevent_time'.

save_extensionstr, optional

File format for the saved figure (e.g., 'jpg', 'png'). Default is 'jpg'.

Raises:
ValueError

If an unsupported time unit is provided.

ValueError

If an invalid configuration is provided.

CrossSection.cov(window_size, plot=True, **kwargs)#

Calculates the coefficient of variation (COV) for the inter-event times using a rolling window.

Note

After executing this method, a new column named cov will be created in the instance.data DataFrame. This column will contain the calculated inter-event times, making the data accessible for further analysis or visualization.

Parameters:
window_sizeint

The size of the rolling window (in number of events) over which the coefficient of variation is calculated.

plotbool, optional

If True, plots the interevent time distribution along with the COV. Default is True.

plot_event_timelinebool, optional

If True and plot_vs='time', adds a secondary y-axis (twiny) to plot a cumulative event timeline. Default is True.

et_colorstr, optional

Specifies the color used for the secondary y-axis (event timeline axis), including the ticks, labels, axis line, and the line representing the cumulative number of events. Default is 'orange'.

plot_covbool, optional

If True and plot_vs='time', adds a secondary y-axis (twiny) to plot the coefficient of variation over time. Default is True.

cov_colorstr, optional

Specifies the color used for the secondary y-axis (event timeline axis), including the ticks, labels, axis line, and the line representing the coefficient og variation. Default is 'blue'.

color_bystr, optional

Specifies the column in the DataFrame used to color the seismic events. Default is None, which applies a single color to all points.

cmapstr, optional

The colormap to use for coloring events if color_by is specified. Default is 'jet'.

sizefloat or str, optional

The size of the markers representing seismic events. If a string is provided, it should refer to a column in the DataFrame to scale point sizes proportionally. Default is 10.

size_scale_factortuple[float, float], optional

A tuple to scale marker sizes when size is based on a DataFrame column. The first element scales the values, and the second element raises them to a power. Default is (1, 2).

yscalestr, optional

Specifies the scale of the y-axis. Common options include 'linear', 'log', 'symlog', and 'logit'. Default is 'log'.

colorstr, optional

Default color for event markers when color_by is None. Default is 'grey'.

edgecolorstr, optional

Edge color for event markers. Default is 'black'.

alphafloat, optional

Transparency level for markers, ranging from 0 (transparent) to 1 (opaque). Default is 0.75.

size_legendbool, optional

If True, displays a legend that explains marker sizes. Default is False.

size_legend_locstr, optional

Location of the size legend when size_legend is True. Default is 'upper right'.

ms_linefloat, optional

The magnitude threshold above which vertical lines will be added to the plot. If None, no vertical lines are added. Default is None.

ms_line_colorstr, optional

The color of the vertical lines. Accepts any Matplotlib-compatible color string. Default is 'red'.

ms_line_widthfloat, optional

The thickness of the vertical lines. Default is 1.5.

ms_line_stylestr, optional

The style of the vertical lines. Default is '-'.

ms_line_gradientbool, optional

If True, the vertical lines will have a gradient effect, fading from the pecified color to transparent along the y-axis. If False, the lines will be solid. Default is True.

fig_sizetuple[float, float], optional

Figure size for the plot. Default is (10, 5).

save_figurebool, optional

If True, saves the plot to a file. Default is False.

save_namestr, optional

Base name for the file if save_figure is True. Default is 'interevent_time'.

save_extensionstr, optional

File format for the saved figure (e.g., 'jpg', 'png'). Default is 'jpg'.

Raises:
ValueError

If an invalid configuration is provided.