diff --git a/docs/source/reference/index.md b/docs/source/reference/index.md index ddc62f7..28dba38 100644 --- a/docs/source/reference/index.md +++ b/docs/source/reference/index.md @@ -5,5 +5,6 @@ catalog config +plots analysis ``` \ No newline at end of file diff --git a/docs/source/reference/plots.md b/docs/source/reference/plots.md new file mode 100644 index 0000000..2944f98 --- /dev/null +++ b/docs/source/reference/plots.md @@ -0,0 +1,20 @@ +# Plotting functions + +```{eval-rst} +.. currentmodule:: seismostats +``` + +## + +```{eval-rst} +.. autosummary:: + :toctree: api/ + + :func: + plot_cum_fmd + plot_fmd + plot_cum_count + plot_mags_in_time + plot_in_space + plot_mc_vs_b +``` diff --git a/seismostats/plots/basics.py b/seismostats/plots/basics.py index 82b5ee2..1018754 100644 --- a/seismostats/plots/basics.py +++ b/seismostats/plots/basics.py @@ -35,10 +35,10 @@ def plot_cum_fmd( bin_position: str = "center", legend: bool | str | list = True, ) -> plt.Axes: - """Plots cumulative frequency magnitude distribution, optionally with a - corresponding theoretical Gutenberg-Richter (GR) distribution (using the - provided b-value). Unlike plot_cum_fmd, plots values for all bins and - requires binning. + """ + Plots cumulative frequency magnitude distribution, optionally with a + corresponding theoretical Gutenberg-Richter (GR) distribution. The GR + distribution is plotted provided the b-value is given. Args: mags : array of magnitudes @@ -47,10 +47,13 @@ def plot_cum_fmd( 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 theoretical GR distribution should be - colored differently this should be a list with two entries - size : size of scattered data - grid : bool, include grid lines or not + 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. @@ -113,11 +116,11 @@ def plot_cum_fmd( ax.set_xlabel("Magnitude") ax.set_ylabel("N") - if grid is True: + if grid: ax.grid(True) ax.grid(which="minor", alpha=0.3) - if legend is not False: + if legend: ax.legend() return ax @@ -133,18 +136,19 @@ def plot_fmd( bin_position: str = "center", legend: bool | str | list = True, ) -> plt.Axes: - """Plots frequency magnitude distribution. Unlike plot_fmd, - plots values for all bins and requires binning. + """ + Plots frequency magnitude distribution. If no binning is specified, the + assumed value of ``delta_m`` is 0.1. Args: mags : 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 scattered data - grid : bool, include grid lines or not - bin_position : position of the bin, options are 'center' and 'left' + 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. @@ -174,11 +178,11 @@ def plot_fmd( ax.set_xlabel("Magnitude") ax.set_ylabel("N") - if grid is True: + if grid: ax.grid(True) ax.grid(which="minor", alpha=0.3) - if legend is not False: + if legend: ax.legend() return ax @@ -192,7 +196,8 @@ def plot_cum_count( ) -> plt.Axes: """ Plots cumulative count of earthquakes in given catalog above given Mc - through time. Plots a line for each given Mc. + through time. Plots a line for each given completeness magnitude in + the array ``mcs``. Args: ax: axis where figure should be plotted @@ -226,8 +231,8 @@ def plot_cum_count( label=f"Mc={np.round(mc, 2)}", ) - ax.set_xlabel("time") - ax.set_ylabel("count - cumulative") + ax.set_xlabel("Time") + ax.set_ylabel("Cumulative number of events") ax.legend() return ax @@ -240,14 +245,16 @@ def plot_mags_in_time( dot_smallest: int = 10, dot_largest: int = 200, dot_interpolation_power: int = 2, + color_dots: str = "blue", + color_line: str = "#eb4034", ) -> plt.Axes: """ - Creates a scatter plot, each dot is an event. Time shown on x-axis, - magnitude shown on y-axis, but also in size of the dot. + Creates a scatter plot, each dot is an event. Time shown on the x-axis, + magnitude shown on the y-axis, but also reflected in the size of dots. Optionally, adds lines that represent the change in completeness magnitude. - For example, mc_change_times = [2000, 2005] and mcs = [3.5, 3.0] means that - between 2000 and 2005, Mc is 3.5 and after 2005, Mc is 3.0. + For example, ``mc_change_times = [2000, 2005]`` and ``mcs = [3.5, 3.0]`` + means that between 2000 and 2005, Mc is 3.5 and after 2005, Mc is 3.0. Args: ax: axis where figure should be plotted @@ -255,10 +262,12 @@ def plot_mags_in_time( "magnitude" and either "time" or "year" mc_change_times: list of points in time when Mc changes, sorted in increasing order, can be given as a list of datetimes or ints (yrs). - mcs: changed values of Mc at times given in 'mc_change_times' + 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_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 @@ -287,7 +296,7 @@ def plot_mags_in_time( largest=dot_largest, interpolation_power=dot_interpolation_power, ), - c="b", + c=color_dots, linewidth=0.5, alpha=0.8, edgecolor="k", @@ -301,20 +310,22 @@ def plot_mags_in_time( mc_change_times.append(np.max(times)) mcs.append(mcs[-1]) - ax.step(mc_change_times, mcs, where="post", c="#eb4034") + ax.step(mc_change_times, mcs, where="post", c=color_line) - ax.set_xlabel("time") - ax.set_ylabel("magnitude") + ax.set_xlabel("Time") + ax.set_ylabel("Magnitude") return ax def dot_size( magnitudes: np.array, - smallest: int = 10, - largest: int = 200, + smallest: float = 10, + largest: float = 200, interpolation_power: int = 1, ) -> np.array: - """Compute dot sizes proportional to a given array of magnitudes. + """ + Auxiliary function, computes dot sizes proportional to a given array of + magnitudes. The dot sizes are computed using a power interpolation between the smallest and largest size, with the given interpolation power. @@ -336,7 +347,7 @@ def dot_size( ------- sizes : ndarray of float, shape (n_samples,) The sizes of the dots, proportional to their magnitudes. - The returned sizes are between `smallest` and `largest`. + The returned sizes are between ``smallest`` and ``largest``. """ if largest <= smallest: print( diff --git a/seismostats/plots/seismicity.py b/seismostats/plots/seismicity.py index 68937ff..d69184d 100644 --- a/seismostats/plots/seismicity.py +++ b/seismostats/plots/seismicity.py @@ -29,37 +29,38 @@ def plot_in_space( dot_labels: str = "auto", ) -> cartopy.mpl.geoaxes.GeoAxes: """ - Function plots seismicity on the surface. If include_map is chosen True, - a nice natural earth map is used, otherwise the seismicity is just - plotted on a blank grid. In the latter case, the grid is stretched to + This function plots seismicity on a surface. If ``include_map`` is + set to ``True``, a nice natural earth map is used, otherwise the seismicity + is just plotted on a blank grid. In the latter case, the grid is stretched according to the midpoint latitude. Args: - cat: dataframe- needs to have latitude, longitude and + cat: dataframe - needs to have latitude, longitude and depth as entries - resolution: resolution of map, '10m', '50m' and '110m' available + 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 + 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 - 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, - use 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). + ``~.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). Returns: GeoAxis object """