FAFBseg

https://fafbseg-py.readthedocs.io
Admin
FAFBseg is a Python library that provides a unified interface to access and work with multiple...
Tokens:180,680
Snippets:895
Trust Score:9.6
Update:5 months ago
Show doc for...
Tokens:
Raw
### Autoreview Edges with CloudVolume

Source: https://fafbseg-py.readthedocs.io/en/latest/source/generated/fafbseg.google.autoreview_edges.html

This example demonstrates how to set up a CloudVolume and then use fafbseg.autoreview_edges to automatically review edges for a given neuron. Ensure you have the necessary libraries installed and a valid CATMAID instance configured.

```python
from cloudvolume import CloudVolume
vol = CloudVolume('https://storage.googleapis.com/fafb-ffn1-20190805/segmentation',
                  cache=True,
                  progress=False)
_ = fafbseg.autoreview_edges(14401884, vol=vol, remote_instance=manual)
```

--------------------------------

### Install Development Version of fafbseg-py

Source: https://fafbseg-py.readthedocs.io/en/latest/source/install.html

Install the latest development version directly from the GitHub repository using pip.

```bash
pip3 install git+https://github.com/navis-org/fafbseg-py.git
```

--------------------------------

### Install Latest Stable fafbseg-py

Source: https://fafbseg-py.readthedocs.io/en/latest/source/install.html

Use this command to install the most recent stable release of the fafbseg-py library via pip.

```bash
pip3 install fafbseg
```

--------------------------------

### Setup pymaid and fafbseg

Source: https://fafbseg-py.readthedocs.io/en/latest/_modules/fafbseg/google/segmentation.html

Import necessary libraries for working with Catmaid and FAFBseg. These imports are typically needed at the beginning of your script.

```python
import pymaid # doctest: +SKIP
import fafbseg # doctest: +SKIP
```

--------------------------------

### Get CAVE Client

Source: https://fafbseg-py.readthedocs.io/en/latest/_modules/fafbseg/flywire/l2.html

Initializes or retrieves the CAVE client, specifying the dataset to be used for queries.

```python
# Get/Initialize the CAVE client
client = get_cave_client(dataset=dataset)

```

--------------------------------

### Attach Synapses to Skeleton

Source: https://fafbseg-py.readthedocs.io/en/latest/source/generated/fafbseg.flywire.synapses.get_synapses.html

This example demonstrates how to fetch synapses and attach them to a skeleton object. The synapses are mapped to the closest node on the skeleton.

```python
from fafbseg import flywire
sk = flywire.get_skeletons(720575940603231916)
_ = flywire.get_synapses(sk, attach=True)
print(sk.connectors.head())
```

--------------------------------

### Import Libraries for FAFBseg

Source: https://fafbseg-py.readthedocs.io/en/latest/source/tutorials/hemibrain_nblast.html

Import necessary libraries for working with FAFBseg, navis, and flybrains. Ensure navis (>=0.5.2) and flybrains (>=0.1.4) are installed.

```python
import navis
import flybrains

from fafbseg import flywire
```

--------------------------------

### Search annotations by root ID

Source: https://fafbseg-py.readthedocs.io/en/latest/source/generated/fafbseg.flywire.search_annotations.html

Find annotation information for a given root ID. This example demonstrates retrieving details for a specific neuron.

```python
an = flywire.search_annotations(720575940628857210)
Using materialization version 783.
an.iloc[0]

```

--------------------------------

### Get Adjacency Matrix

Source: https://fafbseg-py.readthedocs.io/en/latest/_modules/fafbseg/flywire/synapses.html

Fetches the adjacency matrix for given source and target root IDs. The matrix represents connections between neurons. Ensure you have the fafbseg library installed and imported.

```python
from fafbseg import flywire
adj = flywire.get_adjacency(sources=720575940631406673,
                            targets=720575940603231916)
```

--------------------------------

### Initialize Catmaid Instances

Source: https://fafbseg-py.readthedocs.io/en/latest/source/generated/fafbseg.google.find_fragments.html

Set up connections to both manual and automatic Catmaid instances using their respective server URLs and authentication tokens.

```python
manual = pymaid.CatmaidInstance('MANUAL_SERVER_URL', 'HTTP_USER', 'HTTP_PW', 'API_TOKEN')
auto = pymaid.CatmaidInstance('AUTO_SERVER_URL', 'HTTP_USER', 'HTTP_PW', 'API_TOKEN')
```

--------------------------------

### Set up CATMAID instances

Source: https://fafbseg-py.readthedocs.io/en/latest/source/generated/fafbseg.google.find_missed_branches.html

Establish connections to both manual and autoseg CATMAID instances using their respective URLs and authentication tokens.

```python
# Set up connections to manual and autoseg CATMAID
manual = pymaid.CatmaidInstance('URL', 'HTTP_USER', 'HTTP_PW', 'API_TOKEN') 
auto = pymaid.CatmaidInstance('URL', 'HTTP_USER', 'HTTP_PW', 'API_TOKEN')   
```

--------------------------------

### Get Connectivity Data using NeuronCriteria

Source: https://fafbseg-py.readthedocs.io/en/latest/_modules/fafbseg/flywire/annotations.html

Retrieves connectivity data by passing a NeuronCriteria object to the get_connectivity function. This example shows fetching connectivity for DA1_lPN hemibrain type neurons.

```python
cn = flywire.get_connectivity(NC(hemibrain_type='DA1_lPN'))
print(cn.head())
```

--------------------------------

### Setup pymaid Instances and Google Storage

Source: https://fafbseg-py.readthedocs.io/en/latest/_modules/fafbseg/google/segmentation.html

Before using segmentation data from Google Storage, set up your pymaid CatmaidInstance objects and point fafbseg to the correct Google Storage bucket.

```python
import pymaid
import fafbseg

manual = pymaid.CatmaidInstance('MANUAL_SERVER_URL', 'HTTP_USER',
                                'HTTP_PW', 'API_TOKEN')
auto = pymaid.CatmaidInstance('AUTO_SERVER_URL', 'HTTP_USER',
                              'HTTP_PW', 'API_TOKEN')


fafbseg.google.use_google_storage("https://storage.googleapis.com/fafb-ffn1-20190805/segmentation")
```

--------------------------------

### Get Synapse Counts for a Root ID

Source: https://fafbseg-py.readthedocs.io/en/latest/source/generated/fafbseg.flywire.synapses.get_synapse_counts.html

Fetches synapse counts for a single root ID. The output includes pre and post-synaptic counts. This example uses the default materialization and filtering.

```python
>>> from fafbseg import flywire
>>> n_syn = flywire.get_synapse_counts(720575940603231916)
Using materialization version 783.
>>> n_syn
                    pre  post
id
720575940603231916  4571   887

```

--------------------------------

### Initialize Catmaid Instances

Source: https://fafbseg-py.readthedocs.io/en/latest/_modules/fafbseg/google/segmentation.html

Create instances of the CatmaidInstance class, providing server URLs and authentication details. These instances are used to interact with specific Catmaid servers.

```python
manual = pymaid.CatmaidInstance('MANUAL_SERVER_URL', 'HTTP_USER', 'HTTP_PW', 'API_TOKEN') # doctest: +SKIP
auto = pymaid.CatmaidInstance('AUTO_SERVER_URL', 'HTTP_USER', 'HTTP_PW', 'API_TOKEN') # doctest: +SKIP
```

--------------------------------

### Connect to CATMAID and Map Skeleton IDs to FlyWire IDs

Source: https://fafbseg-py.readthedocs.io/en/latest/_modules/fafbseg/flywire/segmentation.html

Connects to a CATMAID instance and maps provided skeleton IDs to their corresponding FlyWire root IDs. Shows progress if enabled and allows specifying the target FlyWire dataset.

```python
>>> from fafbseg import flywire
>>> import pymaid
>>> # Connect to the VFB's CATMAID
>>> rm = pymaid.CatmaidInstance('https://fafb.catmaid.virtualflybrain.org/',
...                             project_id=1, api_token=None)
>>> roots = flywire.skid_to_id([6762, 2379517])
>>> roots
  skeleton_id          flywire_id  confidence
0        6762  720575940608544011        0.80
1     2379517  720575940617229632        0.42
```

--------------------------------

### Get Neuron Connectivity

Source: https://fafbseg-py.readthedocs.io/en/latest/_modules/fafbseg/flywire/synapses.html

Retrieve synaptic connections for a given root ID. This example shows how to fetch all connections associated with a specific neuron ID and display the first few rows of the resulting DataFrame.

```python
>>> from fafbseg import flywire
>>> edges = flywire.get_connectivity(720575940603231916)
Using materialization version 783.
>>> edges.head()
              pre                post  weight
0  720575940635945919  720575940603231916      83
1  720575940620541349  720575940603231916      58
2  720575940603231916  720575940629163931      50
3  720575940603231916  720575940635945919      46
4  720575940603231916  720575940646122804      42
```

--------------------------------

### Example Output DataFrame

Source: https://fafbseg-py.readthedocs.io/en/latest/source/generated/fafbseg.google.neuron_to_segments.html

This is an example of the DataFrame structure returned by the neuron_to_segments function, showing segment IDs and their overlap values.

```text
skeleton_id  id  3245
seg_id
10336680915   5     0
10336682132   0     1

```

--------------------------------

### Initialize CatmaidInstance

Source: https://fafbseg-py.readthedocs.io/en/latest/source/generated/fafbseg.google.find_autoseg_fragments.html

Initialize CatmaidInstance objects for manual and automatic segmentation servers. Ensure you replace placeholder URLs and credentials with your actual server details.

```python
manual = pymaid.CatmaidInstance('MANUAL_SERVER_URL', 'HTTP_USER',
                                 'HTTP_PW', 'API_TOKEN')
auto = pymaid.CatmaidInstance('AUTO_SERVER_URL', 'HTTP_USER',
                              'HTTP_PW', 'API_TOKEN')

```

--------------------------------

### Get Root IDs for Supervoxels

Source: https://fafbseg-py.readthedocs.io/en/latest/source/generated/fafbseg.flywire.supervoxels_to_roots.html

Use this function to find the root IDs corresponding to one or more supervoxel IDs. Specify a timestamp to query historical data or adjust the stop_layer to get IDs at different segmentation levels.

```python
from fafbseg import flywire
flywire.supervoxels_to_roots(78321855915861142)
```

--------------------------------

### GET /api/somas

Source: https://fafbseg-py.readthedocs.io/en/latest/_modules/fafbseg/flywire/annotations.html

Fetches nuclei segmentation for given neuron(s).

```APIDOC
## GET /api/somas

### Description
Fetches nuclei segmentation information for specified neuron root IDs.

### Method
GET

### Endpoint
/api/somas

### Parameters
#### Path Parameters
None

#### Query Parameters
- **x** (int | list of ints | NeuronList) - Optional - FlyWire root ID(s) or neurons for which to fetch soma infos. Use ``None`` to fetch complete list of annotated somas.
- **materialization** (str) - Optional - Controls how data is materialized. Defaults to 'auto'.
- **raise_missing** (bool) - Optional - If True, raises an error if requested somas are missing. Defaults to True.
- **split_positions** (bool) - Optional - If True, splits position information. Defaults to False.
- **dataset** (str) - Optional - FlyWire dataset to query ('public', 'production', 'sandbox'). Defaults to the globally set default dataset.

### Request Example
```bash
GET /api/somas?x=12345&dataset=production
```

### Response
#### Success Response (200)
- **somas** (list) - A list of soma objects, each containing segmentation and position information.

#### Response Example
```json
{
  "somas": [
    {
      "id": 12345,
      "position": [100, 200, 300],
      "radius": 10
    }
  ]
}
```
```

--------------------------------

### Download and Prepare Mesh for Skeletonization

Source: https://fafbseg-py.readthedocs.io/en/latest/_modules/fafbseg/flywire/skeletonize.html

Downloads a mesh from a CloudVolume dataset for a given ID and prepares it for skeletonization. Handles different CloudVolume backends and mesh loading strategies.

```python
if not navis.utils.is_mesh(x):
        vol = get_cloudvolume(dataset)

        # Make sure this is a valid integer
        id = np.int64(x)

        # Download the mesh
        try:
            old_parallel = vol.parallel
            vol.parallel = threads
            if vol.path.startswith("graphene"):
                mesh = vol.mesh.get(id, deduplicate_chunk_boundaries=False)[id]
            elif vol.path.startswith("precomputed"):
                lod_ = kwargs.pop("lod", 2)
                while lod_ >= 0:
                    try:
                        mesh = vol.mesh.get(id, lod=lod_)[id]
                        break
                    except cv.exceptions.MeshDecodeError:
                        lod_ -= 1
                    except BaseException:
                        raise
                if lod_ < 0:
                    raise ValueError(
                        f'Root ID {id} does not appear to exist in "{dataset}"'
                    )
        except BaseException:
            raise
        finally:
            vol.parallel = old_parallel
    else:
        mesh = x
        id = getattr(mesh, "segid", getattr(mesh, "id", 0))
```

--------------------------------

### Get Available Datastacks

Source: https://fafbseg-py.readthedocs.io/en/latest/_modules/fafbseg/flywire/utils.html

Retrieves a list of all available CAVE datastacks.

```APIDOC
## GET /api/cave/datastacks

### Description
Fetches a list of all datastacks that are currently available within the CAVE system.

### Method
GET

### Endpoint
/api/cave/datastacks

### Response
#### Success Response (200)
- **datastacks** (array of strings) - A list of available datastack names.

#### Response Example
```json
{
  "datastacks": ["flywire_fafb_production", "flywire_fafb_public", "some_other_stack"]
}
```
```

--------------------------------

### Skeletonize Neuron and Attach Synapses

Source: https://fafbseg-py.readthedocs.io/en/latest/_modules/fafbseg/flywire/synapses.html

This example demonstrates how to first obtain a neuron's skeleton using its root ID and then attach its associated synapses directly to the skeleton object. This is useful for visualizing or analyzing synaptic partners in context with the neuron's structure. The `attach=True` argument modifies the skeleton object in place.

```python
from fafbseg import flywire
sk = flywire.get_skeletons(720575940603231916)
_ = flywire.get_synapses(sk, attach=True)
Using materialization version 783.
print(sk.connectors.head())
```

--------------------------------

### Get Synapses

Source: https://fafbseg-py.readthedocs.io/en/latest/source/generated/fafbseg.flywire.synapses.get_synapses.html

Retrieves synapse information. This function is part of the fafbseg.flywire.synapses module.

```APIDOC
## GET /api/synapses

### Description
Retrieves synapse information from the FlyWire dataset.

### Method
GET

### Endpoint
/api/synapses

### Parameters
#### Query Parameters
- **ids** (list of int) - Required - A list of synapse IDs to retrieve.
- **fields** (list of str) - Optional - A list of fields to include in the response. If not specified, all fields are returned.

### Response
#### Success Response (200)
- **synapses** (list of dict) - A list of synapse objects, where each object contains the requested fields for a given synapse ID.

#### Response Example
```json
{
  "synapses": [
    {
      "id": 12345,
      "pre_synaptic_site": [100, 200, 300],
      "post_synaptic_site": [150, 250, 350],
      "type": "chemical"
    }
  ]
}
```
```

--------------------------------

### Visualize FlyWire Dotprops

Source: https://fafbseg-py.readthedocs.io/en/latest/source/tutorials/hemibrain_nblast.html

Visualize the fetched FlyWire dotprops, optionally overlaying the FLYWIRE brain for context. Adjustments are made for viewing angle and aspect ratio.

```python
# A quick visualization
# Note we're plotting the FLYWIRE brain on top of it
fig, ax = navis.plot2d(
    [fw_dps, flybrains.FLYWIRE], dps_scale_vec=1000, lw=1.5, figsize=(12, 12) 
)
ax.azim = ax.elev = -90
ax.set_box_aspect(None, zoom=1)
```

--------------------------------

### Get Materialization Versions

Source: https://fafbseg-py.readthedocs.io/en/latest/_modules/fafbseg/flywire/annotations.html

Fetches information on available materializations for a specified FlyWire dataset.

```APIDOC
## GET /api/materializations/versions

### Description
Fetch info on the available materializations.

### Method
GET

### Endpoint
/api/materializations/versions

### Parameters
#### Query Parameters
- **dataset** (string) - Optional - Against which FlyWire dataset to query. If ``None`` will fall back to the default dataset.

### Response
#### Success Response (200)
- **DataFrame** - Contains metadata for each materialization version, including version number, expiration timestamp, and creation timestamp.

#### Response Example
```json
{
  "version": [1, 2, 3],
  "expires_on": ["2023-01-01T10:00:00", "2023-01-02T11:00:00", "2023-01-03T12:00:00"],
  "time_stamp": ["2022-12-01T09:00:00", "2022-12-02T10:00:00", "2022-12-03T11:00:00"]
}
```
```

--------------------------------

### Get ChunkedGraph Secret

Source: https://fafbseg-py.readthedocs.io/en/latest/_modules/fafbseg/flywire/utils.html

Retrieves the local FlyWire chunkedgraph/CAVE secret token for a given domain.

```APIDOC
## GET /api/secrets/chunkedgraph

### Description
Retrieves the local FlyWire chunkedgraph/CAVE secret token.

### Method
GET

### Endpoint
/api/secrets/chunkedgraph

### Parameters
#### Query Parameters
- **domain** (str | list) - Optional - The domain(s) to get the secret for. Defaults to ('global.daf-apis.com', 'prod.flywire-daf.com').

### Response
#### Success Response (200)
- **token** (str) - The retrieved secret token.

#### Response Example
```json
{
  "token": "your_secret_token_here"
}
```
```

--------------------------------

### Generate and Open FlyWire URL

Source: https://fafbseg-py.readthedocs.io/en/latest/source/tutorials/neuroglancer.html

Use the `open=True` parameter in `flywire.encode_url()` to generate a URL and immediately open it in the browser. This is convenient for quickly visualizing selected segments.

```python
url = flywire.encode_url(
    segments=[720575940605214636, 720575940631693610], dataset="public", open=True
)
```

--------------------------------

### Import necessary libraries

Source: https://fafbseg-py.readthedocs.io/en/latest/source/tutorials/flywire_neurons.html

Import the navis library and the flywire module from fafbseg. These are the primary tools for interacting with FlyWire data.

```python
import navis
from fafbseg import flywire
```

--------------------------------

### Get Datastack Segmentation Source

Source: https://fafbseg-py.readthedocs.io/en/latest/_modules/fafbseg/flywire/utils.html

Retrieves the segmentation source information for a specified CAVE datastack.

```APIDOC
## GET /api/cave/datastacks/{datastack_name}/segmentation_source

### Description
Retrieves the segmentation source information for a given CAVE datastack.

### Method
GET

### Endpoint
/api/cave/datastacks/{datastack_name}/segmentation_source

### Parameters
#### Path Parameters
- **datastack_name** (string) - Required - The name of the CAVE datastack.

### Response
#### Success Response (200)
- **segmentation_source** (string) - The segmentation source for the specified datastack.

#### Response Example
```json
{
  "segmentation_source": "flywire_fafb_production"
}
```
```

--------------------------------

### Set up Google Cloud Storage

Source: https://fafbseg-py.readthedocs.io/en/latest/_modules/fafbseg/google/segmentation.html

Configure fafbseg to use segmentation data from a specified Google Cloud Storage bucket. This is necessary before performing operations that rely on this data.

```python
import fafbseg

fafbseg.google.use_google_storage("https://storage.googleapis.com/fafb-ffn1-20190805/segmentation")
```

--------------------------------

### Import fafbseg.flywire Module

Source: https://fafbseg-py.readthedocs.io/en/latest/source/generated/fafbseg.flywire.search_community_annotations.html

Import the necessary flywire module from the fafbseg library. This is a prerequisite for using any flywire functions.

```python
from fafbseg import flywire
```

--------------------------------

### Get Hierarchical Annotations

Source: https://fafbseg-py.readthedocs.io/en/latest/_sources/source/generated/fafbseg.flywire.get_hierarchical_annotations.rst.txt

Retrieves hierarchical annotations from FlyWire. This function is part of the fafbseg.flywire module.

```APIDOC
## GET /api/flywire/annotations/hierarchical

### Description
Retrieves hierarchical annotations from the FlyWire dataset. This endpoint is useful for exploring the structural organization of neural circuits.

### Method
GET

### Endpoint
/api/flywire/annotations/hierarchical

### Parameters
#### Query Parameters
- **root_id** (integer) - Required - The root ID of the segment for which to retrieve annotations.
- **level** (integer) - Optional - The maximum depth of the hierarchy to retrieve. Defaults to all levels if not specified.

### Request Example
GET /api/flywire/annotations/hierarchical?root_id=12345&level=3

### Response
#### Success Response (200)
- **annotations** (array) - A list of hierarchical annotations, where each annotation is an object containing segment IDs and their relationships.
  - **id** (integer) - The ID of the segment.
  - **children** (array) - A list of child segment IDs.

#### Response Example
{
  "annotations": [
    {
      "id": 12345,
      "children": [
        67890,
        11223
      ]
    },
    {
      "id": 67890,
      "children": [
        44556
      ]
    }
  ]
}
```

--------------------------------

### Get Information for a Specific CAVE Table

Source: https://fafbseg-py.readthedocs.io/en/latest/_modules/fafbseg/flywire/annotations.html

Retrieves metadata and information for a given CAVE annotation table.

```APIDOC
## GET /api/cave/tables/{table_name}/info

### Description
Gets information for a given CAVE table, including its metadata.

### Method
GET

### Endpoint
/api/cave/tables/{table_name}/info

### Parameters
#### Path Parameters
- **table_name** (string) - Required - The name of the CAVE table.

#### Query Parameters
- **dataset** (string) - Optional - Against which FlyWire dataset to query. Options: "public", "production", "sandbox". Defaults to the globally set default dataset.

### Response
#### Success Response (200)
- **info** (dict) - A dictionary containing the metadata for the specified CAVE table.

#### Response Example
```json
{
  "description": "Table description here",
  "voxel_resolution": [1.0, 1.0, 1.0],
  "created_at": "2023-01-01T10:00:00Z",
  "updated_at": "2023-01-01T10:00:00Z"
}
```
```

--------------------------------

### Import necessary libraries

Source: https://fafbseg-py.readthedocs.io/en/latest/source/generated/fafbseg.flywire.upload_annotations.html

Import the flywire module from fafbseg and the pandas library for data manipulation.

```python
from fafbseg import flywire
import pandas as pd
```

--------------------------------

### Fetch L2 Graphs for Multiple Root IDs

Source: https://fafbseg-py.readthedocs.io/en/latest/_modules/fafbseg/flywire/l2.html

Fetches L2 graphs for a list of FlyWire root IDs, displaying a progress bar. Returns a list of networkx.Graph objects.

```python
if navis.utils.is_iterable(root_ids):
    graphs = []
    for id in navis.config.tqdm(
        root_ids,
        desc="Fetching",
        disable=not progress or len(root_ids) == 1,
        leave=False,
    ):
        n = get_l2_graph(id, dataset=dataset)
        graphs.append(n)
    return graphs
```

--------------------------------

### GET /api/synapse_counts

Source: https://fafbseg-py.readthedocs.io/en/latest/_modules/fafbseg/flywire/synapses.html

Fetches synapse counts for given root IDs. Can provide counts broken down by neuropil.

```APIDOC
## GET /api/synapse_counts

### Description
Fetch synapse counts for given root IDs. If `by_neuropil` is True, the returned DataFrame will contain a breakdown by neuropil.

### Method
GET

### Endpoint
/api/synapse_counts

### Parameters
#### Query Parameters
- **x** (int | list of int | Neuron/List | NeuronCriteria) - Required - Either a FlyWire segment ID (i.e. root ID), a list thereof or a Neuron/List. For neurons, the `.id` is assumed to be the root ID.
- **by_neuropil** (bool) - Optional - If True, returned DataFrame will contain a break down by neuropil.
- **materialization** (int | str) - Optional - Which materialization to query: 'auto' (default), 'latest', 'live', or an integer materialization version.
- **filtered** (bool) - Optional - Whether to use the filtered synapse table. Defaults to True.
- **min_score** (int) - Optional - Minimum "cleft score".
- **batch_size** (int) - Optional - Number of IDs to query per batch. Defaults to 10.
- **dataset** (str) - Optional - Against which FlyWire dataset to query. Defaults to the default dataset.

### Request Example
```json
{
  "x": 720575940603231916,
  "by_neuropil": false,
  "materialization": "auto",
  "filtered": true,
  "min_score": null,
  "batch_size": 10,
  "dataset": null
}
```

### Response
#### Success Response (200)
- **id** (int) - Root ID.
- **pre** (int) - Number of presynaptic sites.
- **post** (int) - Number of postsynaptic sites.

#### Response Example
```json
{
  "id": 720575940603231916,
  "pre": 4571,
  "post": 887
}
```
```

--------------------------------

### Initialize GitHub Session with PAT

Source: https://fafbseg-py.readthedocs.io/en/latest/_modules/fafbseg/flywire/annotations.html

Initializes a requests Session for interacting with the GitHub API. If a GITHUB_PAT environment variable is set, it uses it for authentication.

```python
s = requests.Session()
if "GITHUB_PAT" in os.environ:
    s.auth = ("user", "pass")
    s.headers.update({"Authorization": f"Bearer {os.environ['GITHUB_PAT']}"})

return s
```

--------------------------------

### GET /flywire/skeletons

Source: https://fafbseg-py.readthedocs.io/en/latest/_modules/fafbseg/flywire/skeletonize.html

Retrieves precomputed neuron skeletons from the FlyWire dataset based on provided root IDs.

```APIDOC
## GET /flywire/skeletons

### Description
Retrieves precomputed neuron skeletons from the FlyWire dataset for one or more root IDs. Supports specifying the dataset version and handling of skeleton generation failures.

### Method
GET

### Endpoint
/flywire/skeletons

### Parameters
#### Query Parameters
- **root_id** (int | list of ints | NeuronCriteria) - Required - Root ID(s) of the FlyWire neuron(s) to skeletonize. Must be root IDs that existed at materialization 630 or 783.
- **omit_failures** (bool, optional) - Determines behavior when skeleton generation fails. If None (default), raises an exception. If True, skips offending neurons. If False, returns an empty TreeNeuron.
- **dataset** (630 | 783) - Required - Specifies which dataset to query (630 or 783).
- **progress** (bool, optional) - Whether to show a progress bar during fetching.
- **max_threads** (int, optional) - Number of parallel requests to make when fetching skeletons. Defaults to 1.

### Response
#### Success Response (200)
- **skeletons** (navis.NeuronList | navis.TreeNeurons) - A NeuronList or TreeNeuron object containing the requested skeletons.

#### Response Example
{
  "example": "{\n  type \t\t\t\t\t navis.TreeNeuron\n  name \t\t\t\t\t skeleton\n  id \t\t\t\t\t 720575940603231916\n  n_nodes \t\t\t\t\t 3588\n  n_connectors \t\t\t\t None\n  n_branches \t\t\t\t 586\n  n_leafs \t\t\t\t\t 645\n  cable_length \t\t\t\t 2050971.75\n  soma \t\t\t\t\t None\n  units \t\t\t\t\t 1 nanometer\n  dtype: object\n}"
}

### Error Handling
- Raises ValueError if the specified dataset is not supported or if `omit_failures` has an invalid value.
- Raises ValueError if any root IDs did not exist at the specified materialization and `omit_failures` is None.
- Returns an empty NeuronList if skeleton generation fails and `omit_failures` is True.
- Returns an empty TreeNeuron if skeleton generation fails and `omit_failures` is False.
```

--------------------------------

### fafbseg.flywire.neuron_to_segments

Source: https://fafbseg-py.readthedocs.io/en/latest/source/generated/fafbseg.flywire.neuron_to_segments.html

Get root IDs overlapping with a given neuron. Neurons must be in FlyWire (FAFB14.1) space.

```APIDOC
## fafbseg.flywire.neuron_to_segments

### Description
Get root IDs overlapping with a given neuron. Neurons must be in FlyWire (FAFB14.1) space.

### Method
GET (assumed, as it retrieves data)

### Endpoint
/api/flywire/neuron_to_segments

### Parameters
#### Query Parameters
- **x** (Neuron/List) - Required - Neurons for which to return root IDs. Neurons must be in FlyWire (FAFB14.1) space.
- **short** (bool) - Optional - If True will only return the top hit for each neuron (including a confidence score).
- **coordinates** (string: "voxel" or "nm") - Optional - Units the neuron(s) are in. “voxel” is assumed to be 4x4x40 (x/y/z) nanometers.
- **dataset** (string: "public", "production", "sandbox", or "flat_630") - Optional - Against which FlyWire dataset to query. If `None` will fall back to the default dataset.

### Response
#### Success Response (200)
- **overlap_matrix** (pandas.DataFrame) - DataFrame of root IDs (rows) and IDs (columns) with overlap in nodes as values.
- **summary** (pandas.DataFrame) - If `short=True`: DataFrame of top hits only.

#### Response Example (short=False)
```json
{
  "overlap_matrix": {
    "root_id": {
      "10336680915": [5, 0],
      "10336682132": [0, 1]
    }
  }
}
```

#### Response Example (short=True)
```json
{
  "summary": {
    "id": [12345, 412314],
    "match": [103366809155, 103366821325],
    "confidence": [0.87665, 0.65233]
  }
}
```
```

--------------------------------

### Fetch L2 Graph using fafbseg.flywire.get_l2_graph

Source: https://fafbseg-py.readthedocs.io/en/latest/source/generated/fafbseg.flywire.get_l2_graph.html

Use this function to fetch L2 graphs from FlyWire by providing root IDs. Ensure the fafbseg.flywire module is imported.

```python
>>> from fafbseg import flywire
>>> G = flywire.get_l2_graph(720575940614131061)

```

--------------------------------

### Search Annotations by Field

Source: https://fafbseg-py.readthedocs.io/en/latest/source/tutorials/flywire_annotations.html

Query annotations by specific fields, such as `cell_class`. This example fetches all gustatory sensory neurons.

```python
>>> # Fetch all gustatory sensory neurons
>>> gust = flywire.search_annotations("cell_class:gustatory")
>>> gust.head()
```

--------------------------------

### CAVE Client Initialization

Source: https://fafbseg-py.readthedocs.io/en/latest/_modules/fafbseg/flywire/utils.html

Initializes and retrieves a CAVE client. It handles dataset selection, authentication tokens, and checks for stale client instances, automatically refreshing if necessary.

```APIDOC
## GET /api/cave/client

### Description
Initializes and returns a CAVE client instance. This function supports specifying the dataset ('public' or 'production'), an authentication token, and options to control stale client checking and force re-initialization.

### Method
GET

### Endpoint
/api/cave/client

### Parameters
#### Query Parameters
- **dataset** (string) - Optional - Specifies the dataset to connect to, either 'public' or 'production'.
- **token** (string) - Optional - Your chunked graph secret token. If not provided, it attempts to read it via cloud-volume.
- **check_stale** (boolean) - Optional - If true, checks if the existing client has gone stale and refreshes it. Defaults to true.
- **force_new** (boolean) - Optional - If true, forces a re-initialization of the client. Defaults to false.

### Response
#### Success Response (200)
- **CAVEclient** (object) - An initialized CAVE client object.

#### Response Example
```json
{
  "client_instance": "<CAVEclient object>"
}
```
```

--------------------------------

### Get Adjacency Matrix

Source: https://fafbseg-py.readthedocs.io/en/latest/_modules/fafbseg/flywire/synapses.html

Fetches the adjacency matrix for neurons, with options for filtering, neuropil selection, and materialization versions.

```APIDOC
## GET /api/adjacency

### Description
Fetches adjacency matrix for neurons. This function can utilize optimized views of materialized tables for faster querying under specific conditions.

### Method
GET

### Endpoint
/api/adjacency

### Parameters
#### Query Parameters
- **sources** (int | list of int | Neuron/List | NeuronCriteria) - Required - Either FlyWire segment ID (i.e. root ID), a list thereof or a Neuron/List. For neurons, the ``.id`` is assumed to be the root ID.
- **targets** (int | list of int | Neuron/List | NeuronCriteria) - Optional - Either FlyWire segment ID (i.e. root ID), a list thereof or a Neuron/List. If ``None``, will assume ```targets = sources``.
- **square** (bool) - Optional - Whether to return a square matrix. Defaults to True.
- **neuropils** (bool | str | list of str) - Optional - Controls neuropil filtering. If True, returns neuropils (requires `square=False`). Can be a neuropil name or list to filter by, or prefixed with '~' to exclude.
- **filtered** (bool) - Optional - Whether to use the filtered synapse table. Defaults to True.
- **min_score** (int) - Optional - Minimum "cleft score" for filtering synapses. Defaults to None.
- **batch_size** (int) - Optional - Number of IDs to query per batch. Defaults to 1000.
- **materialization** (int | str) - Optional - Which materialization to query. Options: 'auto' (default), 'latest', 'live', or a specific integer version.
- **dataset** ("public" | "production" | "sandbox") - Optional - FlyWire dataset to query. Defaults to the configured default dataset.

### Request Example
```json
{
  "sources": [12345, 67890],
  "targets": [11111, 22222],
  "square": false,
  "neuropils": "AL_R",
  "min_score": 50,
  "materialization": "latest",
  "dataset": "production"
}
```

### Response
#### Success Response (200)
- **adjacency** (pd.DataFrame) - DataFrame representing the adjacency matrix or connectivity list.

#### Response Example
```json
{
  "adjacency": [
    {"source_id": 12345, "target_id": 11111, "score": 0.95},
    {"source_id": 12345, "target_id": 22222, "score": 0.88},
    {"source_id": 67890, "target_id": 11111, "score": 0.75}
  ]
}
```
```

--------------------------------

### Fetch Leaderboard Data

Source: https://fafbseg-py.readthedocs.io/en/latest/source/generated/fafbseg.flywire.get_leaderboard.html

Use this function to fetch leaderboard data. Set `by_day=True` to get a day-by-day breakdown of edits. Requires importing the `flywire` module.

```python
from fafbseg import flywire

# Fetch leaderboard with edits per day
hist = flywire.get_leaderboard(by_day=True)

# Plot user actions over time
hist.T.plot()
```

--------------------------------

### Get Transmitter Predictions

Source: https://fafbseg-py.readthedocs.io/en/latest/_modules/fafbseg/flywire/synapses.html

Fetches neurotransmitter predictions for a given neuron ID. Can return a single prediction or all predictions.

```APIDOC
## POST /api/get_transmitter_predictions

### Description
Fetches neurotransmitter predictions for a given neuron ID. If `single_pred` is True, returns only the most likely transmitter.

### Method
POST

### Endpoint
/api/get_transmitter_predictions

### Parameters
#### Query Parameters
- **id** (int) - Required - The segment ID of the neuron.
- **single_pred** (bool) - Optional - If True, returns only the most likely transmitter prediction.

### Request Example
```json
{
  "id": 720575940603231916,
  "single_pred": true
}
```

### Response
#### Success Response (200)
- **predictions** (dict) - A dictionary where keys are segment IDs and values are prediction objects containing 'transmitter' and 'probability'.

#### Response Example
```json
{
  "720575940603231916": {
    "transmitter": "acetylcholine",
    "probability": 0.9389612897479809
  }
}
```
```

--------------------------------

### Get Transmitter Predictions API

Source: https://fafbseg-py.readthedocs.io/en/latest/_modules/fafbseg/flywire/synapses.html

Fetches neurotransmitter predictions for neurons based on synapse data and confidence scores.

```APIDOC
## GET /api/flywire/transmitter_predictions

### Description
Fetches neurotransmitter predictions for neurons. This function calculates per-neuron predictions by averaging per-synapse predictions, weighted by the 'cleft score'.

### Method
GET

### Endpoint
/api/flywire/transmitter_predictions

### Parameters
#### Query Parameters
- **x** (int | list of int | Neuron/List | NeuronCriteria) - Required - Either a FlyWire segment ID (root ID), a list thereof, or a Neuron/List object.
- **single_pred** (bool) - Optional - If True, returns only the highest probability transmitter for each neuron.
- **weighted** (bool) - Optional - If True, weights predictions based on synapse confidence (cleft score).
- **materialization** (int | str) - Optional - Specifies the materialization version to query ('auto', 'latest', 'live', or an integer version).
- **filtered** (bool) - Optional - If True, uses a filtered synapse table that removes redundant and low-confidence synapses.
- **neuropils** (str | list of str) - Optional - Filters predictions to specified neuropils (e.g., 'AL_R') or excludes them (e.g., '~AL_R').
- **batch_size** (int) - Optional - Number of IDs to query per batch. Defaults to 10.
- **dataset** ("public" | "production" | "sandbox") - Optional - The FlyWire dataset to query against. Defaults to the configured default dataset.

### Request Example
```json
{
  "x": 720575940603231916,
  "single_pred": false,
  "weighted": true,
  "materialization": "auto",
  "filtered": true,
  "neuropils": null,
  "batch_size": 10,
  "dataset": null
}
```

### Response
#### Success Response (200)
- **pandas.DataFrame** - If `single_pred=False`: DataFrame with per-transmitter confidences for each query neuron.
- **dict** - If `single_pred=True`: Dictionary mapping neuron IDs to a named tuple of (top_transmitter, confidence).

#### Response Example (single_pred=False)
```json
{
  "root_id": 720575940603231916,
  "gaba": 0.011677,
  "acetylcholine": 0.938961,
  "glutamate": 0.017902,
  "octopamine": 0.012861
}
```

#### Response Example (single_pred=True)
```json
{
  "720575940603231916": {
    "top_transmitter": "acetylcholine",
    "confidence": 0.938961
  }
}
```
```

--------------------------------

### Get L2 Meshes

Source: https://fafbseg-py.readthedocs.io/en/latest/_modules/fafbseg/flywire/l2.html

Fetches L2 meshes for a given neuron root ID from a specified FlyWire dataset.

```APIDOC
## GET /api/neurons/{root_id}/l2_meshes

### Description
Fetches L2 meshes for a given neuron root ID.

### Method
GET

### Endpoint
/api/neurons/{root_id}/l2_meshes

### Parameters
#### Path Parameters
- **root_id** (int | str) - Required - The root ID of the neuron.

#### Query Parameters
- **threads** (int) - Optional - The number of threads to use for fetching meshes. Defaults to 10.
- **progress** (bool) - Optional - Whether to display a progress bar. Defaults to True.
- **dataset** (string) - Optional - The FlyWire dataset to query against (e.g., "public", "production", "sandbox", "flat_630"). Defaults to the globally set default dataset.

### Response
#### Success Response (200)
- **NeuronList** (navis.NeuronList) - A list of MeshNeuron objects representing the L2 meshes.

#### Response Example
```json
{
  "meshes": [
    {
      "id": "12345",
      "vertices": [[0,0,0], [1,0,0], ...],
      "faces": [[0,1,2], ...]
    }, 
    ...
  ]
}
```
```

--------------------------------

### Set Default FlyWire Dataset via Environment Variable

Source: https://fafbseg-py.readthedocs.io/en/latest/source/tutorials/flywire_segments.html

Configure the default FlyWire dataset by setting the `FLYWIRE_DEFAULT_DATASET` environment variable before starting the Python session. This setting persists across sessions if set permanently.

```bash
$ export FLYWIRE_DEFAULT_DATASET="public"
$ python
```

--------------------------------

### Get Per-Transmitter Predictions

Source: https://fafbseg-py.readthedocs.io/en/latest/source/generated/fafbseg.flywire.synapses.get_transmitter_predictions.html

Fetch all per-transmitter confidences for a given neuron ID. Predictions are weighted by synapse confidence.

```python
flywire.get_transmitter_predictions(720575940603231916)
```
Tokens:
Raw