Source code for allensdk.api.queries.reference_space_api

# Allen Institute Software License - This software license is the 2-clause BSD
# license plus a third clause that prohibits redistribution for commercial
# purposes without further permission.
#
# Copyright 2015-2017. Allen Institute. All rights reserved.
#
# Redistribution and use in source and binary forms, with or without
# modification, are permitted provided that the following conditions are met:
#
# 1. Redistributions of source code must retain the above copyright notice,
# this list of conditions and the following disclaimer.
#
# 2. Redistributions in binary form must reproduce the above copyright notice,
# this list of conditions and the following disclaimer in the documentation
# and/or other materials provided with the distribution.
#
# 3. Redistributions for commercial purposes are not permitted without the
# Allen Institute's written permission.
# For purposes of this license, commercial purposes is the incorporation of the
# Allen Institute's software into anything for which you will charge fees or
# other compensation. Contact terms@alleninstitute.org for commercial licensing
# opportunities.
#
# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
# POSSIBILITY OF SUCH DAMAGE.
#
from .rma_api import RmaApi
from allensdk.api.cache import cacheable, Cache
from allensdk.core.obj_utilities import read_obj
import allensdk.core.sitk_utilities as sitk_utilities
import numpy as np
import nrrd
import six


[docs]class ReferenceSpaceApi(RmaApi): AVERAGE_TEMPLATE = 'average_template' ARA_NISSL = 'ara_nissl' MOUSE_2011 = 'annotation/mouse_2011' DEVMOUSE_2012 = 'annotation/devmouse_2012' CCF_2015 = 'annotation/ccf_2015' CCF_2016 = 'annotation/ccf_2016' CCF_2017 = 'annotation/ccf_2017' CCF_VERSION_DEFAULT = CCF_2017 VOXEL_RESOLUTION_10_MICRONS = 10 VOXEL_RESOLUTION_25_MICRONS = 25 VOXEL_RESOLUTION_50_MICRONS = 50 VOXEL_RESOLUTION_100_MICRONS = 100 def __init__(self, base_uri=None): super(ReferenceSpaceApi, self).__init__(base_uri=base_uri)
[docs] @cacheable(strategy='create', reader=nrrd.read, pathfinder=Cache.pathfinder(file_name_position=3, path_keyword='file_name')) def download_annotation_volume(self, ccf_version, resolution, file_name): ''' Download the annotation volume at a particular resolution. Parameters ---------- ccf_version: string Which reference space version to download. Defaults to "annotation/ccf_2017" resolution: int Desired resolution to download in microns. Must be 10, 25, 50, or 100. file_name: string Where to save the annotation volume. Note: the parameters must be used as positional parameters, not keywords ''' if ccf_version is None: ccf_version = ReferenceSpaceApi.CCF_VERSION_DEFAULT self.download_volumetric_data(ccf_version, 'annotation_%d.nrrd' % resolution, save_file_path=file_name)
[docs] @cacheable(strategy='create', reader=sitk_utilities.read_ndarray_with_sitk, pathfinder=Cache.pathfinder(file_name_position=3, path_keyword='file_name')) def download_mouse_atlas_volume(self, age, volume_type, file_name): '''Download a reference volume (annotation, grid annotation, atlas volume) from the mouse brain atlas project Parameters ---------- age : str Specify a mouse age for which to download the reference volume volume_type : str Specify the type of volume to download file_name : str Specify the path to the downloaded volume ''' remote_file_name = '{}_{}.zip'.format(age, volume_type) url = '/'.join([ self.informatics_archive_endpoint, 'current-release', 'mouse_annotation', remote_file_name ]) self.retrieve_file_over_http(url, file_name, zipped=True)
[docs] @cacheable(strategy='create', reader=nrrd.read, pathfinder=Cache.pathfinder(file_name_position=2, path_keyword='file_name')) def download_template_volume(self, resolution, file_name): ''' Download the registration template volume at a particular resolution. Parameters ---------- resolution: int Desired resolution to download in microns. Must be 10, 25, 50, or 100. file_name: string Where to save the registration template volume. ''' self.download_volumetric_data(ReferenceSpaceApi.AVERAGE_TEMPLATE, 'average_template_%d.nrrd' % resolution, save_file_path=file_name)
[docs] @cacheable(strategy='create', reader=nrrd.read, pathfinder=Cache.pathfinder(file_name_position=4, path_keyword='file_name')) def download_structure_mask(self, structure_id, ccf_version, resolution, file_name): '''Download an indicator mask for a specific structure. Parameters ---------- structure_id : int Unique identifier for the annotated structure ccf_version : string Which reference space version to download. Defaults to "annotation/ccf_2017" resolution : int Desired resolution to download in microns. Must be 10, 25, 50, or 100. file_name : string Where to save the downloaded mask. ''' if ccf_version is None: ccf_version = ReferenceSpaceApi.CCF_VERSION_DEFAULT structure_mask_dir = 'structure_masks_{0}'.format(resolution) data_path = '{0}/{1}/{2}'.format(ccf_version, 'structure_masks', structure_mask_dir) remote_file_name = 'structure_{0}.nrrd'.format(structure_id) try: self.download_volumetric_data(data_path, remote_file_name, save_file_path=file_name) except Exception as e: self._file_download_log.error('''We weren't able to download a structure mask for structure {0}. You can instead build the mask locally using ReferenceSpace.many_structure_masks''') raise
[docs] @cacheable(strategy='create', reader=read_obj, pathfinder=Cache.pathfinder(file_name_position=3, path_keyword='file_name')) def download_structure_mesh(self, structure_id, ccf_version, file_name): '''Download a Wavefront obj file containing a triangulated 3d mesh built from an annotated structure. Parameters ---------- structure_id : int Unique identifier for the annotated structure ccf_version : string Which reference space version to download. Defaults to "annotation/ccf_2017" file_name : string Where to save the downloaded mask. ''' if ccf_version is None: ccf_version = ReferenceSpaceApi.CCF_VERSION_DEFAULT data_path = '{0}/{1}'.format(ccf_version, 'structure_meshes') remote_file_name = '{0}.obj'.format(structure_id) try: self.download_volumetric_data(data_path, remote_file_name, save_file_path=file_name) except Exception as e: self._file_download_log.error('unable to download a structure mesh for structure {0}.'.format(structure_id)) raise
[docs] def build_volumetric_data_download_url(self, data_path, file_name, voxel_resolution=None, release=None, coordinate_framework=None): '''Construct url to download 3D reference model in NRRD format. Parameters ---------- data_path : string 'average_template', 'ara_nissl', 'annotation/ccf_{year}', 'annotation/mouse_2011', or 'annotation/devmouse_2012' voxel_resolution : int 10, 25, 50 or 100 coordinate_framework : string 'mouse_ccf' (default) or 'mouse_annotation' Notes ----- See: `3-D Reference Models <http://help.brain-map.org/display/mouseconnectivity/API#API-3DReferenceModels>`_ for additional documentation. ''' if voxel_resolution is None: voxel_resolution = ReferenceSpaceApi.VOXEL_RESOLUTION_10_MICRONS if release is None: release = 'current-release' if coordinate_framework is None: coordinate_framework = 'mouse_ccf' url = ''.join([self.informatics_archive_endpoint, '/%s/%s/' % (release, coordinate_framework), data_path, '/', file_name]) return url
[docs] def download_volumetric_data(self, data_path, file_name, voxel_resolution=None, save_file_path=None, release=None, coordinate_framework=None): '''Download 3D reference model in NRRD format. Parameters ---------- data_path : string 'average_template', 'ara_nissl', 'annotation/ccf_{year}', 'annotation/mouse_2011', or 'annotation/devmouse_2012' file_name : string server-side file name. 'annotation_10.nrrd' for example. voxel_resolution : int 10, 25, 50 or 100 coordinate_framework : string 'mouse_ccf' (default) or 'mouse_annotation' Notes ----- See: `3-D Reference Models <http://help.brain-map.org/display/mouseconnectivity/API#API-3DReferenceModels>`_ for additional documentation. ''' url = self.build_volumetric_data_download_url(data_path, file_name, voxel_resolution, release, coordinate_framework) if save_file_path is None: save_file_path = file_name if save_file_path is None: save_file_path = 'volumetric_data.nrrd' self.retrieve_file_over_http(url, save_file_path)