# pyewt.boundaries1d module

pyewt.boundaries1d.adaptive_bounds_adapt(f, params)

  Adapt given boundaries to actual lowest minima

  Parameters:

    - f (nparray) – vector containing the spectrum used to find the minima

    - params (Dictionary) – must have params[“degree”] set to the wanted polynomial degree

  Returns:

    list of updated boundaries

  Return type:

    bounds - nparray

  Notes

  This function adapt an initial set of boundaries to the studied signal. First it computes some neighborhood from the initial boundaries then it detects the global minima in each neighborhood. The local minima are computed from f.

  Author: Jerome Gilles Institution: San Diego State University Version: 1.0 (12/18/2024)

pyewt.boundaries1d.boundaries_completion(f, bounds, NT)

  Complete set of given boundaries

  Parameters:

    - f (nparray) – vector containing the spectrum

    - nparray (bounds -) – list of previously detected boundaries

    - N (integer) – number of wanted supports

  Returns:

    Updated list of boundaries

  Return type:

    bounds - nparray

  Notes

  This function complete the list of detected boundaries to make sure the minimum amount of modes is NT. If that minimum is already reached then the function returns the original set of boundaries. If completion is needed, then the high frequencies support is evenly subdivided to provide the extra boundaries.

  Author: Jerome Gilles Institution: San Diego State University Version: 1.0 (12/18/2024)

pyewt.boundaries1d.boundaries_detect(f, params)

  Detect meaningful 1D boundaries

  Parameters:

    - f (nparray) – vector containing the spectrum

    - params (Dictionary) – must be set properly accordingly to the options described above

  Returns:

    - bounds - nparray – Updated list of boundaries

    - presig - nparray – Preprocessed spectrum used for the detection

  Notes

  This function complete the list of detected boundaries to make sure the minimum amount of modes is NT. If that minimum is already reached then the function returns the original set of boundaries. If completion is needed, then the high frequencies support is evenly subdivided to provide the extra boundaries.

  If params[“log”] is set to True, then the detection is performed on the logarithm of f, otherwise it will be on f itself.

  Two types of preprocessing are available to “clean” the spectrum:

  - A global trend remover method is set via params[“globtrend”]:

      - “none” : does nothing, returns f

      - “powerlaw”uses a power law to estimate the trend, returns

          f - powerlaw(f)

      - “polylaw”: uses a polynomial interpolation of degree specified

          by params[“degree”] to estimate the trend, returns f - polynomial(f)

      - “morpho”uses morphological operators, returns

          f - (opening(f)+closing(f))/2

      - “tophat”uses morphological operators, returns

          f - opening(f)

      - “opening”returns

          opening(f)

  - A regularization method is set via params[“reg”]:

      - “none” : does nothing, returns f

      - “gaussian”convolve f with a Gaussian of length and standard

          deviation given by params[“lengthfilter”] and params[“sigmafilter”], respectively

      - “average”: convolve f with a constant filter of length given

          by params[“lengthfilter”]

      - “closing”applies the morphological closing operator of length

          given by params[“lengthfilter”]

  The wanted boundary detection method must be set in params[“detect”]. The available options are: - “localmax” : select the mid-point between consecutive maxima.

  > params[“N”] must be set to the expected number of modes.

  - “localmaxmin”select the lowest minima between consecutive

      maxima of the preprocessed spectrum. params[“N”] must be set to the expected number of modes.

  - “localmaxminf”select the lowest minima between consecutive

      maxima where the minima are detected on the original spectrum instead of the preprocessed one. params[“N”] must be set to the expected number of modes.

  - “adaptivereg”this method re-adjust a set of provided initial

      boundaries based on the actual lowest minima of the preprocessed spectrum params[“InitBounds”] must be set with a vector of initial boundaries

  - “adaptive”this method re-adjust a set of provided initial

      boundaries based on the actual lowest minima of the original spectrum params[“InitBounds”] must be set with a vector of initial boundaries

  - “scalespace”uses the scale-space detection technique to

      automatically find the boundaries (including their number) params[“typeDetect”] must be set to the wanted classification method. The available options are: - “otsu” : uses Otsu’s technique - “halfnormal” : uses a half-normal law to model the problem - “empiricallaw” : uses the data itself to build a model of the problem - “mean” : threshold is fixed as the mean of the data - “kmeans” : uses kmeans to classify

  For the automatic detection methods, a completion step is available is the number of detected modes is lower than an expected value params[“N]. If needed, the last high frequency support is evenly splitted. This step is performed if params[“Completion”] is set to True.

  Author: Jerome Gilles Institution: San Diego State University Version: 1.0 (12/18/2024)

pyewt.boundaries1d.empiricallaw(L, ind)

  Detect meaningful minima using the epsilon-meaningful method (empirical law)

  Parameters:

    - L (nparray) – vector of the length of the minima curves

    - ind (nparray) – vector containing the indices of the position of the original minima

  Returns:

    - bounds - nparray – list of the indices of the position of the meaningful minima

    - th - number – detected scale threshold

  Notes

  This function classifies the set of minima curve lengths stored in L into the ones which are epsilon-meaningful for an empirical law fitted. It returns the meaninful ones and the detected threshold.

  Author: Jerome Gilles Institution: San Diego State University Version: 1.0 (12/18/2024)

pyewt.boundaries1d.gss_boundariesdetect(f, type)

  Extract meaningful boundaries by scale-space method

  Parameters:

    - f (1D array) – input vector

    - type (string) – method to be used: “otsu”, “halfnormal”, “empiricallaw”, “mean”, “kmeans”

  Returns:

    - bounds - nparray – list of indices of the position of the detected local minima

    - plane (lil_matrix) – scale-space plane representation

    - L - nparray – vector containing the length of the scale-space curves

    - th - number – detected scale threshold

  Notes

  This function builds a scale-space representation of the provided histogram and then extract the meaningful minima which will correspond to segmenting the histogram. It returns an array bounds containing the indices of the boundaries, the set of length of the scale-space curves, and the detected threshold.

  Author: Jerome Gilles Institution: San Diego State University Version: 1.0 (12/11/2024)

pyewt.boundaries1d.halfnormallaw(L, ind, Lmax)

  Detect meaningful minima using the epsilon-meaningful method (half-normal law)

  Parameters:

    - L (nparray) – vector of the length of the minima curves

    - ind (nparray) – vector containing the indices of the position of the original minima

    - Lmax (number) – maximum possible length of a minima curve (i.e. number of columns in the scale-space plane)

  Returns:

    - bounds - nparray – list of the indices of the position of the meaningful minima

    - th - number – detected scale threshold

  Notes

  This function classifies the set of minima curve lengths stored in L into the ones which are epsilon-meaningful for an half-normal law fitted to the data. It returns the meaninful ones and the detected threshold.

  Author: Jerome Gilles Institution: San Diego State University Version: 1.0 (12/18/2024)

pyewt.boundaries1d.kmeansdetect(L, ind)

  Detect meaningful minima using kmeans

  Parameters:

    - L (nparray) – vector of the length of the minima curves

    - ind (nparray) – vector containing the indices of the position of the original minima

  Returns:

    - bounds - nparray – list of the indices of the position of the meaningful minima

    - th - number – detected scale threshold

  Notes

  This function classifies the set of minima curve lengths stored in L into the ones which meaningful based on a kmeans clustering. It returns the meaninful ones and the detected threshold.

  Author: Jerome Gilles Institution: San Diego State University Version: 1.0 (12/18/2024)

pyewt.boundaries1d.lengthscalecurve(plane)

  Compute the length of curves in the scale-space plane

  Parameters:

    plane (lil_matrix) – scale-space plane representation

  Returns:

    - Length - nparray – list of the length of each curve

    - Indices - nparray – list of indices of the position of the original local minima

  Notes

  This function returns a vector containing the length of each scale-space curves (in terms of scale lifespan) and a vector containing the indices corresponding to the position of the original local minima (i.e. scale 0)

  Author: Jerome Gilles Institution: San Diego State University Version: 1.0 (12/18/2024)

pyewt.boundaries1d.localmax(f, N)

  Find mid-point between maxima

  Parameters:

    - f (nparray) – vector containing the spectrum

    - N (integer) – number of wanted supports

  Returns:

    list of N-1 boundaries

  Return type:

    bounds - nparray

  Notes

  This function detects the position of the N-1 boundaries which define N supports. These positions correspond to the mid-point between consecutive local maxima.

  Author: Jerome Gilles Institution: San Diego State University Version: 1.0 (12/17/2024)

pyewt.boundaries1d.localmaxmin(f, N, f2)

  Find lowest minima between maxima

  Parameters:

    - f (nparray) – vector containing the preprocessed spectrum

    - N (integer) – number of wanted supports

    - f2 (nparray) – vector containing the original spectrum used to find the minima

  Returns:

    list of N-1 boundaries

  Return type:

    bounds - nparray

  Notes

  This function detects the position of the N-1 boundaries which define N supports. These positions correspond to the lowest minima between consecutive local maxima.

  Author: Jerome Gilles Institution: San Diego State University Version: 1.0 (12/17/2024)

pyewt.boundaries1d.localmaxmin2(f)

  Detect the lowest local minima between two consecutive local maxima

  Parameters:

    f (nparray) – input vector

  Returns:

    list of indices of the position of the detected local minima

  Return type:

    bounds - nparray

  Notes

  This function return an array bounds containing the indices of the lowest local minima between two consecutive local maxima in a vector f

  Author: Jerome Gilles Institution: San Diego State University Version: 1.0 (12/18/2024)

pyewt.boundaries1d.maxcheckplateau(L)

  Check plateau of maxima

  ## Parameters:

  - L: nparray

      vector containing the indices of detected minima

  Returns: -th: center of the plateau. If no plateau, returns 1.

  Notes

  Check if maxima form a plateau. For those who do, it returns the position in the center of the plateau.

  Author: Jerome Gilles Institution: San Diego State University Version: 1.0 (12/18/2024)

pyewt.boundaries1d.meaningfulscalespace(f, plane, type)

  Extract meaningful boundaries from the scale-space plane with the selected method

  Parameters:

    - f (nparray) – input vector

    - plane (lil_matrix) – scale-space plane representation

    - type (string) – method to be used: “otsu”, “halfnormal”, “empiricallaw”, “mean”, “kmeans”

  Returns:

    - bounds - nparray – list of indices of the position of the detected local minima

    - L - nparray – vector containing the length of the scale-space curves

    - th - number – detected scale threshold

  Notes

  This function extracts the meaningful minima which will correspond to segmenting the histogram f based on its scale-space representation in plane. It returns an array bounds containing the indices of the boundaries, the set of length of the scale-space curves L, and the detected threshold th.

  Author: Jerome Gilles Institution: San Diego State University Version: 1.0 (12/18/2024)

pyewt.boundaries1d.meanth(L, ind)

  Detect meaningful minima using a mean threshold

  Parameters:

    - L (nparray) – vector of the length of the minima curves

    - ind (nparray) – vector containing the indices of the position of the original minima

  Returns:

    - bounds - nparray – list of the indices of the position of the meaningful minima

    - th - number – detected scale threshold

  Notes

  This function classifies the set of minima curve lengths stored in L into the ones which meaningful based on a threshold computed as the mean of L. It returns the meaninful ones and the detected threshold.

  Author: Jerome Gilles Institution: San Diego State University Version: 1.0 (12/18/2024)

pyewt.boundaries1d.morphoclosing1D(f, sizeel)

  1D Morphological Closing

  Parameters:

    - f (nparray) – vector containing the histogram

    - sizeel (integer) – size of the structural element

  Returns:

    the closed histogram

  Return type:

    clo - nparray

  Notes

  This function applies the 1D morphological closing to f with a structural element of size sizeel (i.e. opening = erosion(dilation). It returns the closed version of f.

  Author: Jerome Gilles Institution: San Diego State University Version: 1.0 (12/16/2024)

pyewt.boundaries1d.morphodilation1D(f, sizeel)

  1D Morphological Dilation

  Parameters:

    - f (nparray) – vector containing the histogram

    - sizeel (integer) – size of the structural element

  Returns:

    the dilated histogram

  Return type:

    s - nparray

  Notes

  This function applies the 1D morphological dilation to f with a structural element of size sizeel. It returns the dilated version of f.

  Author: Jerome Gilles Institution: San Diego State University Version: 1.0 (12/16/2024)

pyewt.boundaries1d.morphoerosion1D(f, sizeel)

  1D Morphological Erosion

  Parameters:

    - f (nparray) – vector containing the histogram

    - sizeel (integer) – size of the structural element

  Returns:

    the eroded histogram

  Return type:

    s - nparray

  Notes

  This function applies the 1D morphological erosion to f with a structural element of size sizeel. It returns the eroded version of f.

  Author: Jerome Gilles Institution: San Diego State University Version: 1.0 (12/16/2024)

pyewt.boundaries1d.morphoopening1D(f, sizeel)

  1D Morphological Opening

  Parameters:

    - f (nparray) – vector containing the histogram

    - sizeel (integer) – size of the structural element

  Returns:

    the opened histogram

  Return type:

    ouv - nparray

  Notes

  This function applies the 1D morphological opening to f with a structural element of size sizeel (i.e. opening = dilation(erosion)). It returns the opened version of f.

  Author: Jerome Gilles Institution: San Diego State University Version: 1.0 (12/16/2024)

pyewt.boundaries1d.morphotrend(h)

  Remove global trend using morphological opening + closing

  Parameters:

    h (nparray) – vector containing the histogram

  Returns:

    the processed histogram

  Return type:

    presig - nparray

  Notes

  This function estimates the trend as half the sum of the morphological opening + closing of h. It then return the original histogram minus the trend.

  Author: Jerome Gilles Institution: San Diego State University Version: 1.0 (12/16/2024)

pyewt.boundaries1d.openingtrend(h)

  Remove global trend using morphological opening

  Parameters:

    h (nparray) – vector containing the histogram

  Returns:

    the processed histogram

  Return type:

    presig - nparray

  Notes

  This function estimates the trend using the opening morphological operator. It then return the opened histogram.

  Author: Jerome Gilles Institution: San Diego State University Version: 1.0 (12/17/2024)

pyewt.boundaries1d.otsumethod(L, ind)

  Detect meaningful minima using Otsu’s method

  Parameters:

    - L (nparray) – vector of the length of the minima curves

    - ind (nparray) – vector containing the indices of the position of the original minima

  Returns:

    - bounds - nparray – list of the indices of the position of the meaningful minima

    - th - number – detected scale threshold

  Notes

  This function classifies the set of minima curve lengths stored in L into two classes by using Otsu’s method. It returns the meaninful ones and the detected threshold.

  Author: Jerome Gilles Institution: San Diego State University Version: 1.0 (12/18/2024)

pyewt.boundaries1d.plangaussianscalespace(f, n=3, t=0.16)

  Build the scale-space plane containing the detected local minima across the scales

  Parameters:

    - f (nparray) – input vector

    - n (integer) – size of the gaussian kernel (default = 3)

    - t (real number) – initial scale (default = 0.16)

  Returns:

    1 for detected local minima, 0 otherwise

  Return type:

    plane - 2D sparse lil_matrix (each column corresponds to a scale)

  Notes

  This function return a sparse lil_matrix where entries equal to 1 correspond to the position of the detected lowest local minima across the different scales. The scale-space is built using the discrete Gaussian kernel based on the modified Bessel function of the first kind.

  Author: Jerome Gilles Institution: San Diego State University Version: 1.0 (12/18/2024)

pyewt.boundaries1d.plotboundaries(f, bounds, title, SamplingRate=-1, logtag=0, Cpx=0)

  Plot 1D boundaries

  Parameters:

    - f (nparray) – input vector which contains the histogram

    - bounds (nparray) – list of indices of the position of the detected local minima

    - title (string) – title to be added to the plot

  Notes

  Plot the position of the meaningful minima on top of the original histogram.

  Author: Jerome Gilles Institution: San Diego State University Version: 1.0 (12/18/2024)

pyewt.boundaries1d.plotplane(plane, hideaxes=False)

  Plot the scale-space plane

  ## Parameters:

  - plane: lil_matrix sparse matrix

      matrix containing the scale-space plane

  - hideaxes: False (default) or True

      if False, the axes will be plotted, if True , they will be hidden

  Notes

  This function plots the scale-space plane containing the position of the local minima through the scales

  Author: Jerome Gilles Institution: San Diego State University Version: 1.0 (12/11/2024)

pyewt.boundaries1d.polytrend(h, params)

  Remove global trend using a polynomial estimator

  Parameters:

    - h (nparray) – vector containing the histogram

    - params (Dictionary) – must have params[“degree”] set to the wanted polynomial degree

  Returns:

    the processed histogram

  Return type:

    presig - nparray

  Notes

  This function fits a polynomial of degree specified by params to the provided histogram h. It then return the original histogram minus the polynomial estimator.

  Author: Jerome Gilles Institution: San Diego State University Version: 1.0 (12/16/2024)

pyewt.boundaries1d.powerlawtrend(h)

  Remove the global trend using a power law estimator

  Parameters:

    h (nparray) – vector containing the histogram

  Returns:

    the processed histogram

  Return type:

    presig - nparray

  Notes

  This function fits a power law to the provided histogram h. It then return the original histogram minus the power law.

  Author: Jerome Gilles Institution: San Diego State University Version: 1.0 (12/16/2024)

pyewt.boundaries1d.removemerge(f, plane, bounds, th)

  Detect the meaningful minima using kmeans

  Parameters:

    - f (nparray) – histogram to be segmented

    - plane (lil_matrix) – scale-space plane representation

    - array (bounds - 1D) – list of the indices of the position of the meaningful minima

    - number (th -) – detected scale threshold

  Returns:

    updated list of the indices of the position of the meaningful minima

  Return type:

    bounds - nparray

  Notes

  This function manage local minima which merge at some point in the scale-space plane according to the following rules:

  > - if the mergin occur before the scale th then we keep only one minima

  > (the lowest one) as they are not individually meaningful - if the mergin occur after the scale th then we consider that each initial minima is meaningful and we keep them

  Author: Jerome Gilles Institution: San Diego State University Version: 1.0 (12/12/2024)

pyewt.boundaries1d.removetrend(f, params)

  Remove the global trend

  Parameters:

    - h (nparray) – vector containing the histogram

    - params (Dictionary) – must have params[“globtrend”] to be set to one of the methods listed in the notes below. must have params[“degree”] set to the wanted polynomial degree if the polylaw method is selected.

  Returns:

    the processed histogram

  Return type:

    presig - nparray

  Notes

  This function removes the global trend from f using the selected method sets in params[“globtrend”]. The available methods are: - “none” : does nothing, returns f - “powerlaw” : uses a power law to estimate the trend, returns

  > f - powerlaw(f)

  - “polylaw”: uses a polynomial interpolation of degree specified
      by params[“degree”] to estimate the trend, returns

        f - polynomial(f)

  - “morpho”uses morphological operators, returns

      f - (opening(f)+closing(f))/2

  - “tophat”uses morphological operators, returns

      f - opening(f)

  - “opening”returns

      opening(f)

  Author: Jerome Gilles Institution: San Diego State University Version: 1.0 (12/16/2024)

pyewt.boundaries1d.specreg(f, params)

  Spectrum regularization

  Parameters:

    - f (nparray) – vector containing the spectrum

    - params (Dictionary) – must have params[“reg”] to be set to one of the methods listed above must have params[“lengthfilter”] to be set for all methods must have params[“sigmafilter”] to be set to the standard deviation for the Gaussian method

  Returns:

    the processed histogram

  Return type:

    freg - nparray

  Notes

  This function regularizes f using the selected method sets in params[“reg”]. The available methods are: - “none” : does nothing, returns f - “gaussian” : convolve f with a Gaussian of length and standard

  > deviation given by params[“lengthfilter”] and params[“sigmafilter”], respectively

  - “average”: convolve f with a constant filter of length given

      by params[“lengthfilter”]

  - “closing”applies the morphological closing operator of length

      given by params[“lengthfilter”]

  Author: Jerome Gilles Institution: San Diego State University Version: 1.0 (12/17/2024)

pyewt.boundaries1d.tophattrend(h)

  Remove global trend using morphological Top-Hat

  Parameters:

    h (nparray) – vector containing the histogram

  Returns:

    the processed histogram

  Return type:

    presig - nparray

  Notes

  This function estimates the trend using the Top Hat morphological operator i.e. h-opening. It then return the original histogram minus the trend.

  Author: Jerome Gilles Institution: San Diego State University Version: 1.0 (12/17/2024)