Generate 2D patches

Short Description

The generateSinglePatch function facilitates the extraction of individual image patches centered around single-cell coordinates from a larger image, offering the flexibility to specify which markers or channels to include.

Function¶

`generateSinglePatch(spatialTablePath, imagePath, imageName='test_image', markerChannelMapPath=None, markers=['DNA1'], markerColumnName='marker', channelColumnName='channel', x_coordinate='X_centroid', y_coordinate='Y_centroid', cell_indicator='CellID', cropsize=16, image_fraction=1, random_state=1, verbose=True, projectDir=None)` ¶

Parameters:

Name	Type	Description	Default
`spatialTablePath`	`str`	Path to the single-cell spatial feature matrix, typically a CSV file.	required
`imagePath`	`str`	Path to the image file. Recognizes `.ome.tif` image file.	required
`imageName`	`str`	Base name for the output cropped sub-images.	`'test_image'`
`markerChannelMapPath`	`str`	Path to a `markers.csv` file that maps the channel number to the marker information. The `.csv` file should have columns named as specified by `markerColumnName` and `channelColumnName` with 1-based indexing for channels.	`None`
`markers`	`list`	A list of marker names indicating which markers to generate single patches for. These should correspond to the names used in the spatial feature matrix.	`['DNA1']`
`markerColumnName`	`str`	The name of the column in the `markers.csv` file that holds the marker names.	`'marker'`
`channelColumnName`	`str`	The name of the column in the `markers.csv` file that holds the channel numbers.	`'channel'`
`x_coordinate`	`str`	The column name in the spatial feature matrix that holds the X coordinates.	`'X_centroid'`
`y_coordinate`	`str`	The column name in the spatial feature matrix that holds the Y coordinates.	`'Y_centroid'`
`cell_indicator`	`str`	The column name in the spatial feature matrix that holds the unique cell identifiers.	`'CellID'`
`cropsize`	`int`	The size in pixels for the square crop from each axis centered on the cell coordinates.	`16`
`image_fraction`	`float`	Fraction of the cells to sample and crop, specified as a float between 0.0 and 1.0.	`1`
`random_state`	`int`	Seed for the random number generator used when sampling cells, if `image_fraction` is less than 1.0	`1`
`verbose`	`bool`	If True, prints detailed process information to the console.	`True`
`projectDir`	`string`	Path to the output directory where results will be saved. If not specified, the current working directory is used. The output will be placed in a subdirectory structure: `projectDir/SpatialAE/SinglePatch/`.	`None`

Returns:

Name	Type	Description
`Images`	`.tif`	The function saves the list of image patches centered on the coordinates specified in the spatial feature matrix to the specified path.

Example

import spatialae as sa
# Define paths and parameters

## specify meta_table with cell cooridinates information and image path
## set the projectDir for saving the cropped images

spatialTablePath="D://ResearchData/scimaptutorials/files/meta_data.csv"
imagePath="D://ResearchData/scimaptutorials/files/reactive_core.tif"
projectDir = "D://ResearchData/"

sa.generateSinglePatch(spatialTablePath,imagePath, projectDir = projectDir)

# Generate single patches for multiple markers, specifying a marker-channel map

markerChannelMapPath = "D://ResearchData/SpatialAE/data/markers.csv"
sa.generateSinglePatch(spatialTablePath, imagePath, markerChannelMapPath, markers = ["DNA1", "DNA2"], projectDir = projectDir)

Source code in spatialae/datasets/ppimage.py

def generateSinglePatch(
    spatialTablePath,
    imagePath,
    imageName="test_image",
    markerChannelMapPath=None,
    markers=["DNA1"],
    markerColumnName="marker",
    channelColumnName="channel",
    x_coordinate="X_centroid",
    y_coordinate="Y_centroid",
    cell_indicator="CellID",
    cropsize=16,
    image_fraction=1,
    random_state=1,
    verbose=True,
    projectDir=None,
):
    """

Parameters:
    spatialTablePath (str):
        Path to the single-cell spatial feature matrix, typically a CSV file.

    imagePath (str):
        Path to the image file. Recognizes `.ome.tif` image file.

    imageName (str):
        Base name for the output cropped sub-images.

    markerChannelMapPath (str):
        Path to a `markers.csv` file that maps the channel number to the marker information. The `.csv` file should have columns named as specified by `markerColumnName` and `channelColumnName` with 1-based indexing for channels.

    markers (list):
        A list of marker names indicating which markers to generate single patches for. These should correspond to the names used in the spatial feature matrix.

    markerColumnName (str):
        The name of the column in the `markers.csv` file that holds the marker names.

    channelColumnName (str):
        The name of the column in the `markers.csv` file that holds the channel numbers.

    x_coordinate (str, optional):
        The column name in the spatial feature matrix that holds the X coordinates.

    y_coordinate (str, optional):
        The column name in the spatial feature matrix that holds the Y coordinates.

    cell_indicator (str, optional):
        The column name in the spatial feature matrix that holds the unique cell identifiers.

    cropsize (int, optional):
        The size in pixels for the square crop from each axis centered on the cell coordinates.

    image_fraction (float, optional):
        Fraction of the cells to sample and crop, specified as a float between 0.0 and 1.0.

    random_state (int, optional):
        Seed for the random number generator used when sampling cells, if `image_fraction` is less than 1.0

    verbose (bool, optional):
        If True, prints detailed process information to the console.

    projectDir (string, optional):
        Path to the output directory where results will be saved. If not specified, the current working directory is used. The output will be placed in a subdirectory structure: `projectDir/SpatialAE/SinglePatch/`.


Returns:
    Images (.tif):
        The function saves the list of image patches centered on the coordinates specified in the spatial feature matrix to the specified path.


Example:
    ```python
    import spatialae as sa
    # Define paths and parameters

    ## specify meta_table with cell cooridinates information and image path
    ## set the projectDir for saving the cropped images

    spatialTablePath="D://ResearchData/scimaptutorials/files/meta_data.csv"
    imagePath="D://ResearchData/scimaptutorials/files/reactive_core.tif"
    projectDir = "D://ResearchData/"

    sa.generateSinglePatch(spatialTablePath,imagePath, projectDir = projectDir)

    # Generate single patches for multiple markers, specifying a marker-channel map

    markerChannelMapPath = "D://ResearchData/SpatialAE/data/markers.csv"
    sa.generateSinglePatch(spatialTablePath, imagePath, markerChannelMapPath, markers = ["DNA1", "DNA2"], projectDir = projectDir)

    ```

    """
    print("generateSinglePatch starting")
    # create folders if it does not exist
    if projectDir is None:
        projectDir = os.getcwd()
    # cropped_image_path = pathlib.Path(projectDir) + '/SpatialAE/SinglePatch/'
    # cropped_image_path = os.path.join(projectDir, '/SpatialAE/SinglePatch/')
    cropped_image_path = (
        pathlib.Path(projectDir).joinpath("SpatialAE").joinpath("SinglePatch")
    )
    if not os.path.exists(cropped_image_path):
        os.makedirs(cropped_image_path)

    if markerChannelMapPath is None:
        # default to crop DNA1
        marker_map = {"DNA1": 0}
        markers = [
            "DNA1",
        ]
    else:
        # read the markers.csv to map the marker and channels
        maper = pd.read_csv(pathlib.Path(markerChannelMapPath))
        ## check the markers input
        all_present = all(item in maper[markerColumnName].values for item in markers)
        if not all_present:
            raise ValueError(
                "The markers you provide is not in the markerChannelMapping file. Pls check."
            )

        chmamap = dict(zip(maper[markerColumnName], maper[channelColumnName]))
        # find the corresponding channel index
        markerChannels = [chmamap[key] for key in markers if key in chmamap]
        # convert markerChannels to zero indexing
        markerChannels = [x - 1 for x in markerChannels]
        # creat a dict of marker and corresponding marker channel index (zero indexing)
        marker_map = dict(zip(markers, markerChannels))

    # load the CSV to identify potential thumbnails
    metadata = pd.read_csv(pathlib.Path(spatialTablePath))
    if image_fraction < 1:
        metadata = metadata.sample(frac=image_fraction, random_state=random_state)
        metadata.reset_index(drop=True, inplace=True)
    locations = metadata[[x_coordinate, y_coordinate]]
    boundary = boundarylocator(locations, cropsize)

    # Run the function for each marker
    r_processMarker = lambda x: processMarker(
        marker=x,
        marker_map=marker_map,
        imagePath=imagePath,
        locations=locations,
        boundary=boundary,
        metadata=metadata,
        cropped_image_path=cropped_image_path,
        imagename=imageName,
        cell_indicator=cell_indicator,
        verbose=verbose,
    )
    final = list(map(r_processMarker, markers))

    # Finish Job
    if verbose is True:
        print(
            'subimages have been generated, head over to "'
            + str(projectDir)
            + 'SpatialAE/SinglePatch" to view results'
        )