../../_images/catalog_light.jpg

Catalog#

class seismoviz.components.catalog.Catalog(instance)#

Represents a seismic event catalog.

Attributes:
datapandas.DataFrame

A DataFrame containing the seismic event data.

Raises:
ValueError

If the input DataFrame is missing required columns during initialization.

Warning

The input CSV file must contain the following columns: lon, lat, time, depth, mag, and id.

Operation methods#

Catalog.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.

Catalog.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.

Catalog.deduplicate_events(**kwargs)#

Removes duplicate entries based on specific attributes.

Returns:
object

The same instance, with duplicate entries removed.

Visualization methods#

Catalog.plot_map(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', 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='map', save_extension='jpg')#

Visualizes seismic events on a geographical 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.

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 'map'.

save_extensionstr, optional

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

Returns:
None

A map with seismic events.

Catalog.plot_space_time(center, strike, color_by=None, cmap='jet', hl_ms=None, hl_size=200, hl_marker='*', hl_color='red', hl_edgecolor='darkred', size=10, size_scale_factor=(1, 2), color='grey', edgecolor='black', alpha=0.75, xlim=None, ylim=None, legend=None, legend_loc='lower right', size_legend=False, size_legend_loc='upper right', fig_size=(10, 5), save_figure=False, save_name='space_time', save_extension='jpg')#

Plots the space-time distribution of seismic events along a specified strike direction.

Parameters:
centertuple[float, float]

The (longitude, latitude) coordinates of the center point for distance calculation.

strikeint

The strike angle in degrees, measured clockwise from north. Defines the direction along which distances are calculated.

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'.

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, 2).

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.

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

Time limits for the x-axis as start and end date strings. Default is None.

ylimtuple[float, float], optional

Limits for the y-axis (distance from center). Default is None.

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 'space_time'.

save_extensionstr, optional

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

Returns:
None

A space-time plot.

Magnitude analysis methods#

Catalog.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'.

Catalog.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.

Catalog.b_value(bin_size, mc, uncertainty_method='shi_bolt', **kwargs)#

Estimate the b-value for seismic events and calculate the associated uncertainty.

Parameters:
bin_sizefloat

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

mcstr or float

The method to estimate Mc ('maxc', 'gft', or 'mbs') or a numerical value for Mc.

uncertainty_methodstr, optional

The method for uncertainty estimation (default is 'shi_bolt').

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 'b-value'.

save_extensionstr, optional

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

Returns:
tuple or None

If mc is provided as a numerical value, returns the b-value estimation tuple.

Catalog.b_value_over_time(bin_size, mc_method, window_type, window_size, step_size=None, uncertainty_method='shi_bolt', min_events_ratio=0.5, plot=True, return_values=False, **kwargs)#

Calculate the b-value over time windows.

Parameters:
bin_sizefloat

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

mc_methodstr

The method to estimate the magnitude of completeness ('maxc', 'gft', or 'mbs').

window_typestr

The type of window to use ('event' or 'time').

window_sizeint or str

The size of the window. Must be an int if window_type is 'event' or a str if 'time'.

step_sizeint or str, optional

The step size for the window. Defaults to the window size if not provided.

uncertainty_methodstr, optional

The method for uncertainty estimation (default is 'shi_bolt').

min_events_ratiofloat, optional

The minimum ratio of events above Mc required (default is 0.5).

plotbool, optional

If True, plot the b-value over time (default is True).

return_valuesbool, optional

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

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.5).

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 'b_value_over_time'.

save_extensionstr, optional

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

Returns:
dict or None

A dictionary with keys: times, b_values, mc_values, uncertainties, if return_values is True; otherwise, None.

Statistical analysis methods#

Catalog.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.

Catalog.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.

Catalog.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.

Catalog.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.