allensdk.api package

Submodules

allensdk.api.api module

class allensdk.api.api.Api(api_base_url_string=None)[source]

Bases: object

cleanup_truncated_file(file_path)[source]

Helper for removing files.

Parameters:

file_path : string

Absolute path including the file name to remove.

construct_well_known_file_download_url(well_known_file_id)[source]

Join data api endpoint and id.

Parameters:

well_known_file_id : integer or string representing an integer

well known file id

Returns:

string

the well-known-file download url for the current api api server

See also

retrieve_file_over_http
Can be used to retrieve the file from the url.
default_api_url = 'http://api.brain-map.org'
do_query(url_builder_fn, json_traversal_fn, *args, **kwargs)[source]

Bundle an query url construction function with a corresponding response json traversal function.

Parameters:

url_builder_fn : function

A function that takes parameters and returns an rma url.

json_traversal_fn : function

A function that takes a json-parsed python data structure and returns data from it.

post : boolean, optional kwarg

True does an HTTP POST, False (default) does a GET

args : arguments

Arguments to be passed to the url builder function.

kwargs : keyword arguments

Keyword arguments to be passed to the rma builder function.

Returns:

any type

The data extracted from the json response.

Examples

A simple Api subclass example.

do_rma_query(rma_builder_fn, json_traversal_fn, *args, **kwargs)[source]

Bundle an RMA query url construction function with a corresponding response json traversal function.

..note:: Deprecated in AllenSDK 0.9.2
do_rma_query will be removed in AllenSDK 1.0, it is replaced by do_query because the latter is more general.
Parameters:

rma_builder_fn : function

A function that takes parameters and returns an rma url.

json_traversal_fn : function

A function that takes a json-parsed python data structure and returns data from it.

args : arguments

Arguments to be passed to the rma builder function.

kwargs : keyword arguments

Keyword arguments to be passed to the rma builder function.

Returns:

any type

The data extracted from the json response.

Examples

A simple Api subclass example.

download_url = 'http://download.alleninstitute.org'
json_msg_query(url, dataframe=False)[source]
Common case where the url is fully constructed
and the response data is stored in the ‘msg’ field.
Parameters:

url : string

Where to get the data in json form

dataframe : boolean

True converts to a pandas dataframe, False (default) doesn’t

Returns:

dict or DataFrame

returned data; type depends on dataframe option

load_api_schema()[source]

Download the RMA schema from the current RMA endpoint

Returns:

dict

the parsed json schema message

Notes

This information and other Allen Brain Atlas Data Portal Data Model documentation is also available as a Class Hierarchy and Class List.

read_data(parsed_json)[source]

Return the message data from the parsed query.

Parameters:

parsed_json : dict

A python structure corresponding to the JSON data returned from the API.

Notes

See API Response Formats - Response Envelope for additional documentation.

retrieve_file_over_http(url, file_path)[source]

Get a file from the data api and save it.

Parameters:

url : string

Url[R1]_ from which to get the file.

file_path : string

Absolute path including the file name to save.

See also

construct_well_known_file_download_url
Can be used to construct the url.

References

[R1]Allen Brain Atlas Data Portal: Downloading a WellKnownFile.
retrieve_parsed_json_over_http(url, post=False)[source]

Get the document and put it in a Python data structure

Parameters:

url : string

Full API query url.

post : boolean

True does an HTTP POST, False (default) encodes the URL and does a GET

Returns:

dict

Result document as parsed by the JSON library.

retrieve_xml_over_http(url)[source]

Get the document and put it in a Python data structure

Parameters:

url : string

Full API query url.

Returns:

string

Unparsed xml string.

set_api_urls(api_base_url_string)[source]

Set the internal RMA and well known file download endpoint urls based on a api server endpoint.

Parameters:

api_base_url_string : string

url of the api to point to

set_default_working_directory(working_directory)[source]

Set the working directory where files will be saved.

Parameters:

working_directory : string

the absolute path string of the working directory.

allensdk.api.cache module

class allensdk.api.cache.Cache(manifest=None, cache=True, version=None)[source]

Bases: object

build_manifest(file_name)[source]

Creation of default path speifications.

Parameters:

file_name : string

where to save it

static cache_csv()[source]
static cache_csv_dataframe()[source]
static cache_csv_json()[source]
static cache_json()[source]
static cache_json_dataframe()[source]
static cacher(fn, *args, **kwargs)[source]

make an rma query, save it and return the dataframe.

Parameters:

fn : function reference

makes the actual query using kwargs.

path : string

where to save the data

strategy : string or None, optional

‘create’ always generates the data, ‘file’ loads from disk, ‘lazy’ queries the server if no file exists, None generates the data and bypasses all caching behavior

pre : function

df|json->df|json, takes one data argument and returns filtered version, None for pass-through

post : function

df|json->?, takes one data argument and returns Object

reader : function, optional

path -> data, default NOP

writer : function, optional

path, data -> None, default NOP

kwargs : objects

passed through to the query function

Returns:

Object or None

data type depends on fn, reader and/or post methods.

static csv_writer(pth, gen)[source]
get_cache_path(file_name, manifest_key, *args)[source]

Helper method for accessing path specs from manifest keys.

Parameters:

file_name : string

manifest_key : string

args : ordered parameters

Returns:

string or None

path

static json_remove_keys(data, keys)[source]
static json_rename_columns(data, new_old_name_tuples=None)[source]

Convenience method to rename columns in a pandas dataframe.

Parameters:

data : dataframe

edited in place.

new_old_name_tuples : list of string tuples (new, old)

load_csv(path, rename=None, index=None)[source]

Read a csv file as a pandas dataframe.

Parameters:

rename : list of string tuples (new old), optional

columns to rename

index : string, optional

post-rename column to use as the row label.

load_json(path, rename=None, index=None)[source]

Read a json file as a pandas dataframe.

Parameters:

rename : list of string tuples (new old), optional

columns to rename

index : string, optional

post-rename column to use as the row label.

load_manifest(file_name, version=None)[source]

Read a keyed collection of path specifications.

Parameters:

file_name : string

path to the manifest file

Returns:

Manifest

manifest_dataframe()[source]

Convenience method to view manifest as a pandas dataframe.

static nocache_dataframe()[source]
static nocache_json()[source]
static pathfinder(file_name_position, secondary_file_name_position=None, path_keyword=None)[source]

helper method to find path argument in legacy methods written prior to the @cacheable decorator. Do not use for new @cacheable methods.

Parameters:

file_name_position : integer

zero indexed position in the decorated method args where file path may be found.

secondary_file_name_position : integer

zero indexed position in the decorated method args where tha file path may be found.

path_keyword : string

kwarg that may have the file path.

Notes

This method is only intended to provide backward-compatibility for some methods that otherwise do not follow the path conventions of the @cacheable decorator.

static remove_keys(data, keys=None)[source]

DataFrame version

static rename_columns(data, new_old_name_tuples=None)[source]

Convenience method to rename columns in a pandas dataframe.

Parameters:

data : dataframe

edited in place.

new_old_name_tuples : list of string tuples (new, old)

wrap(*args, **kwargs)[source]

make an rma query, save it and return the dataframe.

Parameters:

fn : function reference

makes the actual query using kwargs.

path : string

where to save the data

cache : boolean

True will make the query, False just loads from disk

save_as_json : boolean, optional

True (default) will save data as json, False as csv

return_dataframe : boolean, optional

True will cast the return value to a pandas dataframe, False (default) will not

index : string, optional

column to use as the pandas index

rename : list of string tuples, optional

(new, old) columns to rename

kwargs : objects

passed through to the query function

Returns:

dict or DataFrame

data type depends on return_dataframe option.

Notes

Column renaming happens after the file is reloaded for json

allensdk.api.cache.cacheable(strategy=None, pre=None, writer=None, reader=None, post=None, pathfinder=None)[source]

decorator for rma queries, save it and return the dataframe.

Parameters:

fn : function reference

makes the actual query using kwargs.

path : string

where to save the data

strategy : string or None, optional

‘create’ always gets the data from the source (server or generated), ‘file’ loads from disk, ‘lazy’ creates the data and saves to file if no file exists, None queries the server and bypasses all caching behavior

pre : function

df|json->df|json, takes one data argument and returns filtered version, None for pass-through

post : function

df|json->?, takes one data argument and returns Object

reader : function, optional

path -> data, default NOP

writer : function, optional

path, data -> None, default NOP

kwargs : objects

passed through to the query function

Returns:

dict or DataFrame

data type depends on dataframe option.

Notes

Column renaming happens after the file is reloaded for json

allensdk.api.cache.memoize(f)[source]

Memoization decorator for a function taking one or more arguments.

Module contents

Subclasses of allensdk.api.api.Api to implement specific queries to the Allen Brain Atlas Data Portal.