numbacs.extraction ================== .. py:module:: numbacs.extraction .. autoapi-nested-parse:: Extraction package for numbacs. Submodules ---------- .. toctree:: :maxdepth: 1 /autoapi/numbacs/extraction/elliptic/index /autoapi/numbacs/extraction/hyperbolic/index /autoapi/numbacs/extraction/ridges/index Package Contents ---------------- .. py:function:: ftle_ridge_pts(f, eigvec_max, x, y, sdd_thresh=0.0, percentile=0) Compute FTLE ridge points by finding points (with subpixel accuracy) at which: ftle > 0 (or percentile of ftle), directional derivaitve of ftle (in eigvec_max direction) is 0, second directional derivative of ftle (in eigvec_max direction) is greater than sdd_thresh (in magnitude). :param f: ftle array. :type f: np.ndarray, shape = (nx,ny) :param eigvec_max: maximum eigenvector of Cauchy Green tensor. :type eigvec_max: np.ndarray, shape = (nx,ny,2) :param x: array containing x-values. :type x: np.ndarray, shape = (nx,) :param y: array containing y-values. :type y: np.ndarray, shape = (ny,) :param sdd_thresh: threshold for second directional derivative, should be at least 0. The default is 0. :type sdd_thresh: float, optional :param percentile: percentile of ftle used for min allowed value. The default is 0. :type percentile: int, optional :returns: **r_pts** -- ridge points. :rtype: np.ndarray, shape = (ridge_bool.sum(),2) .. py:function:: ftle_ridges(f, eigvec_max, x, y, sdd_thresh=0.0, percentile=0, min_ridge_pts=3) From ridge points from _ftle_ridges, extract connected ridges where a connected ridge is defined by a collection of points having continuous neighbors that are ridge points. :param f: ftle array. :type f: np.ndarray, shape = (nx,ny) :param eigvec_max: maximum eigenvector of Cauchy Green tensor. :type eigvec_max: np.ndarray, shape = (nx,ny,2) :param x: array containing x-values. :type x: np.ndarray, shape = (nx,) :param y: array containing y-values. :type y: np.ndarray, shape = (ny,) :param sdd_thresh: threshold for second directional derivative, should be at least 0. The default is 0. :type sdd_thresh: float, optional :param percentile: percentile of ftle used for min allowed value. The default is 0. :type percentile: int, optional :param min_ridge_pts: minimum points allowed in ridge. The default is 3. :type min_ridge_pts: int :returns: list containing each connected ridge. :rtype: list .. py:function:: ftle_ordered_ridges(f, eigvec_max, x, y, dist_tol, ep_tan_ang=pi / 4, min_ridge_pts=5, sdd_thresh=0.0, percentile=0, c=1.0) Computes ftle ridge points and links points into ridges. After this is done, ridges that should be connected are searched for and connected if they meet certain critera. Criteria: if two ridges have endpoints that are within dist_tol and the angle between the tangent of the ridge at the endpoints and vector connecting the endpoints is less than ep_tan_ang, connect ridges. :param f: ftle array. :type f: np.ndarray, shape = (nx,ny) :param eigvec_max: maximum eigenvector of Cauchy Green tensor. :type eigvec_max: np.ndarray, shape = (nx,ny,2) :param x: array containing x-values. :type x: np.ndarray, shape = (nx,) :param y: array containing y-values. :type y: np.ndarray, shape = (ny,) :param dist_tol: tolerance used to consider new endpoint for connection. :type dist_tol: float :param ep_tan_ang: angle used to confirm endpoints are in line. The default is pi/4. :type ep_tan_ang: float :param min_ridge_pts: minimum points allowed in ridge after endpoints are connected. The default is 5. :type min_ridge_pts: int, optional :param sdd_thresh: threshold for second directional derivative, should be at least 0.0. The default is 0. :type sdd_thresh: float, optional :param percentile: percentile of ftle used for min allowed value. The default is 0. :type percentile: int, optional :param c: scaling for angle portion of metric used in linking algorithm. The default is 1.0. :type c: float, optional :returns: **ridges** -- list containing connected, ordered ridges. :rtype: list .. py:function:: hyperbolic_lcs(eigval_max, eigvecs, x, y, h, steps, lf, lmin, r, nmax, dist_tol, nlines, lambda_avg_min=0, percentile=0, ep_dist_tol=0.0, arclen_flag=False) Wrapper for _compute_lcs which also performs comparison of close enough LCS and returns most attracting/repelling LCS in a list. :param eigval_max: array containing maximum eigenvalues. :type eigval_max: np.ndarray, shape = (nx,ny) :param eigvecs: array containing eigenvectors. :type eigvecs: np.ndarray, shape = (nx,ny,2,2) :param x: array containing x-values. :type x: np.ndarray, shape = (nx,) :param y: array containing y-values. :type y: np.ndarray, shape = (ny,) :param h: step size used in Runge-Kutta solver. :type h: float :param steps: maximum number of steps for Runge-Kutta solver. :type steps: int :param lf: maximum failure distance of LCS criteria allowed. :type lf: float :param lmin: minumum allowed length for LCS. :type lmin: float :param r: radius in which points will be discared after a maximum is found at the center. :type r: float :param nmax: number of maxima, i.e. initial conditions for tensorlines. :type nmax: int :param dist_tol: distance tolerance used when comparing candidate LCS. If dist_tol = 0.0, no comparison will be made and all candidate LCS will be returned. :type dist_tol: float :param nlines: number of lines in dimension with largest length used when comparing candidate LCS, number of lines in other dimension will be scaled by the ratio of the dimensions lengths. Only used if dist_tol > 0. :type nlines: int :param lambda_avg_min: minimum allowed value for lambda_avg for curve to be considered for lcs. The default is 0. :type lambda_avg_min: int :param percentile: percentile of eigval_max used for min allowed value. The default is 0. :type percentile: int, optional :param ep_dist_tol: value used to compare starting/ending points of curves, if endpoints are within this value, all curves with smaller lambda_avg values are discarded. If ep_dist_tol <= 0.0, this step is skipped and endpoints are not compared. The default is 0.0. :type ep_dist_tol: float, optional :param arclen_flag: flag to determine if the average attraction/repulsion rate along curve is used or if the total attraction/repulsion rate for a curve is used for comparison. The default is False. :type arclen_flag: bool, optional :returns: **lcs** -- collection of most attracting/repelling LCS. :rtype: list .. py:function:: hyperbolic_oecs(eigval_max, eigvecs, x, y, r, h, steps, maxlen, minval, n=-1) Wrapper for _hyperbolic_oecs that returns list of oecs saddles. :param eigval_max: array containing values of max eigenvalue of S. :type eigval_max: np.ndarray, shape = (nx,ny) :param eigvecs: array containing both minimum and maximum eigenvectors of S. :type eigvecs: np.ndarray, shape = (nx,ny,2,2) :param x: array containing x-values. :type x: np.ndarray, shape = (nx,) :param y: array containing x-values. :type y: np.ndarray, shape = (ny,) :param r: radius used to find local maxima. :type r: float :param h: step size used in Runge-Kutta solver. :type h: float :param steps: maximum number of steps for Runge-Kutta solver. :type steps: int :param maxlen: maximum allowed length for oecs curve. :type maxlen: float :param minval: minimum value allowed for eigval_max. :type minval: float :param n: number of local maxima to look for, if n = -1, all are used. The default is -1. :type n: int, optional :returns: **oecs_saddles** -- list containing oecs saddles defined by oecs forward and oecs backward curves. :rtype: list .. py:function:: rotcohvrt(lavd, x, y, r, convexity_method='convex_hull', convexity_deficiency=0.005, min_val=-1.0, nlevs=20, start_level=0.0, end_level=0.0, min_len=0.0) Compute rotationally coherent vortices which are (approximately) convex closed contours of the lavd (or ivd) field. :param lavd: array containing lavd values. :type lavd: np.ndarray, shape = (nx,ny) :param x: array containing x-values. :type x: np.ndarray, shape = (nx,) :param y: array containing y-values. :type y: np.ndarray, shape = (ny,) :param r: radius in which points will be discared after a maximum is found at the center. :type r: float :param convexity_method: method used to determine if closed curve is convex, options are 'convex_hull' which calculates the relative difference in area of the curve and its convex hull, 'angle' which checks if angle between succesive edges exceeds convexity_deficiency in the negative direction. The default is 'convex_hull'. :type convexity_method: str, optional :param convexity_deficiency: value used to allow convexity deficiency up to this value, if 'convex_hull' method is used this is the allowable relative difference in area, if 'angle' method is used this is the allowable angle. The default is 5e-3. :type convexity_deficiency: float, optional :param min_val: minimum value allowed for maxima of the lavd field, if equals -1.0, the 80th percentile of the lavd is used. The default is -1.0. :type min_val: float, optional :param nlevs: number of levels of contours to use when searching for convex curves. The default is 20. :type nlevs: int, optional :param start_level: starting level of contours for search, if equals 0.0 then the 70th percentile of the lavd is used. The default is 0.0. :type start_level: float, optional :param end_level: value for last contour level to be checked, if equals 0.0 then the maximum of the lavd is used. The default is 0.0. :type end_level: float, optional :returns: **rcv** -- list containing rotationally coherent vortices and corresponding vortex centers. :rtype: list