From 6f99a284a13c9f0660ee6f34e7baf76018f38a63 Mon Sep 17 00:00:00 2001 From: Marta Han Date: Thu, 20 Feb 2025 16:30:33 +0100 Subject: [PATCH] docs: homogenising docstrings for plotting module --- seismostats/plots/basics.py | 188 +++++++++++++++---------------- seismostats/plots/seismicity.py | 67 +++++------ seismostats/plots/statistical.py | 133 +++++++++++----------- 3 files changed, 194 insertions(+), 194 deletions(-) diff --git a/seismostats/plots/basics.py b/seismostats/plots/basics.py index d1bb432f..30b41f99 100644 --- a/seismostats/plots/basics.py +++ b/seismostats/plots/basics.py @@ -10,15 +10,19 @@ def gutenberg_richter( magnitudes: np.ndarray, b_value: float, mc: float, n_mc: int ) -> np.ndarray: - """Estimates the cumulative Gutenberg richter law (proportional to the + """ + Estimates the cumulative Gutenberg richter law (proportional to the complementary cumulative FMD) for a given magnitude vector. Args: - magnitudes: vector of magnitudes - b_value: theoretical b_value - mc: completeness magnitude - n_mc: cumulative number of all events larger than the completeness - magnitude (n_mc = 10 ** a) + magnitudes: Array of magnitudes. + b_value: Theoretical b_value. + mc: Completeness magnitude. + n_mc: Total number of all events larger than the + completeness magnitude (:math: `n_{m_c} = 10^a`). + + Returns: + x: The cumulative Gutenberg-Richter distribution. """ return n_mc * 10 ** (-b_value * (magnitudes - mc)) @@ -41,25 +45,25 @@ def plot_cum_fmd( distribution is plotted provided the b-value is given. Args: - magnitudes : array of magnitudes - ax : axis where figure should be plotted - b_value : b-value of the theoretical GR distribution to plot - mc : completeness magnitude of the theoretical GR distribution - delta_m : discretization of the magnitudes, important for the correct - visualization of the data - color : color of the data. If one value is given, it is used for - points, and the line of the theoretical GR distribution if it - is plotted. If a list of colors is given, the first entry is - the color of the points, and the second of the line representing - the GR distribution. - size : size of data points - grid : whether to include grid lines or not - bin_position : position of the bin, options are 'center' and 'left' - accordingly, left edges of bins or center points are - returned. + magnitudes: Array of magnitudes. + ax: Axis where figure should be plotted. + b_value: The b-value of the theoretical GR distribution to plot. + mc: Completeness magnitude of the theoretical GR distribution. + delta_m: Discretization of the magnitudes; important for the correct + visualization of the data. + color: Color of the data. If one value is given, it is used for + points, and the line of the theoretical GR distribution if it + is plotted. If a list of colors is given, the first entry is + the color of the points, and the second of the line + representing the GR distribution. + size: Size of the data points. + grid: Indicates whether or not to include grid lines. + bin_position: Position of the bin, options are 'center' and 'left' + accordingly, left edges of bins or center points are + returned. Returns: - ax that was plotted on + ax: The ax object that was plotted on. """ magnitudes = magnitudes[~np.isnan(magnitudes)] @@ -141,19 +145,19 @@ def plot_fmd( assumed value of ``delta_m`` is 0.1. Args: - magnitudes : array of magnitudes - ax : axis where figure should be plotted - delta_m : discretization of the magnitudes, important for the correct - visualization of the data - color : color of the data - size : size of data points - grid : whether to include grid lines or not - bin_position : position of the bin, options are "center" and "left" - accordingly, left edges of bins or center points are - returned. + magnitudes: Array of magnitudes. + ax: The axis where figure should be plotted. + delta_m: Discretization of the magnitudes, important for the + correct visualization of the data. + color: Color of the data. + size: Size of data points. + grid: Indicates whether or not to include grid lines. + bin_position: Position of the bin, options are "center" and "left" + accordingly, left edges of bins or center points are + returned. Returns: - ax that was plotted on + ax: The ax object that was plotted on. """ magnitudes = magnitudes[~np.isnan(magnitudes)] @@ -205,16 +209,17 @@ def plot_cum_count( the array ``mcs``. Args: - times: array containing times of events - magnitudes: array of magnitudes of events corresponding to the - ``times`` - ax: axis where figure should be plotted - mcs: the list of completeness magnitudes for which we show lines - on the plot - delta_m: binning precision of the magnitudes, assumed 0 if not given + times: Array containing times of events. + magnitudes: Array of magnitudes of events corresponding to the + ``times``. + ax: Axis where figure should be plotted. + mcs: The list of completeness magnitudes for which we show + lines on the plot. + delta_m: Binning precision of the magnitudes, assumed 0 if not + given. Returns: - ax that was plotted on + ax: Ax that was plotted on. """ first_time, last_time = min(times), max(times) @@ -259,22 +264,22 @@ def plot_mags_in_time( means that between 2000 and 2005, Mc is 3.5 and after 2005, Mc is 3.0. Args: - times: array containing times of events - magnitudes: array of magnitudes of events corresponding to the - ``times`` - ax: axis where figure should be plotted - mc_change_times: list of points in time when Mc changes, sorted in - increasing order, can be given as a list of datetimes or - integers (years). - mcs: changed values of Mc at times given in ``mc_change_times`` - dot_smallest: smallest dot size for magnitude scaling - dot_largest: largest dot size for magnitude scaling - dot_interpolation_power: interpolation power for scaling - color_dots: color of the dots representing the events - color_line: color of the line representing the Mc changes + times: Array containing times of events. + magnitudes: Array of magnitudes of events corresponding to the + ``times``. + ax: Axis where figure should be plotted. + mc_change_times: List of points in time when Mc changes, sorted in + increasing order, can be given as a list of datetimes or + integers (years). + mcs: Changed values of Mc at times given in ``mc_change_times``. + dot_smallest: Smallest dot size for magnitude scaling. + dot_largest: Largest dot size for magnitude scaling. + dot_interpolation_power: Interpolation power for scaling. + color_dots: Color of the dots representing the events. + color_line: Color of the line representing the Mc changes. Returns: - ax that was plotted on + ax: ax that was plotted on """ if ax is None: ax = plt.subplots()[1] @@ -320,24 +325,18 @@ def dot_size( The dot sizes are computed using a power interpolation between the smallest and largest size, with the given interpolation power. - Args - ---------- - magnitudes : array-like of float, shape (n_samples,) - The magnitudes of the dots. - smallest : float, optional (default=10) - The size of the smallest dot, in pixels. - largest : float, optional (default=200) - The size of the largest dot, in pixels. - interpolation_power : float, optional (default=1) - The power used to interpolate between the smallest and largest size. - A value of 1 results in a linear interpolation, while larger values - result in a more "concave" curve. - - Returns - ------- - sizes : ndarray of float, shape (n_samples,) - The sizes of the dots, proportional to their magnitudes. - The returned sizes are between ``smallest`` and ``largest``. + Args: + magnitudes: Array of magnitudes, influencing size of the dots. + smallest: The size of the smallest dot, in pixels. + largest: The size of the largest dot, in pixels. + interpolation_power: The power used to interpolate between the smallest + and largest size. A value of 1 results in a linear + interpolation, while larger values result in a more + "concave" curve. + + Returns: + sizes: The sizes of the dots, proportional to their magnitudes. + The returned sizes are between ``smallest`` and ``largest``. """ if largest <= smallest: print( @@ -361,32 +360,25 @@ def reverse_dot_size( max_mag: float, interpolation_power: int = 1, ) -> np.ndarray: - """Compute magnitudes proportional to a given array of dot sizes. + """ + Computes magnitudes proportional to a given array of dot sizes. The magnitudes are computed by reversing the dot size calculation - performed by the dot_size function. - - Args - ---------- - sizes : array-like of float, shape (n_samples,) - The sizes of the dots. - min_mag : float - The minimum magnitude in the dataset. - max_mag : float - The maximum magnitude in the dataset. - smallest : float, optional (default=10) - The size of the smallest dot, in pixels. - largest : float, optional (default=200) - The size of the largest dot, in pixels. - interpolation_power : float, optional (default=1) - The power used to interpolate between the smallest and largest size. - A value of 1 results in a linear interpolation, while larger values - result in a more "concave" curve. - - Returns - ------- - magnitudes : ndarray of float, shape (n_samples,) - The magnitudes corresponding to the given dot sizes. + performed by the :func: `dot_size` function. + + Args: + sizes: A list containing the sizes of the dots. + min_mag: The minimum magnitude in the dataset. + max_mag: The maximum magnitude in the dataset. + smallest: The size of the smallest dot, in pixels. + largest: The size of the largest dot, in pixels. + interpolation_power: The power used to interpolate between the smallest + and largest size. A value of 1 results in a linear + interpolation, while larger values result in a more "concave" + curve. + + Returns: + magnitudes: Array of magnitudes corresponding to the given dot sizes. """ if interpolation_power == 0: raise ValueError("interpolation_power cannot be 0") diff --git a/seismostats/plots/seismicity.py b/seismostats/plots/seismicity.py index 84fc5557..5743a57b 100644 --- a/seismostats/plots/seismicity.py +++ b/seismostats/plots/seismicity.py @@ -37,35 +37,35 @@ def plot_in_space( according to the midpoint latitude. Args: - longitudes: array of longitudes - latitudes: array of latitudes - magnitudes: array of magnitudes, used for scaling of dot sizes - resolution: resolution of map, "10m", "50m" and "110m" available - include_map: if True, seismicity will be plotted on natural earth - map, otherwise it will be plotted on a blank grid. - country: name of country, if None map will fit to data points - colors: color of background. if None is chosen, is will be - either white or standard natural earth colors. - style: style of map, "satellite" or "street" are available - dot_smallest: smallest dot size for magnitude scaling - dot_largest: largest dot size for magnitude scaling - dot_interpolation_power: interpolation power for scaling - dot_labels: int, None, "auto" (default), list, or - ``~.ticker.Locator``. Determines how labels for - magnitudes can be created. Input for matplotlib's - ``PathCollection.legend_elements``. If ``None``, no - label is shown. If an integer, target to use - ``dot_labels`` elements in the normed range. - If "auto", an automatic range is chosen for the - labels (default). If a list, uses elements of list - which are between minimum and maximum magnitude of - dataset for the legend. - Finally, a ``~.ticker.Locator`` can be provided to use - a predefined ``matplotlib.ticker`` (e.g. - ``FixedLocator``, which results in the same legend as - providing a list of values). + longitudes: Array of longitudes. + latitudes: Array of latitudes. + magnitudes: Array of magnitudes, used for scaling of dot sizes. + resolution: Resolution of the map, "10m", "50m" and "110m" + available. + include_map: If True, seismicity will be plotted on natural earth + map, otherwise it will be plotted on a blank grid. + country: Name of country, if None map will fit to data points. + colors: Color of background. If None is chosen, it will be + either white or standard natural earth colors. + style: Style of map, "satellite" or "street" are available. + dot_smallest: Smallest dot size for magnitude scaling. + dot_largest: Largest dot size for magnitude scaling. + dot_interpolation_power: Interpolation power for scaling. + dot_labels: Determines how labels for + magnitudes can be created. Input for matplotlib's + ``PathCollection.legend_elements``. If ``None``, no + label is shown. If an integer, target to use + ``dot_labels`` elements in the normed range. + If "auto", an automatic range is chosen for the + labels (default). If a list, uses elements of list + which are between minimum and maximum magnitude of + dataset for the legend. + Finally, a ``~.ticker.Locator`` can be provided to use + a predefined ``matplotlib.ticker`` (e.g. + ``FixedLocator``, which results in the same legend as + providing a list of values). Returns: - GeoAxis object + ax: GeoAxis object """ # request data for use by geopandas if include_map is True: @@ -183,13 +183,14 @@ def rect_from_bound( """ Makes list of tuples for creating a rectangle polygon Args: - xmin: minimum x value - xmax: maximum x value - ymin: minimum y value - ymax: maximum y value + xmin: Minimum x value. + xmax: Maximum x value. + ymin: Minimum y value. + ymax: Maximum y value. Returns: - list of (x,y)'s for a rectangle + x: List of tuples representing the coordinates of vertices + for a rectangle. """ xs = [xmax, xmin, xmin, xmax] ys = [ymax, ymax, ymin, ymin] diff --git a/seismostats/plots/statistical.py b/seismostats/plots/statistical.py index eba02c39..deaf99e6 100644 --- a/seismostats/plots/statistical.py +++ b/seismostats/plots/statistical.py @@ -18,28 +18,29 @@ def plot_mc_vs_b( mcs: np.ndarray, delta_m: float, b_method: BValueEstimator = ClassicBValueEstimator, - confidence_intvl: float = 0.95, + confidence_interval: float = 0.95, ax: plt.Axes | None = None, color: str = "blue", label: str | None = None, **kwargs, ) -> plt.Axes: - """Plots the estimated b-value in dependence of the completeness magnitude. + """ + Plots the estimated b-value in dependence of the completeness magnitude. Args: - magnitudes: magnitudes of the catalog - mcs: completeness magnitudes (list or numpy array) - delta_m: discretization of the magnitudes - method: method used for b-value estimation - confidence_intvl: confidence interval that should be plotted - ax: axis where figure should be plotted - color: color of the data - label: label of the data that will be put in the legend - **kwargs: Additional keyword arguments for the b-value - estimator. + magnitudes: Array of magnitudes. + mcs: Array of completeness magnitudes. + delta_m: Discretization of the magnitudes. + b_method: Method used for b-value estimation. + confidence_interval: Confidence interval that should be plotted. + ax: Axis where figure should be plotted. + color: Color of the data. + label: Label of the data that will be put in the legend. + **kwargs: Additional keyword arguments for the b-value + estimator. Returns: - ax that was plotted on + ax: ax that was plotted on """ b_values = [] @@ -58,7 +59,7 @@ def plot_mc_vs_b( if ax is None: _, ax = plt.subplots() - error_factor = norm.ppf((1 + confidence_intvl) / 2) + error_factor = norm.ppf((1 + confidence_interval) / 2) ax.plot(mcs, b_values, "-o", color=color, label=label) ax.fill_between( mcs, @@ -78,53 +79,59 @@ def plot_mc_vs_b( def plot_b_series_constant_nm( - mags: np.ndarray, - delta_m: float, - mc: np.ndarray, - times: np.ndarray, - n_m: int, - min_num: float = 2, - b_method: BValueEstimator = ClassicBValueEstimator, - plot_technique: Literal['left', 'midpoint', 'right'] = 'right', - x_variable: np.ndarray | None = None, - confidence: float = 0.95, - ax: plt.Axes | None = None, - color: str = "blue", - label: str | None = None, - *args, - **kwargs, + mags: np.ndarray, + delta_m: float, + mc: np.ndarray, + times: np.ndarray, + n_m: int, + min_num: float = 2, + b_method: BValueEstimator = ClassicBValueEstimator, + plot_technique: Literal['left', 'midpoint', 'right'] = 'right', + x_variable: np.ndarray | None = None, + confidence_level: float = 0.95, + ax: plt.Axes | None = None, + color: str = "blue", + label: str | None = None, + *args, + **kwargs ) -> plt.Axes: """ Plots the b-values estimated from a running window of n_m magnitudes. Args: - mags: magnitudes of the events. If x_variable is None, the magnitudes - are assumed to be sorted in the dimension of interest. - delta_m: magnitude bin width - mc: completeness magnitude. If a single value is provided, it is - used for all magnitudes. Otherwise, the individual completeness of - each magnitude can be provided. - times: times of the events - n_m: number of magnitudes in each partition - min_num: minimum number of events from which a b-value is estimated. - If the number of events is smaller, the b-value is set to np.nan - b_method: method to estimate the b-values - plot_technique: technique where to plot the b-values with respect to - the x-variable. Options are 'left', 'midpoint', 'right'. If set to - 'right' (default), the b-value is plotted at the right edge. For - time series, this is the most common choice, as it avoids optical - illusions of the b-value predicting future seismicity. - x_variable: values of the dimension of interest, along which the - b-values should be plotted. It should be a 1D array with the same - length as the magnitudes, e.g., the time of the events. If None, - the b-values are plotted against the event index. - confidence: confidence interval that should be plotted. Default - is 0.95 (i.e., the 95% confidence interval is plotted) - ax: axis where the plot should be plotted - color: color of the data - label: abel of the data that will be put in the legend - *args: Additional positional arguments for the b-value estimator. - **kwargs: Additional keyword arguments for the b-value estimator. + magnitudes: Magnitudes of the events. If x_variable is None, + the magnitudes are assumed to be sorted in the dimension + of interest. + delta_m: Magnitude bin width. + mc: Completeness magnitude. If a single value is provided, + it is used for all magnitudes. Otherwise, the individual + completeness of each magnitude can be provided. + times: Times of the events. + n_m: Number of magnitudes in each partition. + min_num: Minimum number of events from which a b-value is + estimated. If the number of events is smaller, the b-value + is set to np.nan. + b_method: Method used to estimate the b-values. + plot_technique: Technique where to plot the b-values with respect to + the x-variable. Options are 'left', 'midpoint', 'right'. + If set to 'right' (default), the b-value is plotted at the + right edge. For time series, this is the most common choice + as it avoids optical illusions of the b-value predicting + future seismicity. + x_variable: Values of the dimension of interest, along which the + b-values should be plotted. It should be a 1D array with + the same length as the magnitudes, e.g., the time of the + events. If None, the b-values are plotted against the + event index. + confidence_level: Confidence level of the CI that should be plotted. + Default is 0.95 (i.e., the 95% confidence interval is + plotted). + ax: Axis where the plot should be plotted. + color: Color of the data. + label: Label of the data that will be put in the legend. + *args: Additional positional arguments for the b-value + estimator. + **kwargs: Additional keyword arguments for the b-value estimator. Returns: ax that was plotted on @@ -197,7 +204,7 @@ def plot_b_series_constant_nm( # plotting ax.plot(x_variable, b_values, color=color, label=label) - error_factor = norm.ppf((1 + confidence) / 2) + error_factor = norm.ppf((1 + confidence_level) / 2) ax.fill_between( x_variable, b_values - error_factor * std_bs, @@ -241,20 +248,20 @@ def plot_b_significant_1D( Args: magnitudes: Magnitudes of the events. times: Times of the events. - mc: Completeness magnitude. If a single value is provided, it is - used for all magnitudes. Otherwise, the individual completeness of - each magnitude can be provided. + mc: Completeness magnitude. If a single value is provided, it + is used for all magnitudes. Otherwise, the individual completeness + of each magnitude can be provided. delta_m: Magnitude descretization. n_ms: List of number of magnitudes used per sample. If None, the function will use an array of values that are increasing by 10 within a range of reasonable values. min_num: Minimum number of events from which a b-value is estimated. b_method: Method to estimate the b-values. - x_variable: values of the dimension of interest, along which the + x_variable: Values of the dimension of interest, along which the b-values should be plotted. It should be a 1D array with the same length as the magnitudes, e.g., the time of the events. If None, the b-values are plotted against the event index. - p_threshold: Threshold above which the null hypothesis of a constant + p_threshold: Threshold above which the null hypothesis of a constant b-value can be rejected. ax: Axis where the plot should be plotted. color: Color of the data. @@ -317,7 +324,7 @@ def adjust_color_brightness(color, factor=1.2): Adjusts the brightness of a given Matplotlib color. Args: - color: A valid Matplotlib color string (e.g., "blue", "#ff5733", "C1"). + color: A valid Matplotlib color string (e.g., "blue", "#ff5733", "C1"). factor: A float value that adjusts the brightness of the color. if < 1, the color is lightened; if > 1, the color is darkened.