Get expression samples inside a supplied mask

[rmarkello]

The issue

Sometimes people don't want ROI x gene expression matrices! 😮 Sometimes, as in this recent paper by @illdopejake, they want all the samples inside (or near) a mask. It would be great to supply this option!

Proposed solution

A function called something like abagen.get_samples_in_mask() that returns a dictionary (?) where the keys are the donor IDs and the values are lists of sample IDs that fall within a user-specified distance of the mask (i.e., provide the ability to dilate the mask on-the-fly in the event that no samples are directly inside the mask). This would allow users to then use the relevant samples for whatever analyses they wanted to do!

I'm open to the function returning something else instead of the dictionary. It could, for example, return a list of well IDs (which are unique) for each sample, with no mention of the donor from which they were drawn. In this case a suite of helper functions where you could supply well IDs and get the expression data for the given IDs without having to specify the donor from which they originated would be super useful. (Behind the scenes this could simply iterate through the donors and match them to the specified well IDs).

def get_samples_in_mask(mask, tolerance=None):
    """
    Returns all expression samples that are within supplied `mask`

    Parameters
    ----------
    mask : niimg-like object
        A boolean mask in MNI space. True (or 1) where a voxel should be
        considered.
    tolerance : int, optional
        Distance (in mm) that a sample must be from `mask` for it to be
        retained. If not set only samples directly within the supplied mask
        will be retained. Default: None

    Returns
    -------
    samples : dict
        Where keys are donor IDs and values are lists of sample IDs for samples
        from that donor that fall within `mask`

    << OR >>

    samples : numpy.ndarray
        List of sample IDs that fall within `mask`
    """

    # relevant code here