atldld.sync module

A collection of synchronizations related to working with Allen’s API.

Notes

See the module atldld.utils.py for lower level functions that are called within this module.

class DatasetDownloader(dataset_id: int, downsample_ref: int = 25, detection_xy: Tuple[float, float] = (0, 0), include_expression: bool = False, downsample_img: int = 0)[source]

Bases: object

Class to download an entire dataset.

Parameters:

  • dataset_id – Id of the section dataset. Used to determine the 3D matrix.

  • downsample_ref – Downsampling factor of the reference space. If set to 1 no downsampling takes place. The reference space shape will be divided by downsample_ref.

  • detection_xy – Represents the x and y coordinate in the image that will be used for determining the slice number in the reference space. p for coronal slices, r for sagittal slices.

  • include_expression – If True then the generator returns 5 objects where the last one is the expression image.

  • downsample_img – The downloaded image will have both the height and the width downsampled by 2 ** downsample_img.

metadata

Needs to be fetched with the fetch_metadata method. It contains two keys: “dataset” and “images”. The values are dictionaries storing metadata downloaded from the API.

fetch_metadata(force_redownload: bool = False) → None[source]

Fetch metadata of the dataset.

This function performs the following steps: 1. Get metadata for the entire dataset (e.g. affine_3d) 2. Get metadata for all images inside of the dataset (e.g. affine_2d)

Parameters:

force_redownload – If yes, force to redownload the metadata. Otherwise, if the metadata have been computed once, they are not computed again.

run() → Generator[Tuple[int, float, ndarray, Optional[ndarray], DisplacementField], None, None][source]

Download entire dataset.

For each image in the dataset, this function performs the following steps:

  1. Query the API to get the p, i, r coordinates of the detection_xy.

  2. One of the p, i, r will become the slice_coordinate. For coronal datasets it is the p and for sagittal ones it is the r. In other words we assume that the slice is parallel to one of the axes.

  3. Use get_parallel_transform to get a full mapping between the reference space and the image.

  4. Download the image (+ potentially the expression image)

  5. Yield result (order derived from section numbers - highest first)

Returns:

res_dict – Generator yielding consecutive four tuples of (image_id, constant_ref_coordinate, img, df). The constant_ref_coordinate is the dimension in the given axis in microns. The img is the raw gene expression image with dtype uint8. The df is the displacement field. Note that the sorting. If include_expression=True then last returned image is the processed expression image. That is the generator yield (image_id, p, img, df, img_expr).

Return type:

generator

exception DatasetNotFoundError[source]

Bases: Exception

Raised when there is no dataset for the given dataset ID.

get_parallel_transform(slice_coordinate: float, affine_2d: ndarray, affine_3d: ndarray, axis: str = 'coronal', downsample_ref: int = 1, downsample_img: int = 0) → DisplacementField[source]

Compute displacement field between the reference space and the image.

Parameters:

  • slice_coordinate – Value of the axis coordinate at which the image was sliced.

  • affine_2d – Matrix of shape (2, 3) representing a 2D affine transformation.

  • affine_3d – Matrix of shape (3, 4) representing a 3D affine transformation.

  • axis (str, {"coronal", "sagittal", "transverse"}) – Axis along which the slice was made.

  • downsample_ref – Downscaling of the reference space grid. If set to 1 no downsampling takes place. The higher the value the smaller the grid in the reference space and the faster the matrix multiplication.

  • downsample_img – The downloaded image will have both the height and the width downsampled by 2 ** downsample_img.

Returns:

Displacement field representing the transformation between the reference space and the image. Note that one can directly use it to register raw histological images to the reference space.

Return type:

DisplacementField

pir_to_xy(coords_ref: ndarray, affine_2d: ndarray, affine_3d: ndarray) → ndarray[source]

Transform coordinates from the reference space to the image space.

Parameters:

  • coords_ref – Array of shape (3, N) where the first axis contains the p, i and r.

  • affine_2d – Matrix of shape (2, 3) representing a 2D affine transformation. It can be retrieved from the section image metadata via the Allen Brain API. More specifically, it is stored under the tvs_** entries.

  • affine_3d – Matrix of shape (3, 4) representing a 3D affine transformation. It can be retrieved from the dataset metadata via the Allen Brain API. More specifically, it is stored under the trv_** entries.

Returns:

coords_img – Array of shape (3, N) where the first axis contains the x, y, section_number * section_thickness. Note that the section_number can be an arbitrary float that is most likely not equal to a section_number of any section image.

Return type:

np.ndarray

xy_to_pir(coords_img: ndarray, affine_2d: ndarray, affine_3d: ndarray) → ndarray[source]

Transform coordinates from the image space to the reference space.

Parameters:

  • coords_img – Array of shape (3, N) where the first axis contains the x, y and section_number * section_thickness. Note that both the section_number (image specific) and section_thickness (dataset specific) can be retrieved from the Allen Brain API.

  • affine_2d – Matrix of shape (2, 3) representing a 2D affine transformation. It can be retrieved from the section image metadata via the Allen Brain API. More specifically, it is stored under the tsv_** entries.

  • affine_3d – Matrix of shape (3, 4) representing a 3D affine transformation. It can be retrieved from the dataset metadata via the Allen Brain API. More specifically, it is stored under the tvr_** entries.

Returns:

coords_ref – Array of shape (3, N) where the first axis contains the p, i, r coordinates.

Return type:

np.ndarray

Source

source/api/atldld.sync.rst