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="[email protected]",
    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="[email protected]",
    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="[email protected]",
    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.