Skip to content

Application Programming Interface

Bai Shi edited this page Jun 10, 2020 · 6 revisions

Marmoset Brain Connectivity Atlas API Documentation

The application programming interface enables programmatic access to the data presented in the http://analysis.marmosetbrain.org interface. You can use this API to retrieve various kinds of datasets for the purpose of your research.

Please note that the data is distributed under the terms of the CC BY-SA 4.0 licence. When using the data, please acknowledge the following articles:

  • Majka P., Bai S., Bakola S., Bednarek S., Chan J.C., Jermakow N., Passarelli L., Reser D.H., Theodoni P., Worthy K.H., Wang X-J., Wójcik D.K., Mitra P.P. & Rosa M.G.P. (2020). Open access resource for cellular-resolution analyses of corticocortical connectivity in the marmoset monkey. Nature Communications. http://doi.org/10.1038/s41467-020-14858-0.

  • Majka, P., Chaplin, T. A., Yu, H.-H., Tolpygo, A., Mitra, P. P., Wójcik, D. K., & Rosa, M. G. P. (2016). Towards a comprehensive atlas of cortical connections in a primate brain: Mapping tracer injection studies of the common marmoset into a reference digital template. Journal of Comparative Neurology, 524(11), 2161–2181. http://doi.org/10.1002/cne.24023.

The current version of the API (1.0) offers the following functions:

  1. List Injections
  2. List Cases
  3. List Tracers
  4. List Areas
  5. List Areas (In flat structure)
  6. Retrograde connectivity pattern per area
  7. Retrograde connectivity pattern per injection
  8. Retrieve Cells
  9. Download tracer data as 3D volume

Lists all injections published on the http://marmosetbrain.org portal.

Properties

Property Data Type Description
id String Unique identifier of the injection in the system
case_id String Unique identifier of the case studied
display_name String Human-readable identifier of the case without unnecessary underlying technicalities
area String The target area of the injection
section String The section which the injection site is at
tracer String The tracer used in this injection
A-P Float Rostrocaudal stereotaxic coordinate (mm): Positive values are caudal to the interaural line. Negative values are rostral to the interaural line
M-L Float Mediolateral stereotaxic coordinate (mm): The values increase towards the lateral direction
D-V Float Dorsoventral stereotaxic coordinate (mm): Values increase towards the dorsal direction from the interaural line
url_to_highres_viewer String A URL link to the high-resolution viewer to investigate the cells and histology of the injection
url_to_flatmap_image String A URL link pointing to the Flatmap image of this injection
memo String Expert anatomist comment aimed at helping detailed interpretation the injection

Example link

http://www.marmosetbrain.org/api/v1/injections

Example response

{
    "status": "success",
    "timestamp": 1516081347,
    injections: [
        {
        memo: "DY injection in the caudal part of area 8b. Pattern of label is similar to FB injection suggesting no involvement of cortex caudal to 8b (area 6M).",
        url_to_highres_viewer: "http://www.marmosetbrain.org/goto/CJ74/r17b/13.145892/6.221157/3",
        M-L: "0.19",
        A-P: "13.28",
        url_to_flatmap_image: "http://flatmap.marmosetbrain.org/flatmap/CJ74/DY.png",
        id: "CJ74-DY",
        display_name: "CJ74-DY",
        section: "r17b",
        tracer: "DY",
        case_id: "CJ74",
        D-V: "14.98",
        area: "A8b"
        },    
        ...
    ],
    "total_injections": 141,
}

Lists all cases (animals).

Properties

Property Data Type Description
id String Unique identifier of the case in the system
sex String The sex of the animal studied
date_of_birth String The animal's date of birth
injection_date Float The date of injection performed
perfusion_date String The date of perfusion of the brain
survival_days Integer The number of days between surgery and brain is extracted
sectioning_plane String The sectioning plane of the brain.
weight Integer The weight of the animal at the time of surgery (in grams)
memo String Expert anatomist comment on the animal and the experiment

Example link

http://www.marmosetbrain.org/api/v1/cases

Example response

{
    status: "success",
    timestamp: 1516081172,
    cases: [
        {
        id: "CJ122",
        sex: "M"
        date_of_birth: "2008-07-23",
        injection_date: "2011-06-01",
        perfusion_date: "2011-06-15",
        survival_days: 14,
        sectioning_plane: "coronal",
        weight: 318,
        memo: "This animal had 4 injections in temporal cortex.",
        },    
        ...
    ],
    total_cases: 54
}

Lists retrograde fluorescent traces used in the injections.

Properties

Property Data Type Description
id String The unique id for the tracer used in the website
name String The human-readable name of the tracer
description String More verbose description for the tracer
color_code String The HEX color code for the tracer
comment String Any comment for this tracer

Example link

http://www.marmosetbrain.org/api/v1/tracers

Example response

{
    status: "success",
    timestamp: 1516861357,
    total_tracers: 6,
    tracers: [
        {
            comment: null,
            description: "Diamidino Yellow (DY)",
            name: "Diamidino yellow",
            id: "DY",
            color_code: "#F9EBAA"
        },
        ...
    ]
}    

Lists cortical areas in a nested dictionary format.

Properties

Property Data Type Description
id Integer The unique identifier of the cortical area
is_leaf Boolean Indicates if an area has any child areas (is_leaf is true) or if it has no child areas defined (is_leaf is false)
name String The name of the area
abbrev String The unique reference code in the system for the area
human_readable_abbrev String Human-readable abbreviation of the area. The code aligns with the Atlas name
color_code String The HEX color code for the area. The color is used throughout the website
nodes Object The child nodes of the area if it is not a leaf. Each item is keyed by the area's abbrev

Example link

http://www.marmosetbrain.org/api/v1/areas

Example response

{
    status: "success",
    timestamp: 1516083344,
    areas: {
        is_leaf: false,
        human_readable_abbrev: "ProCeph",
        color_code: "#00FF28",
        abbrev: "ProCeph",
        id: 102,
        name: "Prosencephalon",
        nodes: [
            {
                is_leaf: false,
                human_readable_abbrev: "TelCeph",
                color_code: "#0EFF00",
                abbrev: "TelCeph",
                nodes: [
                    ...
                ]
                id: 125,
                name: "Telencephalon",
            },
            ...
        ]
    }
}

Lists areas in flattened object format. The key will be the abbrev identifier of the area in the system. Only leaf nodes are listed. If a full list contains parent nodes is desired, please use http://www.marmosetbrain.org/api/v1/areas

Properties

Property Data Type Description
id Integer The unique identifier of the cortical area
name String The name of the area
abbrev String The unique reference code in the system for the area
human_readable_abbrev String Human-readable abbreviation of the area. The code aligns with the Atlas name
color_code String The HEX color code for the area. The color is used throughout the website

Example link

http://www.marmosetbrain.org/api/v1/areas/flat

Example response

{
    status: "success",
    timestamp: 1516083344,
    areas: {
        PGM: {
            abbrev: "PGM",
            color_code: "#DFD600",
            human_readable_abbrev: "PGM",
            id: 92,
            name: "Parietal area pg, medial part (cortex)"
        },         
        ...
    }
}

Returns retrograde connectivity pattern for cortical areas. The connectivity pattern is based on all injections into a specific area. For per injection connectivity profile, use the retrograde connectivity pattern per injection request. If an optional area parameter is provided, only the data related to that target area is returned. Otherwise, the full connectivity dataset is returned. The returned data is either JSON or CSV specified by format parameter. The column definition is contained in the _comments attribute in JSON or as the comment in CSV.

Parameters

Property Description
format The return format of the data, default to JSON. Possible values JSON, CSV
area Limit the result to interested target area, possible values:

Properties

Property Data Type Description
target String The target area of the connection
source String The source area of the injection
flne Float Fraction of extrinsic labelled neurons
log10_flne Float The strength of the connection expressed as a decimal logarithm of the fraction of extrinsic labelled neurons

Example Links

http://www.marmosetbrain.org/api/v1/flne_areas?area=V1 http://www.marmosetbrain.org/api/v1/flne_areas

Example response

{
    status: "success",
    timestamp: 1516079479,
    total_areas: 3248,
    headers: [
    "target",
    "source",
    "flne",
    "log10_flne"
    ],
    _comments: "# This file contains FLNe values for all areas # Columns description: # 1) Target: area receiving the projection, # 2) Source: area sending the projection, # 3) FLNe: fraction of extrinsic labelled neurons, # 4) log10_flne: log10(FLNe). # timestamp (UTC): 2018-01-16 05:11:19 # # This dataset has been downloaded from the # Marmoset Brain Connectivity Atlas # http://www.marmosetbrain.org/ # # The data is released under the terms of CC BY 4.0 license # (https://creativecommons.org/licenses/by/4.0/). # Please follow the citation policy: # http://www.marmosetbrain.org/ # ",
    areas: [
        [
        "OPt",
        "MST",
        0.177431097244,
        -0.7509702617427246
        ],
        ...
    ]
}

Lists the retrograde connectivity pattern for a selected injection.

Parameters

Property Description
injection_id (Required) Unique identifier of the injection in the system.
format Specify the return format of the result, possible values JSON, CSV

Properties

Property Data Type Description
case_id String Unique identifier of the case studied
tracer_id String Unique identifier of tracer used in the injection
target String The target area of the connection
source String The source area of the injection
cell_count Integer The actual number of labelled cells found in the source area
flne Float Fraction of extrinsic labelled neurons
log10_flne Float Decimal logarithm of the fraction of extrinsic labelled neurons

Example link

http://www.marmosetbrain.org/api/v1/flne_injections?injection_id=CJ173-DY

Example response

{
    status: "success",
    timestamp: 1516079479,
    total_areas: 27,
    headers: [
        "case_id",
        "tracer_id",
        "target",
        "source",
        "cell_count",
        "flne",
        "log10_flne"
    ],
    _comments: "# This file contains a FLNe values and cell count # for an injection into A4ab in the animal CJ173 # using the DY tracer # Columns description: # 1) Case_id: animal identifier, # 2) Tracer_id: tracer type, # 3) Target: area receiving the projection, # 4) Source: area sending the projection, # 5) Cell_count: the actual number of labelled # cells found in the source area, # 6) FLNe: fraction of extrinsic labelled neurons, # 7) log10_flne: log10(FLNe). # timestamp (UTC): 2018-01-16 06:00:04 # # This dataset has been downloaded from the # Marmoset Brain Connectivity Atlas # http://www.marmosetbrain.org/ # # The data is released under the terms of CC BY 4.0 license # (https://creativecommons.org/licenses/by/4.0/). # Please follow the citation policy: # http://www.marmosetbrain.org/ # ",
    areas: [
        [
        "CJ173",
        "DY",
        "A4ab",
        "A24d",
        1855,
        0.264320319179,
        -0.5778694499287389
        ],            
        ...
    ]
}

Returns detailed information on the individual labelled cells identified in a selected injection.

Parameters

Property Description
injection_id (Required) Unique identifier of the injection in the system
format The return format of the data, default to JSON. Supported formats including CSV, JSON

Properties

Property Data Type Description
case_id String Unique identifier of the case in the system
tracer_id String Unique identifier of the tracer type in the system
target String Area receiving the projection
source String Area sending the projection
M-L String Mediolateral stereotaxic coordinate (mm): The values increase towards the lateral direction
A-P String Rostrocaudal stereotaxic coordinate (mm): Positive values are caudal to the interaural line. Negative values are rostral to the interaural line
D-V String Dorsoventral stereotaxic coordinate (mm): Values increase towards the dorsal direction from the interaural line

Example link

http://www.marmosetbrain.org/api/v1/cells?injection_id=CJ173-DY

Example response

{
    status: "success",
    timestamp: 1516081417,
    cells: [
        [
        "CJ173",
        "DY",
        "A4ab",
        "DPal",
        "+3.07",
        "-8.21",
        "+15.49",
        -1
        ],    
        ...
    ],
    headers: [
        "case_id",
        "tracer_id",
        "target",
        "source",
        "M-L",
        "A-P",
        "D-V",
        "laminar position"
    ],        
    "total_cells": 7019,
}

Download zip packaged NIfTI format image of the tracer data.

Parameters

Property Description
injection_id (Required) Unique identifier of the injection in the system

Example link

http://www.marmosetbrain.org/api/v1/volume_map?injection_id=CJ173-DY

Response

A binary data response containing the zip file of the results in NIfTI format.