jimg_ncd.utils

   1import copy
   2import io
   3import math
   4import os
   5import pickle
   6import re
   7import sys
   8import tarfile
   9import tkinter as tk
  10from itertools import combinations
  11
  12import cv2
  13import gdown
  14import matplotlib.pyplot as plt
  15import numpy as np
  16import pandas as pd
  17import plotly.express as px
  18import tifffile as tiff
  19from joblib import Parallel, delayed
  20from scipy import stats
  21from scipy.spatial import ConvexHull, cKDTree
  22from scipy.stats import chi2_contingency
  23from tqdm import tqdm
  24
  25sys.stdout = io.StringIO()
  26
  27
  28def umap_html(umap_result, width=1000, height=1200):
  29    """
  30    Create an interactive HTML UMAP scatter plot.
  31
  32    Parameters
  33    ----------
  34    umap_result : pandas.DataFrame or dict-like
  35        UMAP embedding containing at least:
  36        - `0` : array-like, UMAP dimension 1
  37        - `1` : array-like, UMAP dimension 2
  38        - `'clusters'` : array-like, assigned cluster labels
  39
  40    width : int, optional
  41        Width of the output figure in pixels. Default is 1000.
  42
  43    height : int, optional
  44        Height of the output figure in pixels. Default is 1200.
  45
  46    Returns
  47    -------
  48    plotly.graph_objs._figure.Figure
  49        Interactive Plotly scatter plot object visualizing UMAP with colored clusters.
  50    """
  51
  52    fig = px.scatter(
  53        x=umap_result[0],
  54        y=umap_result[1],
  55        color=umap_result["clusters"],
  56        labels={"color": "Cells"},
  57        template="simple_white",
  58        width=width,
  59        height=height,
  60        render_mode="svg",
  61        color_discrete_sequence=px.colors.qualitative.Dark24
  62        + px.colors.qualitative.Light24,
  63    )
  64
  65    fig.update_xaxes(title_text="UMAP 1")
  66    fig.update_yaxes(title_text="UMAP 2")
  67
  68    return fig
  69
  70
  71def umap_static(umap_result, width=10, height=13, n_per_col=20):
  72    """
  73    Create a static matplotlib UMAP scatter plot.
  74
  75    Parameters
  76    ----------
  77    umap_result : pandas.DataFrame or dict-like
  78        UMAP projection containing:
  79        - `0` : array-like, UMAP dimension 1
  80        - `1` : array-like, UMAP dimension 2
  81        - `'clusters'` : array-like, cluster assignments
  82
  83    width : float, optional
  84        Width of the figure in inches. Default is 10.
  85
  86    height : float, optional
  87        Height of the figure in inches. Default is 13.
  88
  89    n_per_col : int, optional
  90        Maximum number of legend entries per column. Default is 20.
  91
  92    Returns
  93    -------
  94    matplotlib.figure.Figure
  95        Static matplotlib figure representing the UMAP embedding with clusters.
  96    """
  97
  98    plotly_colors = px.colors.qualitative.Dark24 + px.colors.qualitative.Light24
  99    num_colors = len(plotly_colors)
 100
 101    fig = plt.figure(figsize=(width, height))
 102
 103    sorted_labels = pd.unique(umap_result["clusters"])
 104
 105    color_map = {
 106        label: plotly_colors[i % num_colors] for i, label in enumerate(sorted_labels)
 107    }
 108
 109    for label in sorted_labels:
 110        subset = umap_result[umap_result["clusters"] == label]
 111        plt.scatter(
 112            subset[0],
 113            subset[1],
 114            c=[color_map[label]],
 115            label=f"Cluster {label}",
 116            alpha=0.7,
 117            s=20,
 118            edgecolor="black",
 119            linewidths=0.1,
 120        )
 121
 122    n_col = -(-len(set(umap_result["clusters"])) // n_per_col)
 123
 124    plt.xlabel("UMAP 1", fontsize=14)
 125    plt.ylabel("UMAP 2", fontsize=14)
 126    plt.grid(True, which="both", linestyle="--", linewidth=0.1)
 127    plt.legend(bbox_to_anchor=(1.05, 1), loc="upper left", ncol=n_col)
 128    plt.tight_layout()
 129
 130    return fig
 131
 132
 133def test_data(path=""):
 134    """
 135    Download and extract test data from Google Drive.
 136
 137    This function downloads a compressed archive containing example test data
 138    and extracts it into the specified directory. The data is fetched using
 139    a direct Google Drive link. If the download or extraction fails, an
 140    error message is printed.
 141
 142    Parameters
 143    ----------
 144    path : str, optional
 145        Destination directory where the test dataset will be downloaded and
 146        extracted. Defaults to the current working directory.
 147
 148
 149    Notes
 150    -----
 151    - The downloaded file is named ``test_data.tar.gz``.
 152    - The archive is extracted into ``<path>/test_data``.
 153    - In case of any failure (download or extraction), the function prints
 154      an informative message instead of raising an exception.
 155    """
 156
 157    try:
 158
 159        file_name = "test_data.tar.gz"
 160
 161        file_name = os.path.join(path, file_name)
 162
 163        url = "https://drive.google.com/uc?id=1MhzhleMP7iTzlBVW8eP5sFaonJdg1a3T"
 164
 165        gdown.download(url, file_name, quiet=False)
 166
 167        # Unzip
 168
 169        with tarfile.open(file_name, "r:gz") as tar:
 170            tar.extractall(path=path)
 171
 172        print(
 173            f"\nTest data downloaded succesfully -> {os.path.join(path, 'test_data')}"
 174        )
 175
 176    except:
 177
 178        print(
 179            "\nTest data could not be downloaded. Please check your connection and try again!"
 180        )
 181
 182
 183def prop_plot(df_pivot, chi_df):
 184    """
 185    Create a stacked bar plot of proportional data with post-hoc significance annotations.
 186
 187    Parameters
 188    ----------
 189    df_pivot : pandas.DataFrame
 190        Pivot table where rows represent categories (e.g., compartments) and columns
 191        represent groups. Values are counts or frequencies.
 192
 193    chi_df : pandas.DataFrame
 194        DataFrame containing pairwise Chi-square test results with an added
 195        'Significance_Label' column (e.g., '***', '**', '*', 'ns') for each pair
 196        of groups. Typically output from `chi_pairs` and `get_significance_label`.
 197
 198    Returns
 199    -------
 200    matplotlib.figure.Figure
 201        The Matplotlib figure object containing the stacked bar plot.
 202
 203    Notes
 204    -----
 205    - The function converts raw counts to percentages per group for visualization.
 206    - Each pairwise comparison and its significance label is displayed as a text box
 207      next to the plot.
 208    - Colors are assigned using the 'viridis' colormap by default.
 209    - The plot is configured for clarity with labeled axes, legend, and appropriately
 210      sized text.
 211    """
 212
 213    df_pivot_perc = df_pivot.div(df_pivot.sum(axis=0), axis=1) * 100
 214
 215    chi_df = chi_df.sort_values(by="p-value", ascending=True)
 216
 217    df_pivot_perc = df_pivot_perc.T.sort_values(by=list(df_pivot_perc.index)).T
 218
 219    posthoc_text = "\n".join(
 220        [
 221            f"{row['Group 1']} → {row['Group 2']}: {row['Significance_Label']}"
 222            for _, row in chi_df.iterrows()
 223        ]
 224    )
 225
 226    fig, ax = plt.subplots(figsize=(12, 7))
 227
 228    df_pivot_perc.T.plot(kind="bar", stacked=True, ax=ax, cmap="viridis")
 229
 230    ax.set_ylabel("Percentage (%)", fontsize=16)
 231    ax.set_xlabel("Groups", fontsize=16)
 232
 233    ax.tick_params(axis="both", labelsize=12)
 234
 235    ax.legend(
 236        title="Compartment", loc="upper left", bbox_to_anchor=(1.02, 1.05), fontsize=14
 237    )
 238
 239    plt.figtext(
 240        0.93,
 241        0.6,
 242        posthoc_text,
 243        ha="left",
 244        va="top",
 245        fontsize=12,
 246        bbox={"facecolor": "white", "alpha": 0.7, "pad": 5},
 247    )
 248
 249    return fig
 250
 251
 252def get_significance_label(p_value):
 253    """
 254    Return a standard significance label based on a p-value.
 255
 256    Parameters
 257    ----------
 258    p_value : float
 259        The p-value for which the significance label should be determined.
 260
 261    Returns
 262    -------
 263    str
 264        A significance marker commonly used in statistical reporting:
 265
 266        - '***' : p < 0.001
 267        - '**'  : p < 0.01
 268        - '*'   : p < 0.05
 269        - 'ns'  : not significant (p ≥ 0.05)
 270
 271    Notes
 272    -----
 273    This helper function is typically used for annotating statistical test
 274    results in tables or visualizations. Thresholds follow conventional
 275    statistical notation for significance levels.
 276    """
 277
 278    if p_value < 0.001:
 279        return "***"
 280    elif p_value < 0.01:
 281        return "**"
 282    elif p_value < 0.05:
 283        return "*"
 284    else:
 285        return "ns"
 286
 287
 288def chi_pairs(df_pivot):
 289    """
 290    Compute pairwise Chi-square tests for all combinations of groups in a pivoted dataframe.
 291
 292    Parameters
 293    ----------
 294    df_pivot : pandas.DataFrame
 295        A pivot table where rows represent categories and columns represent groups.
 296        Values should be counts (frequencies). The function will add +1 to each cell
 297        to avoid zero counts during chi-square computation.
 298
 299    Returns
 300    -------
 301    pandas.DataFrame
 302        A DataFrame containing pairwise Chi-square test results with the following columns:
 303        - 'Group 1' : str
 304            Name of the first group in the pair.
 305        - 'Group 2' : str
 306            Name of the second group in the pair.
 307        - 'Chi²' : float
 308            The Chi-square statistic for the comparison.
 309        - 'p-value' : float
 310            The p-value of the Chi-square test.
 311
 312    Notes
 313    -----
 314    The function compares every possible pair of columns using `scipy.stats.chi2_contingency`.
 315    Yates' correction is applied by default unless disabled in the SciPy version used.
 316    A value of 1 is added to all cells to avoid issues with zero frequencies.
 317    """
 318
 319    group_pairs = list(combinations(df_pivot.columns, 2))
 320
 321    posthoc_results = []
 322
 323    for group1, group2 in group_pairs:
 324        sub_table = df_pivot.T.loc[[group1, group2]] + 1
 325        chi2, p, dof, expected = chi2_contingency(sub_table)
 326
 327        posthoc_results.append(
 328            {"Group 1": group1, "Group 2": group2, "Chi²": chi2, "p-value": p}
 329        )
 330
 331    posthoc_df = pd.DataFrame(posthoc_results)
 332
 333    return posthoc_df
 334
 335
 336def statistic(input_df, sets=None, metadata=None, n_proc=10):
 337    """
 338    Compute statistical comparison between cell groups or clusters.
 339
 340    This function performs differential feature analysis between either:
 341    (1) every group vs. all other groups (default mode), or
 342    (2) two user-defined groups specified in ``sets``.
 343
 344    The analysis includes:
 345    - Mann–Whitney U test
 346    - Percentage of non-zero values
 347    - Means and standard deviations
 348    - Effect size metric (ESM)
 349    - Benjamini–Hochberg FDR correction
 350    - Fold-change and log2 fold-change
 351
 352
 353    Parameters
 354    ----------
 355    input_df : pandas.DataFrame
 356        Input feature matrix where rows represent features and columns represent cells.
 357        The function transposes this table internally, treating columns as features.
 358
 359    sets : dict or None, optional
 360        Mode selection:
 361        - ``None`` (default): each unique label in ``metadata['sets']`` is compared
 362          against all remaining groups.
 363        - ``dict``: must contain exactly two keys, each mapping to a list of labels
 364          belonging to each comparison group. Example:
 365          ``{'A': ['T1', 'T2'], 'B': ['C1', 'C2']}``.
 366
 367    metadata : pandas.DataFrame, optional
 368        Metadata containing at least a column ``'sets'`` with group labels
 369        corresponding to columns of ``input_df``.
 370
 371    n_proc : int, optional
 372        Number of parallel processes used for statistical computation.
 373        Default is ``10``.
 374
 375    Returns
 376    -------
 377    pandas.DataFrame or None
 378        A DataFrame containing statistical results for each feature, including:
 379
 380        - ``feature`` : str
 381        - ``p_val`` : float
 382        - ``adj_pval`` : float
 383        - ``pct_valid`` : float
 384        - ``pct_ctrl`` : float
 385        - ``avg_valid`` : float
 386        - ``avg_ctrl`` : float
 387        - ``sd_valid`` : float
 388        - ``sd_ctrl`` : float
 389        - ``esm`` : float
 390        - ``FC`` : float
 391        - ``log(FC)`` : float
 392        - ``norm_diff`` : float
 393        - ``valid_group`` : str
 394        - ``-log(p_val)`` : float
 395
 396        If ``sets`` is ``None``, results for each group are concatenated.
 397
 398        Returns ``None`` in case of errors or invalid parameters.
 399
 400    Notes
 401    -----
 402    - Columns containing only zeros are automatically removed.
 403    - p-values equal for both groups produce ``p_val = 1``.
 404    - Benjamini–Hochberg correction is applied separately within each group comparison.
 405    - Fold-change is stabilized using a small, data-derived ``low_factor``.
 406    - Uses ``Mann–Whitney U`` test with ``alternative='two-sided'``.
 407
 408    Raises
 409    ------
 410    None
 411        All exceptions are caught internally and printed as messages.
 412
 413    Examples
 414    --------
 415    >>> df = pd.DataFrame(...)
 416    >>> meta = pd.DataFrame({'sets': [...]})
 417    >>> stat = statistic(df, metadata=meta)
 418    >>> stat.head()
 419
 420    >>> # Compare two groups explicitly
 421    >>> sets = {'A': ['Type1'], 'B': ['Type2']}
 422    >>> stat = statistic(df, sets=sets, metadata=meta, n_proc=4)
 423    """
 424    try:
 425        offset = 1e-100
 426
 427        def stat_calc(choose, feature_name):
 428            target_values = choose.loc[choose["DEG"] == "target", feature_name]
 429            rest_values = choose.loc[choose["DEG"] == "rest", feature_name]
 430
 431            pct_valid = (target_values > 0).sum() / len(target_values)
 432            pct_rest = (rest_values > 0).sum() / len(rest_values)
 433
 434            avg_valid = np.mean(target_values)
 435            avg_ctrl = np.mean(rest_values)
 436            sd_valid = np.std(target_values, ddof=1)
 437            sd_ctrl = np.std(rest_values, ddof=1)
 438            esm = (avg_valid - avg_ctrl) / np.sqrt(((sd_valid**2 + sd_ctrl**2) / 2))
 439
 440            if np.sum(target_values) == np.sum(rest_values):
 441                p_val = 1.0
 442            else:
 443                _, p_val = stats.mannwhitneyu(
 444                    target_values, rest_values, alternative="two-sided"
 445                )
 446
 447            return {
 448                "feature": feature_name,
 449                "p_val": p_val,
 450                "pct_valid": pct_valid,
 451                "pct_ctrl": pct_rest,
 452                "avg_valid": avg_valid,
 453                "avg_ctrl": avg_ctrl,
 454                "sd_valid": sd_valid,
 455                "sd_ctrl": sd_ctrl,
 456                "esm": esm,
 457            }
 458
 459        def safe_min_half(series):
 460            filtered = series[(series > ((2**-1074) * 2)) & (series.notna())]
 461            return filtered.min() / 2 if not filtered.empty else 0
 462
 463        # Transpose the input DataFrame
 464        choose = input_df.copy().T
 465
 466        if sets is None:
 467            print("\nAnalysis started...")
 468            print("\nComparing each type of cell to others...")
 469            final_results = []
 470
 471            if len(set(metadata["sets"])) > 1:
 472                choose.index = metadata["sets"]
 473
 474            indexes = list(choose.index)
 475
 476            for c in set(indexes):
 477                print(f"Calculating statistics for {c}")
 478
 479                choose.index = indexes
 480                choose["DEG"] = np.where(choose.index == c, "target", "rest")
 481
 482                valid = ",".join(set(choose.index[choose["DEG"] == "target"]))
 483                choose = choose.loc[
 484                    :, (choose != 0).any(axis=0)
 485                ]  # Remove all-zero columns
 486
 487                # Parallel computation
 488                results = Parallel(n_jobs=n_proc)(
 489                    delayed(stat_calc)(choose, feature)
 490                    for feature in tqdm(choose.columns[choose.columns != "DEG"])
 491                )
 492
 493                # Convert results to DataFrame
 494                combined_df = pd.DataFrame(results)
 495                combined_df = combined_df[
 496                    (combined_df["avg_valid"] > 0) | (combined_df["avg_ctrl"] > 0)
 497                ]
 498
 499                combined_df["valid_group"] = valid
 500                combined_df.sort_values(by="p_val", inplace=True)
 501
 502                # Adjusted p-values using Benjamini-Hochberg method
 503                num_tests = len(combined_df)
 504                combined_df["adj_pval"] = np.minimum(
 505                    1, (combined_df["p_val"] * num_tests) / np.arange(1, num_tests + 1)
 506                )
 507
 508                combined_df["p_val"] = combined_df["p_val"].replace(0, 2**-1074)
 509
 510                combined_df["-log(p_val)"] = -np.log10(combined_df["p_val"])
 511
 512                valid_factor = safe_min_half(combined_df["avg_valid"])
 513
 514                ctrl_factor = safe_min_half(combined_df["avg_ctrl"])
 515
 516                cv_factor = min(valid_factor, ctrl_factor)
 517
 518                if cv_factor == 0:
 519                    cv_factor = max(valid_factor, ctrl_factor)
 520
 521                if not np.isfinite(cv_factor) or cv_factor == 0:
 522                    cv_factor += offset
 523
 524                valid = combined_df["avg_valid"].where(
 525                    combined_df["avg_valid"] != 0, combined_df["avg_valid"] + cv_factor
 526                )
 527
 528                ctrl = combined_df["avg_ctrl"].where(
 529                    combined_df["avg_ctrl"] != 0, combined_df["avg_ctrl"] + cv_factor
 530                )
 531
 532                combined_df["FC"] = valid / ctrl
 533
 534                combined_df["log(FC)"] = np.log2(combined_df["FC"])
 535                combined_df["norm_diff"] = (
 536                    combined_df["avg_valid"] - combined_df["avg_ctrl"]
 537                )
 538
 539                final_results.append(combined_df)
 540
 541            print("\nAnalysis has finished!")
 542            return pd.concat(final_results, ignore_index=True)
 543
 544        elif isinstance(sets, dict):
 545            print("\nAnalysis started...")
 546            print("\nComparing groups...")
 547
 548            group_list = list(sets.keys())
 549            choose.index = metadata["sets"]
 550
 551            inx = sorted([item for sublist in sets.values() for item in sublist])
 552            choose = choose.loc[inx]
 553
 554            full_df = pd.DataFrame()
 555            for n, g in enumerate(group_list):
 556                print(f"Calculating statistics for {g}")
 557
 558                rest_indices = [
 559                    idx
 560                    for i, group in enumerate(group_list)
 561                    if i != n
 562                    for idx in sets[group]
 563                ]
 564
 565                choose["DEG"] = np.where(
 566                    choose.index.isin(sets[g]),
 567                    "target",
 568                    np.where(choose.index.isin(rest_indices), "rest", "drop"),
 569                )
 570
 571                choose = choose[choose["DEG"] != "drop"]
 572
 573                valid = g
 574                choose = choose.loc[
 575                    :, (choose != 0).any(axis=0)
 576                ]  # Remove all-zero columns
 577
 578                # Parallel computation
 579                results = Parallel(n_jobs=n_proc)(
 580                    delayed(stat_calc)(choose, feature)
 581                    for feature in tqdm(choose.columns[choose.columns != "DEG"])
 582                )
 583
 584                # Convert results to DataFrame
 585                combined_df = pd.DataFrame(results)
 586                combined_df["valid_group"] = valid
 587                combined_df.sort_values(by="p_val", inplace=True)
 588
 589                # Adjusted p-values using Benjamini-Hochberg method
 590                num_tests = len(combined_df)
 591                combined_df["adj_pval"] = np.minimum(
 592                    1, (combined_df["p_val"] * num_tests) / np.arange(1, num_tests + 1)
 593                )
 594
 595                combined_df["-log(p_val)"] = -np.log10(offset + combined_df["p_val"])
 596
 597                valid_factor = safe_min_half(combined_df["avg_valid"])
 598
 599                ctrl_factor = safe_min_half(combined_df["avg_ctrl"])
 600
 601                cv_factor = min(valid_factor, ctrl_factor)
 602
 603                if cv_factor == 0:
 604                    cv_factor = max(valid_factor, ctrl_factor)
 605
 606                if not np.isfinite(cv_factor) or cv_factor == 0:
 607                    cv_factor += offset
 608
 609                valid = combined_df["avg_valid"].where(
 610                    combined_df["avg_valid"] != 0, combined_df["avg_valid"] + cv_factor
 611                )
 612
 613                ctrl = combined_df["avg_ctrl"].where(
 614                    combined_df["avg_ctrl"] != 0, combined_df["avg_ctrl"] + cv_factor
 615                )
 616
 617                combined_df["FC"] = valid / ctrl
 618
 619                combined_df["log(FC)"] = np.log2(combined_df["FC"])
 620                combined_df["norm_diff"] = (
 621                    combined_df["avg_valid"] - combined_df["avg_ctrl"]
 622                ) + offset
 623
 624                full_df = pd.concat([full_df, combined_df])
 625
 626            print("\nAnalysis has finished!")
 627            return full_df
 628
 629        else:
 630            print("\nInvalid parameters. Please check the input.")
 631            return None
 632
 633    except Exception as e:
 634        print(f"Error: {e}")
 635        return None
 636
 637
 638# UTILS JIMG
 639
 640
 641def save_image(image, path_to_save):
 642    """
 643    Save an image to disk.
 644
 645    Parameters
 646    ----------
 647    image : np.ndarray
 648        Input image array to be saved.
 649
 650    path_to_save : str
 651        Output file path including the filename.
 652        Must include one of the following extensions:
 653        ``.png``, ``.tiff`` or ``.tif``.
 654
 655    Returns
 656    -------
 657    str
 658        Path to the saved file.
 659    """
 660
 661    try:
 662        if (
 663            len(path_to_save) == 0
 664            or ".png" not in path_to_save
 665            or ".tiff" not in path_to_save
 666            or ".tif" not in path_to_save
 667        ):
 668            print(
 669                "\nThe path is not provided or the file extension is not *.png, *.tiff or *.tif"
 670            )
 671        else:
 672            cv2.imwrite(path_to_save, image)
 673
 674    except:
 675        print("Something went wrong. Check the function input data and try again!")
 676
 677
 678def load_tiff(path_to_tiff: str):
 679    """
 680    Load a *.tiff image and ensure it is in 16-bit format.
 681
 682    Parameters
 683    ----------
 684    path_to_tiff : str
 685        Path to the *.tiff file.
 686
 687    Returns
 688    -------
 689    np.ndarray
 690        Loaded image stack, converted to 16-bit if necessary.
 691    """
 692
 693    try:
 694        stack = tiff.imread(path_to_tiff)
 695
 696        if stack.dtype != "uint16":
 697
 698            stack = stack.astype(np.uint16)
 699
 700            for n, _ in enumerate(stack):
 701
 702                min_val = np.min(stack[n])
 703                max_val = np.max(stack[n])
 704
 705                stack[n] = ((stack[n] - min_val) / (max_val - min_val) * 65535).astype(
 706                    np.uint16
 707                )
 708
 709                stack[n] = np.clip(stack[n], 0, 65535)
 710
 711        return stack
 712
 713    except:
 714        print("Something went wrong. Check the function input data and try again!")
 715
 716
 717def z_projection(tiff_object, projection_type="avg"):
 718    """
 719    Perform Z-projection on a stacked (3D) image.
 720
 721    Parameters
 722    ----------
 723    tiff_object : np.ndarray
 724        Input stacked 3D image (e.g., loaded with `load_tiff()`).
 725
 726    projection_type : str
 727        Type of Z-axis projection. Options: 'avg', 'median', 'min', 'max', 'std'.
 728
 729    Returns
 730    -------
 731    np.ndarray
 732        Resulting 2D projection image.
 733    """
 734
 735    try:
 736
 737        if projection_type == "avg":
 738            img = np.mean(tiff_object, axis=0).astype(np.uint16)
 739        elif projection_type == "max":
 740            img = np.max(tiff_object, axis=0).astype(np.uint16)
 741        elif projection_type == "min":
 742            img = np.min(tiff_object, axis=0).astype(np.uint16)
 743        elif projection_type == "std":
 744            img = np.std(tiff_object, axis=0).astype(np.uint16)
 745        elif projection_type == "median":
 746            img = np.median(tiff_object, axis=0).astype(np.uint16)
 747
 748        return img
 749
 750    except:
 751        print("Something went wrong. Check the function input data and try again!")
 752
 753
 754def clahe_16bit(img, kernal=(100, 100)):
 755    """
 756    Apply CLAHE (Contrast Limited Adaptive Histogram Equalization) to an image.
 757
 758    Parameters
 759    ----------
 760    img : np.ndarray
 761        Input image.
 762
 763    Returns
 764    -------
 765    img : np.ndarray
 766        Image after CLAHE enhancement.
 767
 768    kernel : tuple
 769        Size of the CLAHE tile grid used for processing, e.g., (100, 100).
 770    """
 771
 772    try:
 773
 774        img = img.copy()
 775
 776        img8bit = img.copy()
 777
 778        min_val = np.min(img8bit)
 779        max_val = np.max(img8bit)
 780
 781        img8bit = ((img8bit - min_val) / (max_val - min_val) * 255).astype(np.uint8)
 782
 783        clahe = cv2.createCLAHE(clipLimit=10, tileGridSize=kernal)
 784        img8bit = clahe.apply(img8bit)
 785
 786        img8bit = img8bit / 255
 787
 788        img = img * img8bit
 789
 790        min_val = np.min(img)
 791        max_val = np.max(img)
 792
 793        img = ((img - min_val) / (max_val - min_val) * 65535).astype(np.uint16)
 794
 795        return img
 796
 797    except:
 798        print("Something went wrong. Check the function input data and try again!")
 799
 800
 801def equalizeHist_16bit(image_eq):
 802    """
 803    Apply global histogram equalization to an image.
 804
 805    Parameters
 806    ----------
 807    image_eq : np.ndarray
 808        Input image.
 809
 810    Returns
 811    -------
 812    np.ndarray
 813        Image after global histogram equalization.
 814    """
 815
 816    try:
 817
 818        image = image_eq.copy()
 819
 820        min_val = np.min(image)
 821        max_val = np.max(image)
 822
 823        scaled_image = ((image - min_val) / (max_val - min_val) * 255).astype(np.uint8)
 824
 825        eq_image = cv2.equalizeHist(scaled_image)
 826
 827        eq_image_bin = eq_image / 255
 828
 829        image_eq_16 = image * eq_image_bin
 830        image_eq_16 = (image_eq_16 / np.max(image_eq_16)) * 65535
 831        image_eq_16[image_eq_16 > (65535 / 2)] += 65535 - np.max(image_eq_16)
 832        image_eq_16 = image_eq_16.astype(np.uint16)
 833
 834        return image_eq_16
 835
 836    except:
 837        print("Something went wrong. Check the function input data and try again!")
 838
 839
 840def load_image(path):
 841    """
 842    Load an image and convert it to 16-bit if necessary.
 843
 844    Parameters
 845    ----------
 846    path : str
 847        Path to the image file.
 848
 849    Returns
 850    -------
 851    np.ndarray
 852        Loaded 16-bit image.
 853    """
 854
 855    try:
 856
 857        img = cv2.imread(path, cv2.IMREAD_ANYDEPTH | cv2.IMREAD_COLOR)
 858
 859        # convert to 16 bit (the function are working on 16 bit images!)
 860        if img.dtype != "uint16":
 861
 862            min_val = np.min(img)
 863            max_val = np.max(img)
 864
 865            img = ((img - min_val) / (max_val - min_val) * 65535).astype(np.uint16)
 866
 867            img = np.clip(img, 0, 65535)
 868
 869        return img
 870
 871    except:
 872        print("Something went wrong. Check the function input data and try again!")
 873
 874
 875def rotate_image(img, rotate: int):
 876    """
 877    Rotate an image by a specified angle.
 878
 879    Parameters
 880    ----------
 881    img : np.ndarray
 882        Image to rotate.
 883
 884    rotate : int
 885        Degree of rotation. Available options: 90, 180, 270.
 886
 887    Returns
 888    -------
 889    np.ndarray
 890        Rotated image.
 891    """
 892
 893    try:
 894
 895        if rotate == 0:
 896            r = 0
 897        elif rotate == 90:
 898            r = -1
 899        elif rotate == 180:
 900            r = 2
 901        elif rotate == 180:
 902            r = 2
 903        elif rotate == 270:
 904            r = 1
 905        else:
 906            print("Wrong argument - rotate!")
 907            return None
 908
 909        img = img.copy()
 910
 911        img = np.rot90(img.copy(), k=r)
 912
 913        return img
 914
 915    except:
 916        print("Something went wrong. Check the function input data and try again!")
 917
 918
 919def mirror_image(img, rotate: str):
 920    """
 921    Mirror an image along specified axes.
 922
 923    Parameters
 924    ----------
 925    img : np.ndarray
 926        Image to mirror.
 927
 928    rotate : str
 929        Type of mirroring to apply. Options:
 930            'h'  - horizontal mirroring
 931            'v'  - vertical mirroring
 932            'hv' - both horizontal and vertical mirroring
 933
 934    Returns
 935    -------
 936    np.ndarray
 937        Mirrored image.
 938    """
 939
 940    try:
 941
 942        if rotate == "h":
 943            img = np.fliplr(img.copy())
 944        elif rotate == "v":
 945            img = np.flipud(img.copy())
 946        elif rotate == "hv":
 947            img = np.flipud(np.fliplr(img.copy()))
 948        else:
 949            print("Wrong argument - rotate!")
 950            return None
 951
 952        return img
 953
 954    except:
 955        print("Something went wrong. Check the function input data and try again!")
 956
 957
 958# validatet UTILS
 959
 960
 961def merge_images(image_list: list, intensity_factors: list = []):
 962    """
 963    Merge multiple image projections from different channels.
 964
 965    Parameters
 966    ----------
 967    image_list : list of np.ndarray
 968        List of images to merge. All images must have the same shape and size.
 969
 970    intensity_factors : list of float
 971        Intensity scaling factors for each image in `image_list`. Base value is 1.
 972            - Values < 1 decrease intensity.
 973            - Values > 1 increase intensity.
 974
 975    Returns
 976    -------
 977    np.ndarray
 978        Merged image after applying intensity scaling.
 979    """
 980
 981    try:
 982
 983        result = None
 984
 985        if len(intensity_factors) == 0:
 986
 987            intensity_factors = []
 988            for bt in range(len(image_list)):
 989                intensity_factors.append(1)
 990
 991        for i, image in enumerate(image_list):
 992            if result is None:
 993                result = image.astype(np.uint64) * intensity_factors[i]
 994            else:
 995                result = cv2.addWeighted(
 996                    result, 1, image.astype(np.uint64) * intensity_factors[i], 1, 0
 997                )
 998
 999        result = np.clip(result, 0, 65535)
1000
1001        result = result.astype(np.uint16)
1002
1003        return result
1004
1005    except:
1006        print("Something went wrong. Check the function input data and try again!")
1007
1008
1009def adjust_img_16bit(
1010    img,
1011    color="gray",
1012    max_intensity: int = 65535,
1013    min_intenisty: int = 0,
1014    brightness: int = 1000,
1015    contrast=1.0,
1016    gamma=1.0,
1017):
1018    """
1019    Manually adjust image parameters and return the adjusted image.
1020
1021    Parameters
1022    ----------
1023    img : np.ndarray
1024        Input image.
1025
1026    color : str
1027        Image color channel. Options: ['green', 'blue', 'red', 'yellow', 'magenta', 'cyan'].
1028
1029    max_intensity : int
1030        Upper threshold for pixel values. Pixels exceeding this value are set to `max_intensity`.
1031
1032    min_intensity : int
1033        Lower threshold for pixel values. Pixels below this value are set to 0.
1034
1035    brightness : int, optional
1036        Image brightness adjustment. Typical range: [900-2000]. Default is 1000.
1037
1038    contrast : float or int, optional
1039        Image contrast adjustment. Typical range: [0-5]. Default is 1.
1040
1041    gamma : float or int, optional
1042        Gamma correction factor. Typical range: [0-5]. Default is 1.
1043
1044    Returns
1045    -------
1046    np.ndarray
1047        Adjusted image after applying brightness, contrast, gamma, and intensity thresholds.
1048    """
1049
1050    try:
1051
1052        img = img.copy()
1053
1054        img = img.astype(np.uint64)
1055
1056        img = np.clip(img, 0, 65535)
1057
1058        # brightness
1059        if brightness != 1000:
1060            factor = -1000 + brightness
1061            side = factor / abs(factor)
1062            img[img > 0] = img[img > 0] + ((img[img > 0] * abs(factor) / 100) * side)
1063            img = np.clip(img, 0, 65535)
1064
1065        # contrast
1066        if contrast != 1:
1067            img = ((img - np.mean(img)) * contrast) + np.mean(img)
1068            img = np.clip(img, 0, 65535)
1069
1070        # gamma
1071        if gamma != 1:
1072
1073            max_val = np.max(img)
1074
1075            image_array = img.copy() / max_val
1076
1077            image_array = np.clip(image_array, 0, 1)
1078
1079            corrected_array = image_array ** (1 / gamma)
1080
1081            img = corrected_array * max_val
1082
1083            del image_array, corrected_array
1084
1085            img = np.clip(img, 0, 65535)
1086
1087        img = np.nan_to_num(img, nan=0, posinf=65535, neginf=0)
1088        max_val = np.max(img)
1089        if max_val > 0:
1090            img = ((img / max_val) * 65535).astype(np.uint16)
1091
1092        # max intenisty
1093        if max_intensity != 65535:
1094            img[img >= max_intensity] = 65535
1095
1096        # min intenisty
1097        if min_intenisty != 0:
1098            img[img <= min_intenisty] = 0
1099
1100        img_gamma = np.zeros((img.shape[0], img.shape[1], 3), dtype=np.uint16)
1101
1102        if color == "green":
1103            img_gamma[:, :, 1] = img
1104
1105        elif color == "red":
1106            img_gamma[:, :, 2] = img
1107
1108        elif color == "blue":
1109            img_gamma[:, :, 0] = img
1110
1111        elif color == "magenta":
1112            img_gamma[:, :, 0] = img
1113            img_gamma[:, :, 2] = img
1114
1115        elif color == "yellow":
1116            img_gamma[:, :, 1] = img
1117            img_gamma[:, :, 2] = img
1118
1119        elif color == "cyan":
1120            img_gamma[:, :, 0] = img
1121            img_gamma[:, :, 1] = img
1122
1123        elif color == "gray":
1124            img_gamma[:, :, 0] = img
1125            img_gamma[:, :, 1] = img
1126            img_gamma[:, :, 2] = img
1127
1128        return img_gamma
1129
1130    except:
1131        print("Something went wrong. Check the function input data and try again!")
1132
1133
1134def get_screan():
1135    """
1136    Get the current screen width and height.
1137
1138    Returns
1139    -------
1140    tuple of int
1141        screen_width, screen_height
1142    """
1143
1144    root = tk.Tk()
1145    screen_width = root.winfo_screenwidth()
1146    screen_height = root.winfo_screenheight()
1147
1148    root.destroy()
1149
1150    return screen_width, screen_height
1151
1152
1153def resize_to_screen_img(img_file, factor=1):
1154    """
1155    Resize an input image to fit the screen size, optionally scaled by a factor.
1156
1157    Parameters
1158    ----------
1159    img_file : np.ndarray
1160        Input image to be resized.
1161
1162    factor : float, optional
1163        Scaling factor applied to the screen dimensions before resizing the image. Default is 1.
1164
1165    Returns
1166    -------
1167    np.ndarray
1168        Resized image that fits within the screen dimensions while maintaining aspect ratio.
1169    """
1170
1171    screen_width, screen_height = get_screan()
1172
1173    screen_width = int(screen_width * factor)
1174    screen_height = int(screen_height * factor)
1175
1176    h = int(img_file.shape[0])
1177    w = int(img_file.shape[1])
1178
1179    if screen_width < w:
1180        h = img_file.shape[0]
1181        w = img_file.shape[1]
1182
1183        ww = int((screen_width / w) * w)
1184        hh = int((screen_width / w) * h)
1185
1186        img_file = cv2.resize(img_file, (ww, hh))
1187
1188        h = img_file.shape[0]
1189        w = img_file.shape[1]
1190
1191    if screen_height < h:
1192        h = img_file.shape[0]
1193        w = img_file.shape[1]
1194
1195        ww = int((screen_height / h) * w)
1196        hh = int((screen_height / h) * h)
1197
1198        img_file = cv2.resize(img_file, (ww, hh))
1199
1200    return img_file
1201
1202
1203def display_preview(image):
1204    """
1205    Quickly preview an image using a display window.
1206
1207    Parameters
1208    ----------
1209    image : np.ndarray
1210        Input image to be displayed.
1211
1212    Notes
1213    -----
1214        The function displays the image in a window. Does not return a value.
1215    """
1216    try:
1217
1218        res_sc = resize_to_screen_img(image.copy(), factor=0.8)
1219
1220        cv2.imshow("Display", res_sc)
1221
1222        cv2.waitKey(0) & 0xFF
1223
1224        cv2.destroyAllWindows()
1225
1226    except:
1227        print("Something went wrong. Check the function input data and try again!")
1228
1229
1230## flow_JIMG_functions
1231
1232
1233class ImageTools:
1234    """
1235    Collection of utility functions for image preprocessing, adjustment,
1236    merging, and stitching.
1237
1238    This class provides standalone static methods for operations such as
1239    histogram equalization, CLAHE enhancement, intensity adjustments,
1240    image merging based on weighted ratios, and horizontal stitching.
1241    These tools are used internally by `ImagesManagement` but can also be
1242    applied independently for generic image-processing workflows.
1243
1244    Notes
1245    -----
1246    All methods operate on NumPy arrays and expect images in standard
1247    OpenCV format. Some functions assume 16-bit images unless stated
1248    otherwise.
1249
1250    Examples
1251    --------
1252    >>> from ImageTools import ImageTools
1253    >>> img = ImageTools.equalize_hist_16bit(img)
1254    >>> merged = ImageTools.merge_images([img1, img2], [0.5, 0.5])
1255    """
1256
1257    def get_screan(self):
1258        """
1259        Return the current screen size.
1260
1261        Returns
1262        -------
1263        screen_width : int
1264            Width of the screen in pixels.
1265
1266        screen_height : int
1267            Height of the screen in pixels.
1268        """
1269
1270        root = tk.Tk()
1271        screen_width = root.winfo_screenwidth()
1272        screen_height = root.winfo_screenheight()
1273
1274        root.destroy()
1275
1276        return screen_width, screen_height
1277
1278    def resize_to_screen_img(self, img_file, factor=0.5):
1279        """
1280        Resize an input image to a scaled version of the current screen size.
1281
1282        Parameters
1283        ----------
1284        img_file : np.ndarray
1285            Input image to be resized.
1286
1287        factor : int
1288            Scaling factor applied to the screen dimensions.
1289
1290        Returns
1291        -------
1292        resized_image : np.ndarray
1293            Resized image adjusted to the scaled screen size.
1294        """
1295
1296        screen_width, screen_height = self.get_screan()
1297
1298        screen_width = int(screen_width * factor)
1299        screen_height = int(screen_height * factor)
1300
1301        h = int(img_file.shape[0])
1302        w = int(img_file.shape[1])
1303
1304        if screen_width < w or screen_width * 0.3 > w:
1305            h = img_file.shape[0]
1306            w = img_file.shape[1]
1307
1308            ww = int((screen_width / w) * w)
1309            hh = int((screen_width / w) * h)
1310
1311            img_file = cv2.resize(img_file, (ww, hh))
1312
1313            h = img_file.shape[0]
1314            w = img_file.shape[1]
1315
1316        if screen_height < h or screen_height * 0.3 > h:
1317            h = img_file.shape[0]
1318            w = img_file.shape[1]
1319
1320            ww = int((screen_height / h) * w)
1321            hh = int((screen_height / h) * h)
1322
1323            img_file = cv2.resize(img_file, (ww, hh))
1324
1325        return img_file
1326
1327    def load_JIMG_project(self, project_path):
1328        """
1329        Load a JIMG project from a `.pjm` file.
1330
1331        Parameters
1332        ----------
1333        file_path : str
1334            Path to the project file with `.pjm` extension.
1335
1336        Returns
1337        -------
1338        project : object
1339            Loaded project object.
1340
1341        Raises
1342        ------
1343        ValueError
1344            If the provided file does not have a `.pjm` extension.
1345        """
1346
1347        if ".pjm" in project_path:
1348            with open(project_path, "rb") as file:
1349                app_metadata_tmp = pickle.load(file)
1350
1351            return app_metadata_tmp
1352
1353        else:
1354            print("\nProvide path to the project metadata file with *.pjm extension!!!")
1355
1356    def ajd_mask_size(self, image, mask):
1357        """
1358        Adjusts the size of a mask to match the dimensions of a given image.
1359
1360        Parameters
1361        ----------
1362        image : np.ndarray
1363            Reference image whose size the mask should match. Can be 2D or 3D.
1364
1365        mask : np.ndarray
1366            Mask image to be resized.
1367
1368        Returns
1369        -------
1370        np.ndarray
1371            Resized mask matching the input image dimensions.
1372        """
1373
1374        try:
1375            mask = cv2.resize(mask, (image.shape[2], image.shape[1]))
1376        except:
1377            mask = cv2.resize(mask, (image.shape[1], image.shape[0]))
1378
1379        return mask
1380
1381    def load_image(self, path_to_image):
1382        """
1383        Load an image from the specified file path.
1384
1385        Parameters
1386        ----------
1387        path_to_image : str
1388            Path to the image file.
1389
1390        Returns
1391        -------
1392        image : np.ndarray
1393            Loaded image as a NumPy array.
1394        """
1395
1396        image = load_image(path_to_image)
1397        return image
1398
1399    def load_3D_tiff(self, path_to_image):
1400        """
1401        Load a 3D image from a TIFF file.
1402
1403        Parameters
1404        ----------
1405        path_to_image : str
1406            Path to the 3D TIFF image file.
1407
1408        Returns
1409        -------
1410        image : np.ndarray
1411            Loaded 3D image as a NumPy array.
1412        """
1413
1414        image = load_tiff(path_to_image)
1415
1416        return image
1417
1418    def load_mask(self, path_to_mask):
1419        """
1420        Load a mask image.
1421
1422        Parameters
1423        ----------
1424        path_to_mask : str
1425            Path to the mask image file.
1426
1427        Returns
1428        -------
1429        mask : np.ndarray
1430            Loaded mask image as a NumPy array.
1431        """
1432
1433        mask = cv2.imread(path_to_mask, cv2.IMREAD_GRAYSCALE)
1434        return mask
1435
1436    def save(self, image, file_name):
1437        """
1438        Save an image to disk.
1439
1440        Parameters
1441        ----------
1442        image : np.ndarray
1443            Image data to be saved.
1444
1445        file_name : str
1446            Output file path including the desired image extension (e.g., ".png", ".jpg").
1447
1448        """
1449
1450        cv2.imwrite(filename=file_name, img=image)
1451
1452    # calculation methods
1453
1454    def drop_dict(self, dictionary, key, var, action=None):
1455        """
1456        Filters elements from a dictionary based on a condition applied to a specified key.
1457
1458        Parameters
1459        ----------
1460        dictionary : dict
1461            Dictionary containing lists or arrays under each key.
1462
1463        key : str
1464            The key in the dictionary on which the filtering condition will be applied.
1465
1466        var : numeric
1467            Value to compare against each element in dictionary[key].
1468
1469        action : str, optional
1470            Comparison operator as string: '<=', '>=', '==', '<', '>'.
1471            Default is None, which raises an error.
1472
1473        Returns
1474        -------
1475        dict
1476            A new dictionary with elements removed where the condition matches.
1477        """
1478
1479        dictionary = copy.deepcopy(dictionary)
1480        indices_to_drop = []
1481        for i, dr in enumerate(dictionary[key]):
1482
1483            if isinstance(dr, np.ndarray):
1484                dr = np.mean(dr)
1485
1486            if action == "<=":
1487                if var <= dr:
1488                    indices_to_drop.append(i)
1489            elif action == ">=":
1490                if var >= dr:
1491                    indices_to_drop.append(i)
1492            elif action == "==":
1493                if var == dr:
1494                    indices_to_drop.append(i)
1495            elif action == "<":
1496                if var < dr:
1497                    indices_to_drop.append(i)
1498            elif action == ">":
1499                if var > dr:
1500                    indices_to_drop.append(i)
1501            else:
1502                print("\nWrong action!")
1503                return None
1504
1505        for key, value in dictionary.items():
1506            dictionary[key] = [
1507                v for i, v in enumerate(value) if i not in indices_to_drop
1508            ]
1509
1510        return dictionary
1511
1512    # modified for gradation (separation near nucleus)
1513
1514    def create_mask(self, dictionary, image):
1515        """
1516        Creates a mask image with gradated intensity values for each coordinate set in a dictionary.
1517
1518        Parameters
1519        ----------
1520        dictionary : dict
1521            Dictionary containing a 'coords' key with a list of arrays of coordinates.
1522
1523        image : np.ndarray
1524            Base image to define the shape of the mask.
1525
1526        Returns
1527        -------
1528        np.ndarray
1529            Mask image with uint16 gradated intensity.
1530        """
1531
1532        image_mask = np.zeros(image.shape)
1533
1534        arrays_list = copy.deepcopy(dictionary["coords"])
1535
1536        if len(arrays_list) > 0:
1537
1538            initial_val = math.floor((2**16 - 1) / 4)
1539            intensity_list = ((2**16 - 1) - math.floor((2**16 - 1) / 4)) / len(
1540                arrays_list
1541            )
1542
1543            gradation = 1
1544            for arr in arrays_list:
1545                image_mask[arr[:, 0], arr[:, 1]] = initial_val + (
1546                    gradation * intensity_list
1547                )
1548                gradation += 1
1549
1550        return image_mask.astype("uint16")
1551
1552    def min_max_histograme(self, image):
1553        """
1554        Calculates histogram-based minimum and maximum intensity percentiles in an image.
1555
1556        Parameters
1557        ----------
1558        image : np.ndarray
1559            Input image for histogram analysis.
1560
1561        Returns
1562        -------
1563        min_val : float
1564            Minimum intensity percentile above zero.
1565
1566        max_val : float
1567            Maximum intensity percentile based on histogram gradient.
1568
1569        df : pd.DataFrame
1570            DataFrame containing quantiles, corresponding intensity values, and cumulative percents.
1571        """
1572
1573        q = []
1574        val = []
1575        perc = []
1576
1577        max_val = image.shape[0] * image.shape[1]
1578
1579        for n in range(0, 100, 5):
1580            q.append(n)
1581            val.append(np.quantile(image, n / 100))
1582            sum_val = np.sum(image < np.quantile(image, n / 100))
1583            pr = sum_val / max_val
1584            perc.append(pr)
1585
1586        df = pd.DataFrame({"q": q, "val": val, "perc": perc})
1587
1588        min_val = 0
1589        for i in df.index:
1590            if df["val"][i] != 0 and min_val == 0:
1591                min_val = df["perc"][i]
1592
1593        max_val = 0
1594        df = df[df["perc"] > 0]
1595        df = df.sort_values("q", ascending=False).reset_index(drop=True)
1596
1597        for i in df.index:
1598            if i > 1 and df["val"][i] * 1.5 > df["val"][i - 1]:
1599                max_val = df["perc"][i]
1600                break
1601            elif i == len(df.index) - 1:
1602                max_val = df["perc"][i]
1603
1604        return min_val, max_val, df