Skip to content

io_utils

tit.stats.io_utils

Input/Output utilities for neuroimaging data

This module contains functions for: - Saving permutation logs (group comparison and correlation)

save_permutation_details 

save_permutation_details(permutation_info, output_file, subject_ids_resp, subject_ids_non_resp, paired=False)

Save detailed information about each permutation to a file

Parameters:

permutation_info : list of dict List containing permutation details with keys: - 'perm_num': permutation number - 'perm_idx': permutation indices, or for a paired run the +/-1 sign flips - 'max_cluster_size': maximum cluster statistic found (size or mass) output_file : str Path to output file subject_ids_resp : list Original responder subject IDs subject_ids_non_resp : list Original non-responder subject IDs paired : bool A paired run permutes by flipping signs within pairs: each line lists the flip vector in pair order (-1 swaps that pair's two conditions), not a relabelling.

Source code in tit/stats/io_utils.py 
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
def save_permutation_details(
    permutation_info, output_file, subject_ids_resp, subject_ids_non_resp, paired=False
):
    """
    Save detailed information about each permutation to a file

    Parameters:
    -----------
    permutation_info : list of dict
        List containing permutation details with keys:
        - 'perm_num': permutation number
        - 'perm_idx': permutation indices, or for a paired run the +/-1 sign flips
        - 'max_cluster_size': maximum cluster statistic found (size or mass)
    output_file : str
        Path to output file
    subject_ids_resp : list
        Original responder subject IDs
    subject_ids_non_resp : list
        Original non-responder subject IDs
    paired : bool
        A paired run permutes by flipping signs within pairs: each line lists the flip
        vector in pair order (-1 swaps that pair's two conditions), not a relabelling.
    """
    all_subject_ids = subject_ids_resp + subject_ids_non_resp
    n_resp = len(subject_ids_resp)

    with open(output_file, "w") as f:
        f.write("=" * 80 + "\n")
        f.write("PERMUTATION TEST DETAILS\n")
        f.write("=" * 80 + "\n\n")
        f.write(f"Total permutations: {len(permutation_info)}\n")
        f.write(f"Original Responders (n={n_resp}): {subject_ids_resp}\n")
        f.write(
            f"Original Non-Responders (n={len(subject_ids_non_resp)}): {subject_ids_non_resp}\n"
        )
        if paired:
            f.write(
                "Paired: each line flips signs within pairs, in pair order; "
                "-1 swaps that pair's two conditions.\n"
            )
        f.write("\n" + "=" * 80 + "\n\n")

        for info in permutation_info:
            perm_num = info["perm_num"]
            perm_idx = info["perm_idx"]
            max_stat = info["max_cluster_size"]

            f.write(f"Permutation {perm_num:4d}: ")
            if paired:
                f.write(f"Sign flips: {[int(s) for s in perm_idx]}, ")
            else:
                perm_resp_ids = [all_subject_ids[i] for i in perm_idx[:n_resp]]
                perm_non_resp_ids = [all_subject_ids[i] for i in perm_idx[n_resp:]]
                f.write(f"Responders: {perm_resp_ids}, ")
                f.write(f"Non-Responders: {perm_non_resp_ids}, ")
            f.write(f"Max Cluster Stat: {_format_stat(max_stat)}\n")

save_correlation_permutation_details 

save_correlation_permutation_details(permutation_info, output_file, subject_ids)

Save each correlation permutation's effect-size shuffle to a file.

In permutation k subject subject_ids[j] is given the effect size of subject_ids[perm_idx[j]]; each line lists those donors in subject order. permutation_info has the keys :func:save_permutation_details documents.

Source code in tit/stats/io_utils.py 
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
def save_correlation_permutation_details(permutation_info, output_file, subject_ids):
    """Save each correlation permutation's effect-size shuffle to a file.

    In permutation ``k`` subject ``subject_ids[j]`` is given the effect size of
    ``subject_ids[perm_idx[j]]``; each line lists those donors in subject order.
    ``permutation_info`` has the keys :func:`save_permutation_details` documents.
    """
    with open(output_file, "w") as f:
        f.write("=" * 80 + "\n")
        f.write("PERMUTATION TEST DETAILS (CORRELATION)\n")
        f.write("=" * 80 + "\n\n")
        f.write(f"Total permutations: {len(permutation_info)}\n")
        f.write(f"Subjects (n={len(subject_ids)}): {subject_ids}\n")
        f.write(
            "Each line names, in subject order, whose effect size each subject got.\n"
        )
        f.write("\n" + "=" * 80 + "\n\n")

        for info in permutation_info:
            donors = [subject_ids[i] for i in info["perm_idx"]]
            f.write(f"Permutation {info['perm_num']:4d}: ")
            f.write(f"Effect sizes from: {donors}, ")
            f.write(f"Max Cluster Stat: {_format_stat(info['max_cluster_size'])}\n")