nltools 0.6.0.dev0__py3-none-any.whl

nltools/algorithms/inference/timeseries.py

@@ -0,0 +1,347 @@
+"""Permutation tests for autocorrelated time series.
+
+Shuffling the samples of a time series destroys its autocorrelation and inflates
+false positives. These surrogate-data methods build the null while preserving
+temporal structure:
+
+- `circle_shift`: rotate the series (preserves autocorrelation exactly)
+- `phase_randomize`: randomize Fourier phases (preserves the power spectrum)
+- `_timeseries_correlation_permutation_test`: correlation test using either method
+
+Permutations run on joblib workers; `n_jobs` sets how many, and a given
+`random_state` gives the same result at any worker count.
+
+References:
+    Theiler, J., Galdrikian, B., Longtin, A., Eubank, S., & Farmer, J. D. (1991).
+    Testing for nonlinearity in time series: the method of surrogate data
+    (No. LA-UR-91-3343; CONF-9108181-1). Los Alamos National Lab., NM (United States).
+
+    Lancaster, G., Iatsenko, D., Pidde, A., Ticcinelli, V., & Stefanovska, A. (2018).
+    Surrogate data for hypothesis testing of physical systems. Physics Reports, 748, 1-60.
+"""
+
+import numpy as np
+from typing import Literal
+from sklearn.utils import check_random_state
+
+from .utils import _maybe_tqdm
+from ..validation import _compute_pvalue, _validate_tail_parameter
+from .correlation import _select_corr_func
+
+
+def circle_shift(
+    data: np.ndarray,
+    shift_amount: int | np.ndarray | None = None,
+    random_state: int | np.random.RandomState | None = None,
+) -> np.ndarray:
+    """Circular shift for time-series data.
+
+    Performs a circular shift that preserves autocorrelation structure.
+    Useful for permutation tests on autocorrelated time series (e.g., fMRI).
+    For 1D data, shifts by a single amount. For 2D data, shifts each
+    feature (column) independently.
+
+    Args:
+        data (np.ndarray): Time series, shape (n_samples,) or (n_samples, n_features).
+        shift_amount (int | np.ndarray | None): Shift amount: an int for 1D data,
+            or an array of length n_features (one shift per column) for 2D data.
+            None draws random shift(s). Defaults to None.
+        random_state (int | np.random.RandomState | None): Random seed used when
+            `shift_amount` is None.
+
+    Returns:
+        np.ndarray: Circularly shifted data with the same shape as the input.
+
+    Examples:
+        ```python
+        x = np.array([1, 2, 3, 4, 5])
+        circle_shift(x, shift_amount=2)  # → array([4, 5, 1, 2, 3])
+
+        X = np.array([[1, 10], [2, 20], [3, 30], [4, 40]])
+        circle_shift(X, shift_amount=np.array([1, 2]))
+        # → array([[ 4, 30],
+        #          [ 1, 40],
+        #          [ 2, 10],
+        #          [ 3, 20]])
+        ```
+    """
+    data = np.asarray(data)
+    rng = check_random_state(random_state)
+
+    # 1D case
+    if data.ndim == 1:
+        if shift_amount is None:
+            shift_amount = rng.randint(1, len(data))
+        shift_amount = int(shift_amount)
+        return np.concatenate([data[-shift_amount:], data[:-shift_amount]])
+
+    # 2D case
+    if data.ndim == 2:
+        n_samples, n_features = data.shape
+        if shift_amount is None:
+            # Each feature gets an independent random shift (with replacement)
+            # This allows n_features > n_samples (e.g., more voxels than timepoints)
+            shift_amount = rng.randint(1, n_samples, size=n_features)
+        shift_amount = np.asarray(shift_amount, dtype=int)
+
+        if shift_amount.shape != (n_features,):
+            raise ValueError(
+                f"shift_amount must have length n_features={n_features}, "
+                f"got shape {shift_amount.shape}"
+            )
+
+        # Shift each feature independently
+        shifted = np.empty_like(data)
+        for i, shift in enumerate(shift_amount):
+            shifted[:, i] = np.concatenate([data[-shift:, i], data[:-shift, i]])
+        return shifted
+
+    raise ValueError(f"data must be 1D or 2D, got shape {data.shape}")
+
+
+def phase_randomize(
+    data: np.ndarray,
+    *,
+    random_state: int | np.random.RandomState | None = None,
+) -> np.ndarray:
+    """FFT-based phase randomization for time-series data.
+
+    Preserves the power spectrum (and therefore the autocorrelation) exactly, up
+    to numerical precision, while destroying nonlinear temporal structure. Used to
+    test whether data was generated by a linear Gaussian process or contains
+    nonlinear dynamics.
+
+    The signal is transformed with an FFT, each positive frequency is multiplied
+    by `exp(iφ)` with φ drawn uniformly from [0, 2π], the matching negative
+    frequency by the conjugate `exp(-iφ)` so the inverse FFT is real, and the
+    result is transformed back.
+
+    Args:
+        data (np.ndarray): Time series, shape (n_samples,) or (n_samples, n_features).
+        random_state (int | np.random.RandomState | None): Random seed for
+            reproducibility.
+
+    Returns:
+        np.ndarray: Phase-randomized data with the same shape as the input.
+
+    Examples:
+        ```python
+        x = np.sin(np.linspace(0, 10 * np.pi, 100))
+        x_rand = phase_randomize(x, random_state=42)
+        # Power spectrum is preserved
+        np.allclose(np.abs(np.fft.rfft(x)) ** 2, np.abs(np.fft.rfft(x_rand)) ** 2)  # → True
+        ```
+    """
+    data = np.asarray(data)
+    rng = check_random_state(random_state)
+
+    # Compute FFT
+    fft_data = np.fft.fft(data, axis=0)
+    n_samples = data.shape[0]
+
+    # Determine positive and negative frequency indices
+    if n_samples % 2 == 0:
+        pos_freq = np.arange(1, n_samples // 2)
+        neg_freq = np.arange(n_samples - 1, n_samples // 2, -1)
+    else:
+        pos_freq = np.arange(1, (n_samples - 1) // 2 + 1)
+        neg_freq = np.arange(n_samples - 1, (n_samples - 1) // 2, -1)
+
+    # Generate random phases and apply to FFT
+    if data.ndim == 1:
+        phase_shifts = rng.uniform(0, 2 * np.pi, size=len(pos_freq))
+        fft_data[pos_freq] *= np.exp(1j * phase_shifts)
+        fft_data[neg_freq] *= np.exp(-1j * phase_shifts)
+    else:
+        n_features = data.shape[1]
+        phase_shifts = rng.uniform(0, 2 * np.pi, size=(len(pos_freq), n_features))
+        fft_data[pos_freq, :] *= np.exp(1j * phase_shifts)
+        fft_data[neg_freq, :] *= np.exp(-1j * phase_shifts)
+
+    # Inverse FFT and return real part
+    return np.real(np.fft.ifft(fft_data, axis=0))
+
+
+def _timeseries_correlation_cpu_parallel(
+    data1: np.ndarray,
+    data2: np.ndarray,
+    *,
+    n_permute: int,
+    method: str,
+    metric: str,
+    tail: int | str,
+    return_null: bool,
+    n_jobs: int,
+    random_state: int | np.random.RandomState | None,
+    progress_bar: bool = False,
+) -> dict:
+    """Surrogate-data correlation test parallelized across CPU cores with joblib.
+
+    Pre-generates one seed per permutation, so the surrogate a permutation sees
+    depends only on its index and never on which worker ran it. Only `data1` is
+    randomized: randomizing both series reduces power and tests a different
+    hypothesis than H0: correlation = 0.
+
+    Args:
+        data1 (np.ndarray): First time series, shape `(n_samples,)`; the series
+            the surrogates are built from.
+        data2 (np.ndarray): Second time series, shape `(n_samples,)`; held fixed.
+        n_permute (int): Number of permutations.
+        method (str): `'circle_shift'` or `'phase_randomize'`.
+        metric (str): `'pearson'`, `'spearman'`, or `'kendall'`.
+        tail (int | str): `2` or `'two'` for two-tailed; `1` or `'one'` for
+            one-tailed.
+        return_null (bool): Whether to return the null distribution.
+        n_jobs (int): Number of joblib workers (-1 = all cores).
+        random_state (int | np.random.RandomState | None): Random seed for
+            reproducibility.
+        progress_bar (bool): Whether to display a tqdm progress bar.
+
+    Returns:
+        dict: Same format as `_timeseries_correlation_permutation_test`.
+    """
+    from joblib import Parallel, delayed
+
+    corr_func = _select_corr_func(metric)
+
+    obs_corr = corr_func(data1, data2)
+    if isinstance(obs_corr, np.ndarray):
+        obs_corr = obs_corr[0]
+    obs_corr = np.asarray(obs_corr)
+
+    rng = check_random_state(random_state)
+    MAX_INT = 2**31 - 1
+    seeds = rng.randint(MAX_INT, size=n_permute)
+
+    surrogate = circle_shift if method == "circle_shift" else phase_randomize
+
+    def _compute_one_perm(seed):
+        """Correlate one surrogate of `data1` against the fixed `data2`."""
+        corr = corr_func(surrogate(data1, random_state=seed), data2)
+        return corr[0] if isinstance(corr, np.ndarray) else corr
+
+    null_dist = Parallel(n_jobs=n_jobs)(
+        delayed(_compute_one_perm)(seeds[i])
+        for i in _maybe_tqdm(
+            range(n_permute),
+            progress_bar=progress_bar,
+            desc=f"{method} perms",
+            unit="perm",
+        )
+    )
+    null_dist = np.array(null_dist)
+
+    p_value = _compute_pvalue(obs_corr, null_dist, tail=tail)
+
+    results = {
+        "correlation": float(obs_corr),
+        "p": p_value.item() if hasattr(p_value, "item") else float(p_value),
+    }
+
+    if return_null:
+        results["null_dist"] = null_dist
+
+    return results
+
+
+def _timeseries_correlation_permutation_test(
+    data1: np.ndarray,
+    data2: np.ndarray,
+    *,
+    method: Literal["circle_shift", "phase_randomize"] = "circle_shift",
+    n_permute: int = 5000,
+    metric: Literal["pearson", "spearman", "kendall"] = "pearson",
+    tail: int | str = 2,
+    n_jobs: int = -1,
+    return_null: bool = False,
+    random_state: int | np.random.RandomState | None = None,
+    progress_bar: bool = False,
+) -> dict:
+    """Permutation test for the correlation between two autocorrelated time series.
+
+    Standard permutation tests shuffle samples independently, which destroys
+    autocorrelation and inflates Type I error on time series. This test instead
+    builds the null from surrogates of `data1` that preserve temporal structure
+    — circular shifts (`'circle_shift'`) or Fourier phase randomization
+    (`'phase_randomize'`) — while `data2` stays fixed. For independent
+    observations use `correlation_permutation_test`.
+
+    Args:
+        data1 (np.ndarray): First time series, shape (n_samples,) or (n_samples, 1).
+        data2 (np.ndarray): Second time series, shape (n_samples,) or (n_samples, 1).
+        method (str): `'circle_shift'` rotates the series (preserves
+            autocorrelation; fast, and suitable for most fMRI time series);
+            `'phase_randomize'` randomizes Fourier phases (preserves the power
+            spectrum exactly; tests for nonlinear structure). Defaults to
+            'circle_shift'.
+        n_permute (int): Number of permutations. Defaults to 5000.
+        metric (str): Correlation type, one of 'pearson', 'spearman', or
+            'kendall'. Defaults to 'pearson'.
+        tail (int | str): `2` or `'two'` for a two-tailed test; `1` or `'one'` for
+            a one-tailed test in the positive direction (negate one series for the
+            other direction). Defaults to 2.
+        n_jobs (int): Number of joblib workers, -1 = all cores. Defaults to -1.
+            Results are identical at every worker count.
+        return_null (bool): Also return the null distribution. Defaults to False.
+        random_state (int | np.random.RandomState | None): Random seed for
+            reproducibility.
+        progress_bar (bool): Show a progress bar over permutations. Defaults to
+            False.
+
+    Returns:
+        dict: Keys 'correlation' (float, observed correlation), 'p' (float), and
+            'null_dist' (np.ndarray of shape (n_permute,)) when
+            `return_null=True`.
+
+    Examples:
+        ```python
+        import numpy as np
+        from nltools.algorithms import _timeseries_correlation_permutation_test
+
+        rng = np.random.default_rng(0)
+        x = np.sin(np.linspace(0, 10 * np.pi, 100))  # strongly autocorrelated
+        y = x + rng.standard_normal(100) * 0.5
+        result = _timeseries_correlation_permutation_test(
+            x, y, method="circle_shift", n_permute=1000, random_state=42
+        )
+        result["correlation"]  # → 0.853
+        result["p"]  # → 0.078 — the autocorrelation-aware null is far wider
+        #   than a sample-shuffling null would be
+        ```
+    """
+    # Validate tail up front (like one_sample/two_sample/matrix) so an invalid
+    # value fails immediately rather than after every permutation has run.
+    _validate_tail_parameter(tail)
+
+    # Validate inputs
+    data1 = np.asarray(data1).squeeze()
+    data2 = np.asarray(data2).squeeze()
+
+    if data1.ndim != 1 or data2.ndim != 1:
+        raise ValueError("data1 and data2 must be 1D arrays")
+
+    if len(data1) != len(data2):
+        raise ValueError("data1 and data2 must have the same length")
+
+    if method not in ["circle_shift", "phase_randomize"]:
+        raise ValueError(
+            f"method must be 'circle_shift' or 'phase_randomize', got '{method}'"
+        )
+
+    if metric not in ["pearson", "spearman", "kendall"]:
+        raise ValueError(
+            f"metric must be 'pearson', 'spearman', or 'kendall', got '{metric}'"
+        )
+
+    return _timeseries_correlation_cpu_parallel(
+        data1,
+        data2,
+        n_permute=n_permute,
+        method=method,
+        metric=metric,
+        tail=tail,
+        return_null=return_null,
+        n_jobs=n_jobs,
+        random_state=random_state,
+        progress_bar=progress_bar,
+    )

nltools/algorithms/inference/two_sample.py

@@ -0,0 +1,212 @@
+"""Two-sample permutation test (group-label shuffling).
+
+Tests whether two independent groups differ in mean by randomly reassigning
+observations to groups — the permutation analogue of an independent-samples
+t-test. Permutations run on joblib workers; `n_jobs` sets how many, and a
+given `random_state` gives the same result at any worker count.
+"""
+
+import numpy as np
+
+from .utils import _maybe_tqdm
+from .validation import _validate_array_shape_range
+from ..validation import _compute_pvalue, _validate_tail_parameter
+from .random import _generate_seeds
+
+
+def _two_sample_permutation_cpu_parallel(
+    data1: np.ndarray,
+    data2: np.ndarray,
+    *,
+    n_permute: int,
+    tail: int,
+    return_null: bool,
+    n_jobs: int,
+    random_state: int | None,
+    single_feature: bool = False,
+    progress_bar: bool = False,
+) -> dict:
+    """Two-sample permutation test parallelized across CPU cores with joblib.
+
+    Each worker shuffles the group labels for one permutation (from its own
+    pre-drawn seed) and computes the mean difference, so results are
+    reproducible regardless of worker count.
+
+    Args:
+        data1 (np.ndarray): Group 1 data, shape `(n_samples1, n_features)`.
+        data2 (np.ndarray): Group 2 data, shape `(n_samples2, n_features)`.
+        n_permute (int): Number of permutations.
+        tail (int | str): `2` or `'two'` for two-tailed; `1` or `'one'` for
+            one-tailed.
+        return_null (bool): Whether to return the null distribution.
+        n_jobs (int): Number of parallel jobs (-1 = all cores).
+        random_state (int | None): Random seed for reproducibility.
+        single_feature (bool): Whether the caller passed 1D data (results are
+            returned as scalars).
+        progress_bar (bool): Whether to display a tqdm progress bar.
+
+    Returns:
+        dict: Same format as `two_sample_permutation_test`.
+    """
+    from joblib import Parallel, delayed
+
+    # Setup random state and generate seeds for workers
+    seeds = _generate_seeds(n_permute, random_state=random_state)
+
+    # Get dimensions (data already reshaped by caller)
+    n1, n_features = data1.shape
+    n2 = data2.shape[0]
+    n_total = n1 + n2
+
+    # Compute observed mean difference
+    obs_diff = np.nanmean(data1, axis=0) - np.nanmean(data2, axis=0)
+
+    # Concatenate data for permutation
+    combined = np.vstack([data1, data2])  # (n_total, n_features)
+
+    # Define worker function (each processes ONE permutation)
+    def _compute_one_perm(seed):
+        """Compute mean difference for one group permutation."""
+        perm_rng = np.random.RandomState(seed)
+        # Randomly shuffle indices
+        indices = perm_rng.permutation(n_total)
+        # Split into two groups
+        group1_indices = indices[:n1]
+        group2_indices = indices[n1:]
+        # Compute mean difference
+        mean1 = np.nanmean(combined[group1_indices], axis=0)
+        mean2 = np.nanmean(combined[group2_indices], axis=0)
+        return mean1 - mean2
+
+    # Execute in parallel with progress bar
+    null_dist = Parallel(n_jobs=n_jobs)(
+        delayed(_compute_one_perm)(seeds[i])
+        for i in _maybe_tqdm(
+            range(n_permute),
+            progress_bar=progress_bar,
+            desc="CPU parallel perms",
+            unit="perm",
+        )
+    )
+    null_dist = np.array(null_dist)  # Shape: (n_permute, n_features)
+
+    # Compute p-values
+    p_values = _compute_pvalue(obs_diff, null_dist, tail=tail)
+
+    # Return to original shape
+    if single_feature:
+        obs_diff = obs_diff.item() if hasattr(obs_diff, "item") else float(obs_diff[0])
+        p_values = p_values.item() if hasattr(p_values, "item") else float(p_values[0])
+
+    # Build result
+    result = {
+        "mean_diff": obs_diff,
+        "p": p_values,
+    }
+
+    if return_null:
+        if single_feature:
+            null_dist = null_dist.squeeze()
+        result["null_dist"] = null_dist
+
+    return result
+
+
+def two_sample_permutation_test(
+    data1: np.ndarray,
+    data2: np.ndarray,
+    *,
+    n_permute: int = 5000,
+    tail: int | str = 2,
+    return_null: bool = False,
+    n_jobs: int = -1,
+    random_state: int | None = None,
+    progress_bar: bool = False,
+) -> dict:
+    """Two-sample permutation test using group-label shuffling.
+
+    Tests whether two independent groups have different means by randomly
+    reassigning observations to groups — the permutation analogue of an
+    independent-samples t-test. Group sizes may differ. Multi-feature
+    (voxel-wise) data tests each column independently against the same
+    permutations.
+
+    Assumes exchangeability under the null (group assignment is arbitrary):
+    independent samples from similarly shaped distributions. NaN observations
+    are dropped from the observed and every permuted mean (`np.nanmean`),
+    feature by feature.
+
+    Args:
+        data1 (np.ndarray): Group 1 data, shape `(n_samples1,)` for a single
+            feature or `(n_samples1, n_features)` for voxel-wise data. May
+            contain NaN observations.
+        data2 (np.ndarray): Group 2 data, shape `(n_samples2,)` or
+            `(n_samples2, n_features)`; must have the same number of features
+            as `data1`. May contain NaN observations.
+        n_permute (int): Number of permutations. Defaults to 5000.
+        tail (int | str): `2` or `'two'` (default) for a two-tailed test
+            (mean1 != mean2); `1` or `'one'` for a one-tailed test of
+            mean1 > mean2 (swap the groups for the other direction — the fixed
+            direction keeps multiple-comparison correction valid).
+        return_null (bool): If True, include the full null distribution in the
+            result. Defaults to False.
+        n_jobs (int): Number of joblib workers. Defaults to -1 (all cores).
+            Results are identical at every worker count.
+        random_state (int | None): Random seed for reproducibility.
+        progress_bar (bool): Whether to display a progress bar. Defaults to False.
+
+    Returns:
+        dict: Keys `'mean_diff'` (float or np.ndarray, observed
+            `mean(data1) - mean(data2)`), `'p'` (float or np.ndarray,
+            p-value(s)), and — when `return_null=True` — `'null_dist'`
+            (np.ndarray, shape `(n_permute,)` or `(n_permute, n_features)`).
+
+    Examples:
+        ```python
+        # Single feature
+        data1 = np.random.randn(20)  # Group 1: 20 subjects
+        data2 = np.random.randn(25)  # Group 2: 25 subjects
+        result = two_sample_permutation_test(data1, data2, n_permute=5000)
+        result["p"]  # → 0.45
+
+        # Voxel-wise test
+        data1 = np.random.randn(20, 10000)  # 20 subjects, 10K voxels
+        data2 = np.random.randn(25, 10000)  # 25 subjects, 10K voxels
+        result = two_sample_permutation_test(data1, data2, n_permute=5000)
+        result["mean_diff"].shape  # → (10000,)
+        result["p"].shape  # → (10000,)
+        ```
+    """
+    # Input validation
+    data1 = np.asarray(data1, dtype=np.float64)
+    data2 = np.asarray(data2, dtype=np.float64)
+
+    _validate_array_shape_range(data1, 1, 2, name="data1")
+    _validate_array_shape_range(data2, 1, 2, name="data2")
+    _validate_tail_parameter(tail)
+
+    # Handle shape
+    single_feature = data1.ndim == 1 and data2.ndim == 1
+    if data1.ndim == 1:
+        data1 = data1[:, np.newaxis]
+    if data2.ndim == 1:
+        data2 = data2[:, np.newaxis]
+
+    # Check feature dimensions match
+    if data1.shape[1] != data2.shape[1]:
+        raise ValueError(
+            f"data1 and data2 must have same number of features, "
+            f"got {data1.shape[1]} and {data2.shape[1]}"
+        )
+
+    return _two_sample_permutation_cpu_parallel(
+        data1,
+        data2,
+        n_permute=n_permute,
+        tail=tail,
+        return_null=return_null,
+        n_jobs=n_jobs,
+        random_state=random_state,
+        single_feature=single_feature,
+        progress_bar=progress_bar,
+    )

nltools/algorithms/inference/utils.py

@@ -0,0 +1,58 @@
+"""Shared helpers for the permutation tests: sign flips, z-from-p, the stability epsilon and progress bars."""
+
+import numpy as np
+from ...utils import _NullProgressBar, _make_progress_bar, _maybe_tqdm  # noqa: F401
+from .random import _generate_sign_flips as _generate_sign_flips  # noqa: F401
+
+
+# ============================================================================
+# Numerical Stability Constants
+# ============================================================================
+
+# Small constant added to denominators to prevent division by zero
+# Value: 1e-10 is standard in scientific computing for float64 precision
+# - Well above machine epsilon (2.22e-16 for float64)
+# - Small enough not to affect correlation values
+# - Matches established practice in neuroimaging libraries
+EPSILON = 1e-10
+
+
+def _signed_z_from_p(t_like_arr, p_arr, tail_internal: str = "two") -> np.ndarray:
+    """Compute a signed z-score map from a p-value map.
+
+    The z-from-p conversion used by `BrainData.ttest` and `Adjacency.ttest`.
+    The clipping policy below must live in exactly one place.
+
+    Two-tailed p: ``|z| = norm.isf(p/2)`` so that p=0.05 → |z|≈1.96, matching
+    nilearn's ``output_type='z_score'`` convention, with the sign copied from
+    the accompanying statistic. One-tailed (upper) p: ``z = norm.isf(p)`` —
+    a one-sided p already encodes direction, so no sign copy is needed.
+
+    p is clipped to the open interval (0, 1) so z stays finite in BOTH
+    directions: the lower bound is the smallest positive normal float64
+    (z ≈ +37.7), the upper bound the largest float64 below 1 (z ≈ -8.3).
+    The bounds look asymmetric because float64 resolves p near 0 far more
+    finely than near 1; both sit beyond any meaningful statistical
+    resolution. Without the upper clip, ``p == 1.0`` — reachable on the
+    one-tailed path, e.g. ``t.sf(-45, 29) == 1.0`` — maps to ``-inf`` and
+    poisons downstream percentiles and plotting.
+
+    Args:
+        t_like_arr (np.ndarray): Statistic supplying the sign (t map or similar).
+        p_arr (np.ndarray): P-value map (two-tailed, or one-tailed upper).
+        tail_internal (str): `'two'` (default) or `'upper'`.
+
+    Returns:
+        np.ndarray: Signed z map, finite everywhere.
+    """
+    from scipy.stats import norm
+
+    p_clipped = np.clip(
+        np.asarray(p_arr, dtype=np.float64),
+        np.finfo(np.float64).tiny,
+        np.nextafter(1.0, 0.0),
+    )
+    if tail_internal == "upper":
+        return norm.isf(p_clipped)
+    z_abs = norm.isf(p_clipped / 2.0)
+    return np.sign(np.asarray(t_like_arr)) * z_abs