WigglyRivers.utilities package

Submodules

WigglyRivers.utilities.Logger module

DESCRIPTION:
This class acts as the logger for all the classes

class WigglyRivers.utilities.Logger.Logger(console: bool = False, file: str | Path | None = None, level: int | str = 'DEBUG', format: str = '%(asctime)s[%(levelname)s] %(funcName)s: %(message)s')[source]

Bases: object

close_logger()[source]: Close current logger

critical(msg: str)[source]

Logger message

Parameters:: msg (str) – message

debug(msg: str)[source]

Logger message

Parameters:: msg (str) – message

error(msg: str)[source]

Logger message

Parameters:: msg (str) – message

info(msg: str)[source]

Logger message

Parameters:: msg (str) – message

property logger: logger for debbuging

set_logger(console: bool = False, file: str | Path | None = None, level: int | str = 10, format: str = '%(asctime)s[%(levelname)s] %(funcName)s: %(message)s')[source]

Setting logging

Parameters:

console (bool, optional) – show logger information in the terminal. Defaults to False.
file (Union[str, pl.Path, None], optional) – Export logger information to file. If None no file will be created. Defaults to None.
level (Union[int, str], optional) – level of logger, the levels are: DEBUG, CRITICAL, ERROR, WARNING, INFO, NOTSET. Defaults to “DEBUG”.
format (str, optional) – format for logger message. Defaults to “%(asctime)s[%(levelname)s] %(funcName)s: %(message)s”.

warning(msg: str)[source]

Logger message

Parameters:: msg (str) – message

WigglyRivers.utilities.classExceptions module

The classExceptions are included in this script.

exception WigglyRivers.utilities.classExceptions.FileNotFoundError[source]: Bases: Exception

exception WigglyRivers.utilities.classExceptions.FormatError[source]: Bases: Exception

exception WigglyRivers.utilities.classExceptions.HUCNotFoundError[source]: Bases: Exception

exception WigglyRivers.utilities.classExceptions.SmallMeanderError[source]: Bases: Exception

exception WigglyRivers.utilities.classExceptions.VariableNotFoundError[source]: Bases: Exception

WigglyRivers.utilities.classExceptions.deprecated(replacement=None)[source]

WigglyRivers.utilities.filesManagement module

The functions given on this package allow the user to save data in different formats

class WigglyRivers.utilities.filesManagement.NpEncoder(*, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, sort_keys=False, indent=None, separators=None, default=None)[source]

Bases: JSONEncoder

default(obj)[source]

Implement this method in a subclass such that it returns a serializable object for o, or calls the base implementation (to raise a TypeError).

For example, to support arbitrary iterators, you could implement default like this:

def default(self, o):
    try:
        iterable = iter(o)
    except TypeError:
        pass
    else:
        return list(iterable)
    # Let the base class default method raise the TypeError
    return super().default(o)

WigglyRivers.utilities.filesManagement.create_geopandas_dataframe(pandas_df: DataFrame, geometry_columns: list, shape_type: str = 'line', crs: str = 'EPSG:4326') → GeoDataFrame[source]

Create geopandas dataframe from a pandas dataframe.

Parameters:

pandas_df (pd.DataFrame) – Pandas dataframe.
geometry_columns (list) – list of columns that hold the geometry.
shape_type (str, optional) – geometry type. The options are “point” or “line”. Defaults to “line”.
crs (str, optional) – projection. Defaults to “EPSG:4326”.

Raises:

ValueError – geometry type not implemented.

Returns:

geopandas dataframe.

Return type:

gpd.GeoDataFrame

WigglyRivers.utilities.filesManagement.get_load_formats()[source]

WigglyRivers.utilities.filesManagement.get_save_formats()[source]

WigglyRivers.utilities.filesManagement.load_data(file_path: Path | str, pandas_dataframe: bool = False, *args, **kwargs) → dict | DataFrame[source]

Load data in any of the following formats:: .p, .pickle, .mat, .json, .txt, .csv, .shp, .dbf, .hdf5, .feather

Parameters:

file_path (Union[Path, str]) – file to be loaded.
pandas_dataframe (bool, optional) – Load the data as PandasDataframe. If False, the data will be loaded as a dictionary. Defaults to False.
*args – Additional arguments for each loading function.
**kwargs – Additional keyword arguments for each loading function.

Raises:

TypeError – file_path must be a string or Path.
CE.FormatError – format not implemented.

Returns:

Loaded data.

Return type:

Union[dict, pd.DataFrame]

WigglyRivers.utilities.filesManagement.load_dict_from_hdf5(file_name: Path | str, key_c: str | None = None) → dict[source]

load dictionary from hdf5 file.

Parameters:

file_name (Union[Path, str]) – complete path to the file.
key_c (Union[str, None], optional) – specific key to be loaded from the hdf5 file. If key_c is None, all the keys will be loaded. Defaults to None.

Returns:

loaded dictionary.

Return type:

dict

WigglyRivers.utilities.filesManagement.read_gdb(file_path: Path | str, layer: str, **kwargs) → GeoDataFrame[source]

Read a layer from a geodatabase.

Parameters:

file_path (Union[Path, str]) – Path to the geodatabase.
layer (str) – layer to be read.

Returns:

geopandas dataframe.

Return type:

gpd.GeoDataFrame

WigglyRivers.utilities.filesManagement.recursively_load_dict_contents_from_group(h5file: File, path: str, key_c: str | None = None) → dict[source]

recursively load dictionary from hdf5 file.

Parameters:

h5file (h5py.File) – h5py file object.
path (str) – path to variable.
key_c (Union[str, None], optional) – specific key to be loaded from the hdf5 file. If key_c is None, all the keys will be loaded. Defaults to None.

Returns:

Loaded dictionary

Return type:

dict

WigglyRivers.utilities.filesManagement.recursively_save_dict_contents_to_group(h5file: File, path: str, dic: dict)[source]

recursively save dictionary to hdf5 file

Parameters:

h5file (h5py.File) – h5py file object.
path (str) – path to variable.
dic (dict) – dictionary to be saved.

Raises:

ValueError – save type not implemented.

WigglyRivers.utilities.filesManagement.save_data(data: dict, path_output: Path | str, file_name: str, *args, **kwargs)[source]

Save data in any of the following formats:: .p, .pickle, .mat, .json, .txt, .csv, .shp, .hdf5, .feather

Parameters:

data (dict) – Data to be saved in dictionary format.
path_output (Union[Path, str]) – Path where the data will be saved.
file_name (str) – File name.
*args – Additional arguments for each saving function.
**kwargs – Additional keyword arguments for each saving function.

Raises:

CE.FormatError – Format not implemented.

WigglyRivers.utilities.filesManagement.save_dict_to_hdf5(dic: dict, file_name: str)[source]

save dictionary to hdf5 file

Parameters:

dic (dict) – Dictionary to be saved.
file_name (str) – Complete path to the file.

WigglyRivers.utilities.general_functions module

The functions given on this package allow the user to manipulate and create functions from the computer.

WigglyRivers.utilities.general_functions.circumcenter(tri: Delaunay) → ndarray[source]

Compute the circumcenter of a triangle. The point where the perpendicular bisectors of the sides of the triangle intersect.

Parameters:: tri (Delaunay) – Delaunay triangulation.
Returns:: circumcenter of the triangle.
Return type:: np.ndarray

WigglyRivers.utilities.general_functions.convolution_smoother(x: ndarray, kernel: ndarray, iter: int) → ndarray[source]

Calculates a mean smoothing by convolution.

This function is based on the __convolution_smoother__ of pynumdiff, created by Van Breugel et al. (2022).

Van Breugel, F. V., Liu, Y., Brunton, B. W., & Kutz, J. N. (2022). PyNumDiff: A Python package for numerical differentiation of noisy time-series data. Journal of Open Source Software, 7(71), 4078. https://doi.org/10.21105/joss.04078

Parameters:

x (np.ndarray) – 1xN, Coordinates to differentiate
kernel (np.ndarray) – 1xwindow_size, Kernel used in the convolution.
iter (int) – Number of iterations >= 1.

Returns:

coordinates smoothed.

Return type:

np.ndarray

WigglyRivers.utilities.general_functions.gaussian_function(t: float | ndarray, sigma: ndarray | float) → float | ndarray[source]

Gaussian function

Parameters:

t (Union[float, np.ndarray]) – array of values to evaluate the function.
sigma (Union[np.ndarray, float]) – array of values of the standard deviation.

Returns:

array of values of the gaussian function.

Return type:

Union[float, np.ndarray]

WigglyRivers.utilities.general_functions.savgol_filter(x: ndarray, ds: float, order: int, savgol_window: int, kernel: ndarray) → ndarray[source]

This function performs the savitzky golay filter with a Gaussian filter.

It is based in the functions presented in the pynumdiff package, created by Van Breugel et al. (2022).

Van Breugel, F. V., Liu, Y., Brunton, B. W., & Kutz, J. N. (2022). PyNumDiff: A Python package for numerical differentiation of noisy time-series data. Journal of Open Source Software, 7(71), 4078. https://doi.org/10.21105/joss.04078

Parameters:

x (np.ndarray) – coordinates to filter.
ds (float) – delta in distance.
order (int) – order of the polynomial in the savgol filter.
savgol_window (int) – savgol filter window. It has to be an odd number if an even number is given the function will sum one to the value.
kernel (np.ndarray) – Gaussian kernel to apply additional smoothing to the function.

Raises:

ValueError – if savgol_window is smaller than order.

Returns:

smoothed values of the coordinates.

Return type:

np.ndarray

WigglyRivers.utilities.graphs module

The functions here are used to plot Meanders

class WigglyRivers.utilities.graphs.MidPointLogNorm(vmin=None, vmax=None, midpoint=None, clip=False)[source]: Bases: LogNorm

class WigglyRivers.utilities.graphs.MidPointNorm(vmin=None, vmax=None, midpoint=None, clip=False)[source]: Bases: Normalize

WigglyRivers.utilities.graphs.plot_meander_matplotlib(x_river: ndarray, y_river: ndarray, x_meander: ndarray, y_meander: ndarray) → Figure[source]

plot meander in the river.

Parameters:

x_river (np.ndarray) – x coordinates of the river.
y_river (np.ndarray) – y coordinates of the river.
x_meander (np.ndarray) – x coordinates of the meander.
y_meander (np.ndarray) – y coordinates of the meander.
**kwargs – additional arguments to be passed to the ax.plot.

Returns:

Figure of the plot.

Return type:

plt.Figure

WigglyRivers.utilities.graphs.plot_node(ax: Axes, node: Node, x_var: str, y_var: str, **kwargs) → Axes[source]

plot node in the planimetry.

Parameters:

ax (plt.Axes) – axes of the plot.
node (Node) – Node object.
x_var (str) – variable name of the x coordinate.
y_var (str) – variable name of the y coordinate.

Returns:

Axes of the plot.

Return type:

plt.Axes

WigglyRivers.utilities.graphs.plot_river_spectrum_compiled(river, only_significant: bool = True, idx_data: ndarray | None = None) → Figure | Axes[source]

plot river spectrum.

Parameters:

river (RiverTransect) – RiverTransect object.
only_significant (bool, optional) – flag to show only significant meanders. Defaults to True.
idx_data (Union[np.ndarray, None], optional) – index data to plot. Defaults to None.

Returns:

Figure and Axes of the plot.

Return type:

Union[plt.Figure, plt.Axes]

WigglyRivers.utilities.graphs.plot_river_with_plotly(river, tree: bool = False, meanders: bool = False, curvature_side: int = 1, so: int = 0, mapbox_token: str | None = None, projection: str = 'esri:102003', data_source: str = 'original') → None[source]

plot the river transect with the meanders and the tree using plotly.

Parameters:

river (RiverTransect) – River transect object.
tree (bool, optional) – flag to plot the tree. Defaults to False.
meanders (bool, optional) – flag to plot meanders. Defaults to False.
curvature_side (int, optional) – curveture side of meanders to plot. This parameter can be 1 or -1. Defaults to 1.
so (int, optional) – Stream order to plot. Only used if data_source is ‘smooth’. If 0 all stream orders will be plotted. Defaults to 0.
mapbox_token (Union[str, None], optional) – mapbox token. This will allow to plot the figure with the satellite image at the background. Defaults to None.
projection (str, optional) – projection of the current data. This is needed to convert the data to WGS84 for mapbox plotting. Defaults to “esri:102003”.
data_source (str, optional) – data source use for plotting. Defaults to “original”.

WigglyRivers.utilities.graphs.plot_rivers_matplotlib(rivers, comids: str | list | ndarray, data_source: str = 'resample', **kwargs) → Tuple[Figure, Axes][source]

plot the rivers using matplotlib.

Parameters:

rivers (RiverDatasets) – RiverDatasets object.
comids (Union[str, list, np.ndarray]) – list of comids to be plotted.
data_source (str, optional) – data source of the coordinates. The options are ‘original’ and ‘resample’. Defaults to “resample”.
**kwargs – additional arguments to be passed to the ax.plot.

Returns:

figure and axes of the plot.

Return type:

Tuple[plt.Figure, plt.Axes]

WigglyRivers.utilities.graphs.plot_rivers_plotly(rivers, comids, data_source='resample', mapbox_token=None, current_crs='epsg:4326', zoom=5)[source]

WigglyRivers.utilities.graphs.plot_tree_from_anytree(x: ndarray, y: ndarray, s_curvature: ndarray, wavelength: ndarray, wave: ndarray, tree_scales: dict, gws: ndarray, peaks_gws: ndarray, id_river: int | float | str, coi: ndarray | None = None, tree_ids: list | None = None, node_ids: int | None = None, min_s: ndarray | None = None, include_removed: bool = False, scale_by_width: bool = False, title: str | None = None, **kwargs) → Tuple[Figure, Axes][source]

plot the river, the curvature, and the wavelet response using anytree tree.

Parameters:

x (np.ndarray) – x coordinates of the river.
y (np.ndarray) – y coordinates of the river.
s_curvature (np.ndarray) – Arc length of the river.
wavelength (np.ndarray) – Wavelength of the wavelet response.
wave (np.ndarray) – power of the wavelet response.
tree_scales (dict) – treescales object.
gws (np.ndarray) – generalized wavelet spectrum.
peaks_gws (np.ndarray) – peaks of the generalized wavelet spectrum.
id_river (Union[int, float, str]) – river id.
coi (Union[np.ndarray, None], optional) – cone of influence. Defaults to None.
tree_ids (Union[list, None], optional) – tree ids to plot. Defaults to None.
node_ids (Union[int, None], optional) – node ids to plot. Defaults to None.
min_s (Union[np.ndarray, None], optional) – cut in this spectrum. Defaults to None.
include_removed (bool, optional) – include removed branches. Defaults to False.
scale_by_width (bool, optional) – scale distance by width. Defaults to False.
title (Union[str, None], optional) – title of the figure. Defaults to None.

Raises:

ValueError – node_ids must be None if more than one tree_id

Returns:

figure and Axes of the plot.

Return type:

Tuple[plt.Figure, plt.Axes]

WigglyRivers.utilities.graphs.plot_wavelet_system(x: ndarray, y: ndarray, c: ndarray, s_curvature: ndarray, cwt_matrix: ndarray, scales: ndarray, cwt_period: ndarray, zc_lines: ndarray | None = None, zc_sign: ndarray | None = None, poly: ndarray | None = None, ml_tree: ndarray | None = None, peak_row: ndarray | None = None, peak_col: ndarray | None = None, xc: ndarray | None = None, yc: ndarray | None = None, regions: ndarray | list | None = None, save: bool = False, path: str | Path | None = None, name: str | None = None, cmap: str = 'Spectral', meanders: ndarray | list | None = None, curvature_side: int = 1, **kwargs) → Tuple[Figure, Axes][source]

This function plots the river, the curvature, and the wavelet response. It will also plot the zero-crossings and the peaks of the wavelet response, and the tree that shows the location of the meanders with dots.

Parameters:

x (np.ndarray) – x coordinates of the river.
y (np.ndarray) – y coordinates of the river.
c (np.ndarray) – Curvature of the river.
s_curvature (np.ndarray) – Arc length of the river.
cwt_matrix (np.ndarray) – Wavelet response of the river.
scales (np.ndarray) – Scales of the wavelet response.
cwt_period (np.ndarray) – Period of the wavelet response.
zc_lines (Union[np.ndarray, None], optional) – zero-crossing lines of the wavelet response. If None this lines will not be plotted. Defaults to None.
zc_sign (Union[np.ndarray, None], optional) – sign of the zero-crossing lines of the wavelet response. If None this lines will not be plotted. Defaults to None.
poly (Union[np.ndarray, None], optional) – Polygons that delimits the region in the wavelet response. If None this regions will not be plotted. Defaults to None.
ml_tree (Union[np.ndarray, None], optional) – Connection between the nodes of the tree. If None this nodes will not be plotted. Defaults to None.
peak_row (Union[np.ndarray, None], optional) – Row of the peaks of the wavelet response for each polygon region. Defaults to None.
peak_col (Union[np.ndarray, None], optional) – Columns of the peaks of the wavelet response for each plygon region. Defaults to None.
xc (Union[np.ndarray, None], optional) – x coordinates of the tree nodes projected to the planimetry. Defaults to None.
yc (Union[np.ndarray, None], optional) – y coordinated of the tree nodes projected to the planimetry. Defaults to None.
regions (Union[np.ndarray, list, None], optional) – regions of the wavelet response. Defaults to None.
save (bool, optional) – flag to save the figure. If False the figure will not be saved. Defaults to False.
path (Union[str, pl.Path, None], optional) – path to save the figure. This parameter will only be used if save is True. Defaults to None.
name (Union[str, None], optional) – name of the figure. This parameter will only be used if save is True. Defaults to None.
cmap (Union[str], optional) – color map of the wavelet response function. Defaults to “Spectral”.
meanders (Union[np.ndarray, list, None], optional) – meander x and y coordinates. Defaults to None.
curvature_side (int, optional) – side of the curvature to plot. This parameter will only be used if meanders is not None. The parameter can be 1 or -1. Defaults to 1.

Returns:

figure and axes of the plot.

Return type:

Tuple[plt.Figure, plt.Axes]

WigglyRivers.utilities.interactivePlotly module

The functions here are used to have the ineractive plots for the Meander Characterization App.

WigglyRivers.utilities.interactivePlotly.check_meander_id(meander_ids: list) → int[source]

Check meander ids.

Parameters:: meander_ids (list) – Meander IDs.
Returns:: new meander id.
Return type:: int

WigglyRivers.utilities.interactivePlotly.create_hover_template_meander(meander_id: int, river_obj=None) → str[source]

create hover template for meanders.

Parameters:

meander_id (int) – Meander ID
river_obj (Union[None, RiverTransect], optional) – RiverTransect object. Defaults to Union[None, RiverTransect].

Returns:

hover template.

Return type:

str

WigglyRivers.utilities.interactivePlotly.load_meanders(f: FigureWidget, river_obj, mapbox_token: str = None, current_crs: str = 'epsg:4326') → FigureWidget[source]

load current selection of meanders.

Parameters:

f (go.FigureWidget) – plotly figure widget.
river_obj (RiverTransect) – RiverTransect object.
mapbox_token (Union[bool, None], optional) – mapbox token. This is needed to have the satellite image in the background. If None the plot will have a white background. Defaults to None.
current_crs (str, optional) – Current projection of the data. This is needed to reproject the data a WGS84 for mapbox plotting. Defaults to “epsg:4326”.

Returns:

Figure widget of the interactive plot.

Return type:

go.FigureWidget

WigglyRivers.utilities.interactivePlotly.plot_interactive_river_plain(x: list | ndarray, y: list | ndarray, clicked_points: list = [], meander_ids: list = [], river_obj=None, inflection_flag: bool = False, mapbox_token: bool | None = None, current_crs: str = 'epsg:4326', zoom: int = 5) → FigureWidget[source]

This function plots an interactive plot to detect meanders in a river planform. This function can only be used in a Jupyter Notebook.

Parameters:

x (Union[list, np.ndarray]) – x coordinates of the river.
y (Union[list, np.ndarray]) – y coordinates of the river.
clicked_points (list, optional) – list of clicked points. Defaults to [].
meander_ids (list, optional) – meander ids for the clicked points. Defaults to [].
river_obj (Union[RiverTransect, None], optional) – RiverTransect object. Defaults to None.
inflection_flag (bool, optional) – flag to plot infection points. Defaults to False.
mapbox_token (Union[bool, None], optional) – mapbox token. This is needed to have the satellite image in the background. If None the plot will have a white background. Defaults to None.
current_crs (str, optional) – Current projection of the data. This is needed to reproject the data a WGS84 for mapbox plotting. Defaults to “epsg:4326”.
zoom (int, optional) – Zoom of the plot. Defaults to 5.

Returns:

Figure widget of the interactive plot.

Return type:

go.FigureWidget

WigglyRivers.utilities.utilities module

The functions given on this package allow the user to manipulate and create functions from the computer.

WigglyRivers.utilities.utilities.cr_folder(path: Path | str)[source]

Create a folder in a specific path.

Parameters:: path (Union[pl.Path, str]) – Path to create the folder.

WigglyRivers.utilities.utilities.fix_widget_error()[source]

Fix FigureWidget - ‘mapbox._derived’ Value Error. Adopted from:

https://github.com/plotly/plotly.py/issues/2570#issuecomment-738735816

WigglyRivers.utilities.utilities.get_folders(path: Path | str) → list[source]

get folders in a specific path.

Parameters:: path (Union[pl.Path, str]) – get folders in a specific path.
Returns:: list of folders in the path.
Return type:: list

WigglyRivers.utilities.utilities.toc(time1: float)[source]

print the time of execution.

Parameters:: time1 (float) – time when execution started given by time.time().

WigglyRivers.utilities.utilities.unzip_file(zip_file: Path | str, path_output: Path | str)[source]

unzip a file to a specific path.

Parameters:

zip_file (Union[pl.Path, str]) – Path to the zip file.
path_output (Union[pl.Path, str]) – Path to extract the zip file.

WigglyRivers.utilities package

Submodules

WigglyRivers.utilities.Logger module

WigglyRivers.utilities.classExceptions module

WigglyRivers.utilities.filesManagement module

WigglyRivers.utilities.general_functions module

WigglyRivers.utilities.graphs module

WigglyRivers.utilities.interactivePlotly module

WigglyRivers.utilities.utilities module

Module contents