atldld.utils module

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

Notes

See the module atldld.sync for more elaborate functions that use these utils. Each function here is independent and performs a very specific lower level operation.

class CommonQueries[source]

Bases: object

A collection of very common queries.

static get_axis(dataset_id)[source]

Get axis for a given dataset.

Parameters:

dataset_id (int) – Id representing a section dataset.

Returns:

axis – Axis of the dataset images. {‘sagittal’, ‘coronal’}

Return type:

str

static get_reference_space(dataset_id)[source]

Get a reference space id for a given dataset.

Parameters:

dataset_id (int) – Id representing a section dataset.

Returns:

reference_space_id – Id representing the reference space.

Return type:

int

abi_get_request(url)[source]

Request url and check the response is valid.

Parameters:

url (str) – URL of the request.

Returns:

response – Response to the request.

Return type:

list or dict

Raises:

ValueError – If the status_code of the request is different than 200. (=Request failed)

get_2d(image_id, ref2inp=False, add_last=False)[source]

For a section image returns the 2D transformation matrix.

Parameters:

  • image_id (int) – Id of the section image.

  • ref2inp (bool, optional) – If True, then reference to input image transformation matrix. Otherwise input to reference.

  • add_last (bool) – If True then adding a row of [0, 0, 1] to be able to work in homogeneous coordinates.

Returns:

Transformation matrix of shape (2, 3) if add_last=False, else (3, 3). The last column represents the translation and the potentially 3rd row is just homogeneous coordinates.

Return type:

np.ndarray

Raises:

ValueError – When request not successful.

get_2d_bulk(dataset_id, ref2inp=False, add_last=False)[source]

Get 2D matrices for all images in a given dataset.

Notes

This implementation is significantly faster than simply running get_2d on each image of the dataset.

Parameters:

  • dataset_id – Id of the section dataset.

  • ref2inp (bool, optional) – If True, then reference to input image transformation matrix. Otherwise input to reference.

  • add_last (bool) – If True then adding a row of [0, 0, 1] to each of the 2D matrices in order to be able to work in homogeneous coordinates.

Returns:

res_dict – Keys represent image ids and values are tuples of (a, section_number) where a is the 2D matrix.

Return type:

dict

get_3d(dataset_id, ref2inp=False, add_last=False, return_meta=False)[source]

For a section dataset returns the 3D transformation matrix.

Parameters:

  • dataset_id (int) – Id of the section dataset.

  • ref2inp (bool, optional) –

    If True, then reference to input image transformation matrix.

    Otherwise input to reference.

  • add_last (bool) – If True then adding a row of [0, 0, 0, 1] to be able to work in homogeneous coordinates.

  • return_meta (bool) – If True then also the reference_space and the section thickness are returned.

Returns:

  • a (np.ndarray) – Transformation matrix of shape (3, 4) if add_last=False, else (4, 4). The last column represents the translation and the potentially 4th row is just homogeneous coordinates.

  • reference_space (int) – Reference space of the given section dataset. Only returned if return_meta is True.

  • section_thickness (float) – In microns. Only returned if return_meta is True.

Raises:

ValueError – When request not successful.

get_corners_in_ref_space(image_id: int, image_width: int, image_height: int) → ndarray[source]

Get the corner coordinates of a section image in the reference space.

Parameters:

  • image_id – The section image ID.

  • image_width – The width of the section image.

  • image_height – The height of the section image.

Returns:

ref_corners

Return type:

np.ndarray

Notes

The x and y coordinates in the API requests refer to the mathematical axes with the origin in the lower left corner of the plotted image. This is not the same as the array indices of image since the element image[0, 0] is mapped to the upper left corner, image[i_max, 0] to the lower left corner, etc.

Mathematical coordinates:

^ (0, 1)            (1, 1)
|
|
+------------------------->
  (0, 0)            (1, 0)

Corresponding elements of the image array:
^ image[0, 0]       image[0, j_max]
|
|
+------------------------->
  image[i_max, 0]   image[i_max, j_max]
get_experiment_list_from_gene(gene_name, axis='sagittal')[source]

Get Allen’s experiments IDs for a given gene expression name.

Parameters:

  • gene_name (str) – Gene Expression name.

  • axis ({"coronal", "sagittal"}) – Axis of the experiment.

Returns:

experiment_list – List of the experiment ID for a given gene expression and a given axis.

Return type:

list

get_image(image_id: int, folder: Optional[Union[str, pathlib.Path]] = None, expression: bool = False, downsample: int = 0) → np.ndarray | None[source]

Download an image from AIBS’ servers given an image ID.

All requested images are stored in the folder and then read.

Parameters:

  • image_id – Integer representing an id of the section image.

  • folder – Local folder where image saved. If None then automatically defaults to the configured cache directory.

  • expression – If True, retrieve the specified expression mask image. Otherwise, retrieve the specified image. See references for details.

  • downsample – Downsampling coefficient. Both the height and width are divided by 2 ** downsample.

Returns:

img – Downloaded/locally loaded image. The dtype is np.uint8.

Return type:

np.ndarray

Raises:

ValueError – If the image has a wrong format (determined by the dtype).

References

[1] AllenSDK API: ImageDownloadApi

pir_to_xy_API_single(p, i, r, dataset_id, reference_space=9)[source]

Convert an p, i, r in a reference space into a x, y in the image of the dataset.

Parameters:

  • p (float) – Coronal dimension (anterior -> posterior).

  • i (float) – Transversal dimension (superior -> inferior). The y (row) coordinate in coronal sections.

  • r (float) – Sagittal dimension (left -> right). The x (column) coordinate in coronal sections.

  • dataset_id (int) – Id of the section dataset.

  • reference_space (int, optional) – Reference space for which to perform the computations, most likely 9 is the one we always want.

Returns:

  • x (float) – The x coordinate (column) in the image with id closest_section_image_id.

  • y (float) – The y coordinate (row) in the section image with id closest_section_image_id.

  • section_number (float) – Section number as calculated by the 3D transformation. Since the dataset will never contain exactly this section one just uses the closest section image (see closest_section_imag_id).

  • closest_section_image_id (int) – Id of an image contained in the section dataset such that for the given p, i, r input is the closest existing approximation.

xy_to_pir_API_single(x: float, y: float, image_id: int) → Tuple[float, float, float][source]

Convert an x and y in a section image into a p, i, r in the reference space.

Notes

The reference space is always uniquely determined by the dataset the image comes from.

Parameters:

  • x – The x coordinate (column) in the section image with id image_id.

  • y – The y coordinate (row) in the section image with id image_id.

  • image_id – Integer representing an id of the section image with id image_id.

Returns:

  • p (float) – Coronal dimension (anterior -> posterior).

  • i (float) – Transversal dimension (superior -> inferior). The y (row) coordinate in coronal sections.

  • r (float) – Sagittal dimension (left -> right). The x (column) coordinate in coronal sections.

Source

source/api/atldld.utils.rst