Metadata-Version: 2.1
Name: basic-functions
Version: 0.0.4
Summary: very basic functions for data pre-processing and visualization
Author: Noga Mudrik
Author-email: <nmudrik1@jhmi.edu>
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE.txt

Help on module basic_functions:

**FUNCTIONS**

    add_arrow(ax, start, end, arrowprops={'facecolor': 'black', 'width': 1.8, 'alpha': 0.5})
        Add an arrow to the `ax` axis.
        
        Parameters
        ----------
        ax : matplotlib.axes._subplots.AxesSubplot
            The axis to add the arrow to.
        start : tuple of floats
            The starting coordinates of the arrow in (x, y) format.
        end : tuple of floats
            The ending coordinates of the arrow in (x, y) format.
        arrowprops : dict, optional
            A dictionary of properties for the arrow, by default 
            {'facecolor': 'black', 'width': 1.8, 'alpha': 0.5}.
            
        Returns
        -------
        None
    
    
    ------------------------------------------------------------------------------------------
    add_dummy_sub_legend(ax, colors, lenf, label_base='f')
        Add a sub-legend to the plot for the specified colors.
        
        Parameters:
        - ax (matplotlib.axes.Axes): The matplotlib axes to add the sub-legend to.
        - colors (list): A list of colors to add to the sub-legend.
        - lenf (int): The number of colors to include in the sub-legend.
        - label_base (str): The base string for the label of each color. (default: 'f')
        
        Returns: None
    
    ------------------------------------------------------------------------------------------
    add_labels(ax, xlabel='X', ylabel='Y', zlabel='', title='', xlim=None, ylim=None, zlim=None, xticklabels=array([None], dtype=object), yticklabels=array([None], dtype=object), xticks=[], yticks=[], legend=[], ylabel_params={}, zlabel_params={}, xlabel_params={}, title_params={})
        Add labels, titles, limits, etc. to a figure.
        
        Parameters:
        ax (subplot): The subplot to be edited.
        xlabel (str, optional): The label for the x-axis. Defaults to 'X'.
        ylabel (str, optional): The label for the y-axis. Defaults to 'Y'.
        zlabel (str, optional): The label for the z-axis. Defaults to ''.
        title (str, optional): The title for the plot. Defaults to ''.
        xlim (list or tuple, optional): The limits for the x-axis. Defaults to None.
        ylim (list or tuple, optional): The limits for the y-axis. Defaults to None.
        zlim (list or tuple, optional): The limits for the z-axis. Defaults to None.
        xticklabels (array, optional): The labels for the x-axis tick marks. Defaults to np.array([None]).
        yticklabels (array, optional): The labels for the y-axis tick marks. Defaults to np.array([None]).
        xticks (list, optional): The positions for the x-axis tick marks. Defaults to [].
        yticks (list, optional): The positions for the y-axis tick marks. Defaults to [].
        legend (list, optional): The legend for the plot. Defaults to [].
        ylabel_params (dict, optional): Additional parameters for the y-axis label. Defaults to {}.
        zlabel_params (dict, optional): Additional parameters for the z-axis label. Defaults to {}.
        xlabel_params (dict, optional): Additional parameters for the x-axis label. Defaults to {}.
        title_params (dict, optional): Additional parameters for the title. Defaults to {}.
    
    ------------------------------------------------------------------------------------------
    cal_next_FHN(v, w, dt=0.01, max_t=300, I_ext=0.5, b=0.7, a=0.8, tau=20)
        Calculate next v and w values for FitzHugh-Nagumo dynamics
        Inputs:
            v: current v value
            w: current w value
            dt: time step
            max_t: maximum time
            I_ext: external current
            b: model parameter
            a: model parameter
            tau: model parameter
        Returns:
            v_next: next v value
            w_next: next w value
    
    ------------------------------------------------------------------------------------------
    checkEmptyList(obj)
        Parameters
        ----------
        obj : any type
        
        Returns
        -------
        Boolean variable (whether obj is a list)

    ------------------------------------------------------------------------------------------
    check_save_name(save_name, invalid_signs='!@#$%^&*.,:;', addi_path=[], sep='\\')
        Check if the given file name is valid and returns the final file name.
        The function replaces invalid characters in the file name with underscores ('_').
        
        Parameters:
        save_name (str): The name of the file to be saved.
        invalid_signs (str, optional): A string of invalid characters. Defaults to '!@#$%^&*.,:;'.
        addi_path (list, optional): A list of additional paths to be appended to the file name. Defaults to [].
        sep (str, optional): The separator used between different elements of the path. Defaults to the system separator.
        
        Returns:
        str: The final file name with invalid characters replaced and with additional path appended if provided.

    ------------------------------------------------------------------------------------------
    claculate_percent_close(reco, real, epsilon_close=0.1, return_quantiles=False, quantiles=[0.05, 0.95])
        Calculate the ratio of close (within a specific distance) points among all dynamics' points.
        
        Parameters:
        -----------
        reco: k x T numpy array
            The reconstructed dynamics matrix.
        real: k x T numpy array
            The real dynamics matrix (ground truth).
        epsilon_close: float, optional (default: 0.1)
            The threshold for distance.
        return_quantiles: bool, optional (default: False)
            Whether to return confidence interval values.
        quantiles: list of float, optional (default: [0.05, 0.95])
            The lower and higher limits for the quantiles.
        
        Returns:
        --------
        mean_close: float
            The mean of the close enough points.
        q1: float
            The first quantile (only returned if `return_quantiles` is True).
        q2: float
            The second quantile (only returned if `return_quantiles` is True).

    ------------------------------------------------------------------------------------------
    create_FHN(dt=0.01, max_t=100, I_ext=0.5, b=0.7, a=0.8, tau=20, v0=-0.5, w0=0, params={'exp_power': 0.9, 'change_speed': False})
        Create the FitzHugh-Nagumo dynamics
        Inputs:
            dt: time step
            max_t: maximum time
            I_ext: external current
            b: model parameter
            a: model parameter
            tau: model parameter
            v0: initial condition for v
            w0: initial condition for w
            params: dictionary of additional parameters
                exp_power: power to raise time to for non-uniform time
                change_speed: Boolean to determine whether to change time speed
        Returns:
            v_full: list of v values at each time step
            w_full: list of w values at each time step

    ------------------------------------------------------------------------------------------
    create_ax(ax, nums=(1, 1), size=(10, 10), proj='d2', return_fig=False, sharey=False, sharex=False, fig=[])
        Create axes in the figure for plotting.
        
        Parameters:
        ax (list or Axes): List of Axes objects or a single Axes object
        nums (tuple): Number of rows and columns for the subplots (default (1,1))
        size (tuple): Size of the figure (default (10,10))
        proj (str): Projection type ('d2' for 2D or 'd3' for 3D) (default 'd2')
        return_fig (bool): Return the figure object in addition to the Axes object (default False)
        sharey (bool): Share y axis between subplots (default False)
        sharex (bool): Share x axis between subplots (default False)
        fig (Figure): Figure object
        
        Returns:
        Axes or tuple: The Axes object(s) for plotting
    
    create_colors(len_colors, perm=[0, 1, 2])
        Create a set of discrete colors with a one-directional order
        Input: 
            len_colors = number of different colors needed
        Output:
            3 X len_colors matrix decpiting the colors in the cols

    ------------------------------------------------------------------------------------------
    create_dynamics(type_dyn='cyl', max_time=1000, dt=0.01, change_speed=False, t_speed=<ufunc 'exp'>, axis_speed=[], t_speed_params={}, to_cent=False, return_3d=False, return_additional=False, params_ex={})
        Create ground truth dynamics
        dyn_type options:
            cyl
            f_spiral
            df_spiral
    ------------------------------------------------------------------------------------------    
    create_lorenz_mat(t=[], initial_conds=(0.0, 1.0, 1.05), txy=[])
        Create the lorenz dynamics

    ------------------------------------------------------------------------------------------
    create_orth_F(num_subdyns, num_neurons, evals=[1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0], seed_f=0, dist_type='random')
        Create orthogonal matrices.
        
        Parameters:
        num_subdyns (int): Number of sub-dynamics
        num_neurons (int): Number of neurons
        evals (list): List of eigenvalues.
        seed_f (int): Seed for the random number generator (default 0)
        dist_type (str): Distribution type ('random')
        
        Returns:
        list: List of orthogonal matrices

    ------------------------------------------------------------------------------------------
    create_rotation_mat(theta=0, axes='x', dims=3)
        Create a rotation matrix based on the given parameters.
        
        Parameters:
        theta (float, optional): Angle in radians for rotation. Default is 0.
        axes (str, optional): Axis for rotation. Must be one of 'x', 'y' or 'z'. Default is 'x'.
        dims (int, optional): Dimension of the rotation. Must be either 2 or 3. Default is 3.
        
        Returns:
        numpy.ndarray: Rotation matrix of shape (dims, dims).
        
        Raises:
        ValueError: If dims is not 2 or 3.

    ------------------------------------------------------------------------------------------
    find_closest(vec1, vec2, metric='mse')
        Find the closest elements in vec2 for each element in vec1.
        
        Parameters:
        vec1 (ndarray): 1-D numpy array
        vec2 (ndarray): 1-D numpy array
        metric (str): Metric to use for comparison, 'mse' by default
        
        Returns:
        tuple:
            - ndarray: closest elements in vec2 for each element in vec1
            - ndarray: indices of closest elements in vec2 for each element in vec1
        
        Example:
            find_closest([1, 2, 3], [0, 4, 5]) -> ([0, 4, 5], [0, 1, 2])

    ------------------------------------------------------------------------------------------
    find_dominant_row(coefficients)
        This function returns the row index of the largest absolute value of each column in the input 2D numpy array "coefficients".
        
        Inputs:
            coefficients - a 2D numpy array of shape (m, n) where m is the number of rows and n is the number of columns.
            
        Outputs:
            domi - a 1D numpy array of shape (n,) where each element is an integer representing the row index of the largest absolute value of each column.

    ------------------------------------------------------------------------------------------
    
    find_perpendicular(d1, d2, perp_length=1, prev_v=[], next_v=[], ref_point=[], choose_meth='intersection', initial_point='mid', direction_initial='low', return_unchose=False, layer_num=0)
        IT IS AN INTER FUNCTION - DO NOT USE IT BY ITSELF
        This function find the 2 point of the orthogonal vector to a vector defined by points d1,d2
        d1 =                first data point
        d2 =                second data point
        perp_length =       desired width
        prev_v =            previous value of v. Needed only if choose_meth == 'prev'
        next_v =            next value of v. Needed only if choose_meth == 'prev'
        ref_point =         reference point for the 'smooth' case, or for 2nd+ layers
        choose_meth =       'intersection' (eliminate intersections) OR 'smooth' (smoothing with previous prediction) OR 'prev' (eliminate convexity)
        direction_initial = to which direction take the first perp point  
        return_unchose =    whether to return unchosen directions
    
    ------------------------------------------------------------------------------------------    
    flip_power(x1, x2)
        This function takes two arguments, x1 and x2, and returns the result of x2 raised to the power of x1 using the numpy.power function.

    ------------------------------------------------------------------------------------------
    init_mat(size_mat, r_seed=0, dist_type='norm', init_params={'loc': 0, 'scale': 1}, normalize=False)
        This is an initialization function to initialize matrices. 
        Inputs:
          size_mat    = 2-element tuple or list, describing the shape of the mat
          r_seed      = random seed (should be integer)
          dist_type   = distribution type for initialization; can be 'norm' (normal dist), 'uni' (uniform dist),'inti', 'sparse', 'regional', 'zeros'
          init_params = a dictionary with params for initialization. The keys depends on 'dist_type'.
                        keys for norm -> ['loc','scale']
                        keys for inti and uni -> ['low','high']
                        keys for sparse -> ['k'] -> number of non-zeros in each row
                        keys for regional -> ['k'] -> repeats of the sub-dynamics allocations
          normalize   = whether to normalize the matrix
        Output:
            the random matrix with size 'size_mat'

    ------------------------------------------------------------------------------------------
    lists2list(xss)
        Flatten a list of lists into a single list.
        
        Parameters
        ----------
        xss : list of lists
            The list of lists to be flattened.
        
        Returns
        -------
        list
            The flattened list.

    ------------------------------------------------------------------------------------------
    load_mat_file(mat_name, mat_path='', sep='\\')
        Load a MATLAB `.mat` file. Useful for uploading the C. elegans data.
        
        Parameters:
        -----------
        mat_name: str
            The name of the MATLAB file.
        mat_path: str, optional (default: '')
            The path to the MATLAB file.
        sep: str, optional (default: the system separator)
            The separator to use in the file path.
        
        Returns:
        --------
        data_dict: dict
            A dictionary containing the contents of the MATLAB file.

    ------------------------------------------------------------------------------------------
    load_pickle(path)
        Load a pickled object from disk.
        
        Parameters:
        path (str): The path to the pickled object.
        
        Returns:
        dct (obj): The loaded object.

    ------------------------------------------------------------------------------------------
    load_vars(folders_names, save_name, sep='\\', ending='.pkl', full_name=False)
        Load results previously saved.
        
        Parameters:
        folders_names (str/list): List of folders to form the path or a string representation of the path
        save_name (str): Name of the saved file
        sep (str): Separator to join the folders
        ending (str): File extension of the saved file
        full_name (bool): If True, folders_names and sep are ignored
        
        Example:
            load_vars('' ,  'save_c.pkl' ,sep=sep , ending = '.pkl',full_name = False)

    ------------------------------------------------------------------------------------------
    lorenz(x, y, z, s=10, r=25, b=2.667)
        Given:
           x, y, z: a point of interest in three dimensional space
           s, r, b: parameters defining the lorenz attractor
        Returns:
           x_dot, y_dot, z_dot: values of the lorenz attractor's partial
               derivatives at the point x, y, z

    ------------------------------------------------------------------------------------------
    mean_change(signal, axis=0)
        Calculate the mean change of the signal along the specified axis.
        
        Parameters
        ----------
        signal : numpy.ndarray
            The signal data.
        axis : int, optional
            The axis along which the mean change is calculated, by default 0.
        
        Returns
        -------
        numpy.ndarray
            The mean change of the signal.

    ------------------------------------------------------------------------------------------
    min_dist(dotA1, dotA2, dotB1, dotB2, num_sects=500)
        Calculates the minimum euclidean distance between two discrete lines (e.g. where they intersect?).
        Inputs:
            dotA1: Tuple of x,y coordinate of first point on line A
            dotA2: Tuple of x,y coordinate of second point on line A
            dotB1: Tuple of x,y coordinate of first point on line B
            dotB2: Tuple of x,y coordinate of second point on line B
            num_sects: Number of sections the lines should be divided into to calculate distance
            
        Returns:
            List of minimum distances between two lines.

    ------------------------------------------------------------------------------------------
    movmfunc(func, mat, window=3, direction=0, dist='uni')
        moving window with applying the function func on the matrix 'mat' towrads the direction 'direction'
        dist: can be 'uni' (uniform) or 'gaus' (Gaussian)
        
        Calculates the moving window with the application of the given function `func` on the matrix `mat` in the direction `direction`.
        
        Parameters:
        - func (callable): The function to apply.
        - mat (numpy.ndarray): The matrix to apply the function to.
        - window (int): The size of the moving window. (default: 3)
        - direction (int): The direction to apply the moving window. 0 for row-wise and 1 for column-wise. (default: 0)
        - dist (str): The distribution to use for weighting. Can be 'uni' for uniform or 'gaus' for Gaussian. (default: 'uni')
        
        Returns:
        numpy.ndarray: The result of applying the moving window to `mat`.
        
        Example:
        >>> import numpy as np
        >>> def myfunc(arr, axis=None):
        ...     return np.sum(arr, axis=axis)
        >>> mat = np.array([[1, 2, 3, 4], [5, 6, 7, 8], [9, 10, 11, 12]])
        >>> movmfunc(myfunc, mat, window=3, direction=0, dist='uni')
        array([[ 6.,  9., 12.],
               [15., 18., 21.],
               [ 9., 12., 15.]])

    ------------------------------------------------------------------------------------------
    norm_coeffs(coefficients, type_norm, same_width=True, width_des=0.7, factor_power=0.9, min_width=0.01)
        Normalize the coefficients according to the specified type of normalization.
        
        Parameters
        ----------
        coefficients : numpy.ndarray
            The coefficients to be normalized.
        type_norm : str
            The type of normalization to be applied. Can be 'sum_abs', 'norm', 'abs' or 'no_norm'.
        same_width : bool, optional
            Whether to enforce the same width for all coefficients, by default True.
        width_des : float, optional
            The desired width, by default 0.7.
        factor_power : float, optional
            The power factor to apply, by default 0.9.
        min_width : float, optional
            The minimum width allowed, by default 0.01.
        
        Returns
        -------
        numpy.ndarray
            The normalized coefficients.
        
        Raises
        ------
        NameError
            If the `type_norm` value is not one of the allowed values ('sum_abs', 'norm', 'abs' or 'no_norm').

    ------------------------------------------------------------------------------------------
    norm_mat(mat, type_norm='evals', to_norm=True)
        This function comes to norm matrices by the highest eigen-value
        Inputs:
            mat       = the matrix to norm
            type_norm = what type of normalization to apply. Can be 'evals' (divide by max eval), 'max' (divide by max value), 'exp' (matrix exponential)
            to_norm   = whether to norm or not to.
        Output:  
            the normalized matrix

    ------------------------------------------------------------------------------------------
    norm_over_time(coefficients, type_norm='normal')
        Normalize coefficients over time
        Inputs:
            coefficients: array of coefficients
            type_norm: type of normalization
                'normal': standard normalization
        Returns:
            coefficients_norm: normalized coefficients

    ------------------------------------------------------------------------------------------
    nullify_part(f, axis='both', percent0=80)
        Nullify a part of a matrix.
        
        Parameters:
        f (numpy array): The input matrix
        axis (str or int): The axis along which to perform the operation ('0', '1', or 'both') (default 'both')
        percent0 (int): The percentile value used to determine which values to nullify (default 80)
        
        Returns:
        numpy array: The input matrix with the specified values set to 0

    ------------------------------------------------------------------------------------------
    plot_3d_color_scatter(latent_dyn, coefficients, ax=[], figsize=(15, 10), delta=0.4, colors=[])
        Plot a 3D color scatter plot.
        
        Parameters
        ----------
        latent_dyn : numpy.ndarray
            A 3xN numpy array representing the latent dynamics.
        coefficients : numpy.ndarray
            A KxN numpy array representing the coefficients.
        ax : matplotlib.axes._subplots.AxesSubplot, optional
            A 3D axis to plot on, by default []
        figsize : tuple, optional
            The size of the figure, by default (15, 10)
        delta : float, optional
            The delta between each row, by default 0.4
        colors : list of str, optional
            The colors for each row, by default []
        
        Returns
        -------
        None

    ------------------------------------------------------------------------------------------
    plot_multi_colors(store_dict, min_time_plot=0, max_time_plot=-100, colors=['green', 'red', 'blue'], ax=[], fig=[], alpha=0.99, smooth_window=3, factor_power=0.9, coefficients_n=[], to_scatter=False, to_scatter_only_one=False, choose_meth='intersection', title='')
        store_dict is a dictionary with the high estimation results. 
        example:        
            store_dict , coefficients_n = calculate_high_for_all(coefficients,choose_meth = 'intersection',width_des = width_des, latent_dyn = latent_dyn, direction_initial = direction_initial,factor_power = factor_power, return_unchose=True)

    ------------------------------------------------------------------------------------------
    quiver_plot(sub_dyn=[], xmin=-5, xmax=5, ymin=-5, ymax=5, ax=[], chosen_color='red', alpha=0.4, w=0.02, type_plot='quiver', zmin=-5, zmax=5, cons_color=False, return_artist=False, xlabel='x', ylabel='y', quiver_3d=False, inter=2, projection=[0, 1])
        Plots a quiver or stream plot on the specified axis.
        
        Parameters
        ----------
        sub_dyn: numpy.ndarray, default: []
            The matrix whose eigenvectors need to be plotted. If an empty list is provided, the default sub_dyn will be set to [[0,-1],[1,0]]
        xmin: float, default: -5
            The minimum value for x-axis.
        xmax: float, default: 5
            The maximum value for x-axis.
        ymin: float, default: -5
            The minimum value for y-axis.
        ymax: float, default: 5
            The maximum value for y-axis.
        ax: matplotlib.axes._subplots.AxesSubplot or list, default: []
            The axis on which the quiver or stream plot will be plotted. If a list is provided, a new figure will be created.
        chosen_color: str or list, default: 'red'
            The color of the quiver or stream plot. 
        alpha: float, default: 0.4
            The alpha/transparency value of the quiver or stream plot.
        w: float, default: 0.02
            The width of the arrows in quiver plot.
        type_plot: str, default: 'quiver'
            The type of plot. Can either be 'quiver' or 'streamplot'.
        zmin: float, default: -5
            The minimum value for z-axis (for 3D plots).
        zmax: float, default: 5
            The maximum value for z-axis (for 3D plots).
        cons_color: bool, default: False
            If True, a constant color will be used for the stream plot. If False, the color will be proportional to the magnitude of the matrix.
        return_artist: bool, default: False
            If True, the artist instance is returned.
        xlabel: str, default: 'x'
            Label for x-axis.
        ylabel: str, default: 'y'
            Label for y-axis.
        quiver_3d: bool, default: False
            If True, a 3D quiver plot will be generated.
        inter: float, default: 2
            The step size for the grids in 3D plots.
        projection: list, default: [0,1]
            The indices of the columns in sub_dyn that will be used for plotting.
            
        Returns
        -------
        h: matplotlib.quiver.Quiver or matplotlib.streamplot.Streamplot
            The artist instance, if return_artist is True.
    
    ------------------------------------------------------------------------------------------    
    red_mean(mat, axis=1)
        Subtract the mean of each row or column in a matrix.
        
        Parameters:
        mat (np.ndarray): The input matrix.
        axis (int, optional): The axis along which the mean should be computed. Default is 1 (mean of each row).
        
        Returns:
        np.ndarray: The matrix with each row or column mean subtracted.

    ------------------------------------------------------------------------------------------
    relative_eror(reco, real, return_mean=True, func=<function nanmean at 0x000001AADA09DA20>)
        Calculate the relative reconstruction error
        Inputs:
            reco: k X T reconstructed dynamics matrix
            real: k X T real dynamics matrix (ground truth)
            return_mean: reaturn the average of the reconstruction error over time
            func: the function to apply on the relative error of each point
        Output:
            the relative error (or the mean relative error over time if return_mean)

    ------------------------------------------------------------------------------------------
    remove_background(ax, grid=False, axis_off=True)
        Remove the background of a figure.
        
        Parameters:
        ax (subplot): The subplot to be edited.
        grid (bool, optional): Whether to display grid lines. Defaults to False.
        axis_off (bool, optional): Whether to display axis lines. Defaults to True.

    ------------------------------------------------------------------------------------------
    remove_edges(ax, include_ticks=False, top=False, right=False, bottom=False, left=False)
        Remove the specified edges (spines) of the plot and optionally the ticks of the plot.
        
        Parameters
        ----------
        ax : matplotlib.axes.Axes
            The matplotlib axes object of the plot.
        include_ticks : bool, optional
            Whether to include the ticks, by default False.
        top : bool, optional
            Whether to remove the top edge, by default False.
        right : bool, optional
            Whether to remove the right edge, by default False.
        bottom : bool, optional
            Whether to remove the bottom edge, by default False.
        left : bool, optional
            Whether to remove the left edge, by default False.
        
        Returns
        -------
        None

    ------------------------------------------------------------------------------------------
    rgb_to_hex(rgb_vec)
        Convert a RGB vector to a hexadecimal color code.
        
        Parameters:
        rgb_vec (list): A 3-element list of floats representing the red, green, and blue components of the color. The values should be between 0 and 1.
        
        Returns:
        str: The hexadecimal color code as a string.
        
        Example:
        >>> rgb_to_hex([0.5, 0.2, 0.8])
        '#8033CC'
    ------------------------------------------------------------------------------------------    
    saveLoad(opt, filename)
        Save or load a global variable 'calc'
        
        Parameters
        ----------
        opt : str
            the option, either "save" or "load"
        filename : str
            the name of the file to save or load from
            
        Returns
        -------
        None

    ------------------------------------------------------------------------------------------
    save_file_dynamics(save_name, folders_names, to_save=[], invalid_signs='!@#$%^&*.,:;', sep='\\', type_save='.npy')
        Save dynamics & model results to disk.
        
        Parameters:
        save_name (str): The name of the file to save.
        folders_names (List[str]): List of folder names where the file should be saved.
        to_save (List, optional): List of values to save. Defaults to [].
        invalid_signs (str, optional): String of invalid characters to be removed from the save name. Defaults to '!@#$%^&*.,:;'.
        sep (str, optional): Separator to use when joining `folders_names`. Defaults to `os.sep`.
        type_save (str, optional): The file format to save the data in. Valid options are '.npy' and '.pkl'. Defaults to '.npy'.
        
        Returns:
        None

    ------------------------------------------------------------------------------------------
    sigmoid(x, std=1)
        This function computes the sigmoid function of a given input x, with a standard deviation "std". 
        Parameters
        ----------
        x : np.array / list
        std :  The default is 1.
        
        Returns
        -------
        np.array
            The sigmoid function maps any input value to the range of 0 and 1, making it useful for binary classification problems and as an activation function in neural networks.

    ------------------------------------------------------------------------------------------
    spec_corr(v1, v2, to_abs=True)
        Compute the absolute value of the correlation between two arrays.
        
        Parameters:
        - v1 (numpy.ndarray): The first array to compute the correlation between.
        - v2 (numpy.ndarray): The second array to compute the correlation between.
        - to_abs (bool): Whether to compute the absolute value of the correlation (default: True).
        
        Returns:
        - float: The absolute value of the correlation between `v1` and `v2`.

    ------------------------------------------------------------------------------------------
    str2bool(str_to_change)
        Transform a string representation of a boolean value to a boolean variable.
        
        Parameters:
        str_to_change (str): String representation of a boolean value
        
        Returns:
        bool: Boolean representation of the input string
        
        Example:
            str2bool('true') -> True

    ------------------------------------------------------------------------------------------
    visualize_dyn(dyn, ax=[], params_plot={}, turn_off_back=False, marker_size=10, include_line=False, color_sig=[], cmap='cool', return_fig=False, color_by_dominant=False, coefficients=[], figsize=(5, 5), colorbar=False, colors=[], vmin=None, vmax=None, color_mix=False, alpha=0.4, colors_dyns=array(['r', 'g', 'b', 'yellow'], dtype='<U6'), add_text='t ', text_points=[], fontsize_times=18, marker='o', delta_text=0.5, color_for_0=None, legend=[], fig=[], return_mappable=False, remove_back=True, edgecolors='none')
        Plot the multi-dimensional dynamics
        Inputs:
            dyn          = dynamics to plot. Should be a np.array with size k X T
            ax           = the subplot to plot in (optional)
            params_plot  = additional parameters for the plotting (optional). Can include plotting-related keys like xlabel, ylabel, title, etc.
            turn_off_back= disable backgroud of the plot? (optional). Boolean
            marker_size  = marker size of the plot (optional). Integer
            include_line = add a curve to the plot (in addition to the scatter plot). Boolean
            color_sig    = the color signal. if empty and color_by_dominant - color by the dominant dynamics. If empty and not color_by_dominant - color by time.
            cmap         = cmap
            colors       = if not empty -> pre-defined colors for the different sub-dynamics. Otherwise - colors are according to the cmap.
            color_mix    = relevant only if  color_by_dominant. In this case the colors need to be in the form of [r,g,b]
        Output:
            (only if return_fig) -> returns the figure


