FIX: Clarify phase encoding direction, rather than axis

[mgxd]

BOLD runs' FunctionalSummary nodes were returning PE-Axis instead of PE-Direction.

[effigies]

This is only true for LAS images. We need the orientation of the original image, to be certain.

[mgxd]

Good point - I've added a commit to consider LAS/RAS. How extensive do you think our support should be for different orientations?

[effigies]

We can get images in any orientation. Need something like:

def get_world_pedir(img, pe_direction):
    axes = (("Right", "Left"),
            ("Anterior", "Posterior"),
            ("Superior", "Inferior"))
    ax_idcs = {"i": 0, "j": 1, "k": 2}

    ornt = ''.join(nb.aff2axcodes(img.affine))
    axcode = ornt[ax_idcs[pe_direction[0]]]
    inv = pe_direction[1:] == "-"

    for ax in axes:
        for flip in (ax, ax[::-1]):
            if flip[not inv].startswith(axcode):
                return "-".join(flip)
    raise ValueError(f"Cannot determine world direction of phase encoding. Orientation: {ornt}; PE dir: {pe_direction}")

[effigies]

Incidentally, for testing, I've recently written this, which allows you to generate an image of any orientation:

def generate_image(params):
    dataobj = np.zeros(params["shape"], params["dtype"]) 
    affine = np.eye(4) 
    rot = ornt.inv_ornt_aff(ornt.axcodes2ornt(params["orientation"]), (1, 1, 1)) 
    affine[:3, :3] = np.diag(params["zooms"][:3]) @ np.linalg.inv(rot[:3, :3]) 
    return nb.Nifti1Image(dataobj, affine)

(It's intended for generating datasets on the fly, which is why it's so parameterized.)