Source code for allensdk.api.queries.tree_search_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 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 ..api import Api


class TreeSearchApi(Api):
    '''

    See `Searching a Specimen or Structure Tree <http://help.brain-map.org/display/api/Image-to-Image+Synchronization>`_
    for additional documentation.
    '''

    def __init__(self, base_uri=None):
        super(TreeSearchApi, self).__init__(base_uri)

    def get_tree(self,
                 kind,
                 db_id,
                 ancestors=None,
                 descendants=None):
        '''Fetch meta data for the specified structure or specimen.

        Parameters
        ----------
        kind : string
            'Structure' or 'Specimen'
        db_id : integer
            The id of the structure or specimen to search.
        ancestors : boolean, optional
            whether to include ancestors in the response (defaults to False)
        descendants : boolean, optional
            whether to include descendants in the response (defaults to False)

        Returns
        -------
        dict
            parsed json response data
        '''
        params = []
        url_params = ''

        if ancestors is True:
            params.append('ancestors=true')
        elif ancestors is False:
            params.append('ancestors=false')

        if descendants is True:
            params.append('descendants=true')
        elif descendants is False:
            params.append('descendants=false')

        if len(params) > 0:
            url_params = '?' + '&'.join(params)
        else:
            url_params = ''

        url = ''.join([self.tree_search_endpoint,
                       '/',
                       kind,
                       '/',
                       str(db_id),
                       '.json',
                       url_params])

        return self.json_msg_query(url)