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