DynamicAnnotationDB 5.13.1

Annotation Database pendant to the chunkedgraph

DynamicAnnotationDB

DynamicAnnotationDB (DADB) is an interface layer for creating, modifying and interacting with PostgreSQL databases used to store spatial point annotations and segmentation data defined by a chunkedgraph.

Features

• Create and manage PostgreSQL databases for annotation storage
• Handle spatial point annotations with PostGIS integration
• Support for segmentation data linked to annotations
• Dynamic schema generation and validation
• CRUD operations for annotations and segmentation data
• Reference annotation support with table linking
• Built-in versioning and tracking of modifications

Installation

You can install DynamicAnnotationDB using pip:

pip install DynamicAnnotationDB

Or install from source:

git clone https://github.com/CAVEconnectome/DynamicAnnotationDB
cd DynamicAnnotationDB
pip install -e .

Quick Start

Here's a basic example of using DynamicAnnotationDB:

from dynamicannotationdb import DynamicAnnotationInterface

# Connect to database
sql_uri = "postgresql://postgres:postgres@localhost:5432"
aligned_volume = "my_annotations"
interface = DynamicAnnotationInterface(sql_uri, aligned_volume)

# Create a new annotation table
table_name = "synapse_annotations"
interface.annotation.create_table(
    table_name=table_name,
    schema_type="synapse",
    description="Synapse annotations for dataset X",
    user_id="[e-mail]",
    voxel_resolution_x=4.0,
    voxel_resolution_y=4.0,
    voxel_resolution_z=40.0
)

# Insert annotations
annotations = [{
    "pre_pt": {"position": [121, 123, 1232]},
    "ctr_pt": {"position": [128, 143, 1232]},
    "post_pt": {"position": [235, 187, 1232]},
    "size": 1
}]

annotation_ids = interface.annotation.insert_annotations(table_name, annotations)

Key Components

The interface consists of several key components:

• Annotation Client: Handle CRUD operations for annotation data
• Segmentation Client: Manage segmentation data linked to annotations
• Schema Client: Generate and validate dynamic schemas
• Database Client: Core database operations and metadata management

Documentation

Full documentation is available at dynamicannotationdb.readthedocs.io.

Features in Detail

Dynamic Schema Support

DADB uses EMAnnotationSchemas to define table structures:

# Create a table with a specific schema
interface.annotation.create_table(
    table_name="my_table",
    schema_type="synapse",
    description="Description",
    user_id="[e-mail]",
    voxel_resolution_x=4.0,
    voxel_resolution_y=4.0,
    voxel_resolution_z=40.0
)

Segmentation Support

Link segmentation data to annotations:

# Create a segmentation table
seg_table = interface.segmentation.create_segmentation_table(
    table_name="my_table",
    schema_type="synapse", 
    segmentation_source="seg_source"
)

# Insert linked data
interface.segmentation.insert_linked_annotations(
    table_name="my_table",
    pcg_table_name="seg_source",
    annotations=[...]
)

Reference Tables

Create tables that reference other annotations:

# Create a reference table
interface.annotation.create_table(
    table_name="reference_table",
    schema_type="reference_type",
    description="Reference annotations",
    user_id="[e-mail]",
    voxel_resolution_x=4.0,
    voxel_resolution_y=4.0,
    voxel_resolution_z=40.0,
    table_metadata={
        "reference_table": "target_table",
        "track_target_id_updates": True
    }
)

Development

Requirements

• Python 3.7+
• PostgreSQL with PostGIS extension
• Docker (optional, for testing)

Testing

Run tests with pytest:

# Install test requirements
pip install -r test_requirements.txt

# Run tests (requires a PostgreSQL with PostGIS extension running)
pytest

# Run tests with a temporary Docker PostgreSQL instance (preferred local testing method)
pytest --docker=true

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

For support, please open an issue on the GitHub repository.