Getting started with Eyened ORM

The Eyened ORM (Object-Relational Mapping) is a Python library that provides direct access to the Eyened database through a high-level, object-oriented interface. Built on SQLAlchemy 2.0, it allows you to interact with database entities as Python objects, making it easy to query, update, and manage data programmatically.

When to Use the ORM

The Eyened ORM provides direct, low-level access to database objects, which gives you maximum flexibility and control. However, for many common operations, the Eyened API may provide a more convenient interface with a higher level of abstraction.

Use the ORM when you need to:

• Perform bulk operations on large datasets
• Access fields or relationships not exposed through the API
• Write complex queries requiring SQLAlchemy’s full capabilities
• Build custom data processing pipelines or automated workflows
• Import/export data or work directly with database entities in Python scripts or Jupyter notebooks

Consider using the API instead when:

• You need standard CRUD operations
• You want built-in validation and business logic
• You’re building web applications or integrations

Note

Use of the ORM is considered advanced as it provides broader functionality and more direct interaction with database objects. Make sure you understand the database schema and relationships before making changes that could affect data integrity.

Setup

To install the ORM locally as a Python package:

git clone https://github.com/Eyened/eyened-platform.git
cd eyened-platform/orm
pip install -e .

Connecting to the database

To connect the ORM to a database, use the Database class. You can initialize it from environment variables, configuration files, or dictionaries. See ORM Configuration for detailed setup instructions and all available configuration options.

Working with database objects

Once connected, you can import and use database objects from the ORM. The Eyened database follows a hierarchical structure: Project → Patient → Study → Series → ImageInstance.

Basic usage

Start by importing the entity classes you need:

from eyened_orm import Project, Patient, Study, Series, ImageInstance

Finding objects

Use helper methods to find objects by common identifiers:

# Find a project by name
project = Project.by_name(session, 'My Project Name')

# Find a patient by identifier
patient = Patient.by_identifier(session, project_id, 'Patient_001')

Navigating relationships

Access related objects through relationship properties:

# Navigate from project down the hierarchy
project = Project.by_name(session, 'My Project Name')

for patient in project.Patients:
    print(f"Patient ID: {patient.PatientID}, Identifier: {patient.PatientIdentifier}")

    for study in patient.Studies:
        print(f"  Study date: {study.StudyDate}")

        for series in study.Series:
            print(f"    Series ID: {series.SeriesID}")

            for image in series.ImageInstances:
                print(f"      Image path: {image.path}")

Querying with SQLAlchemy

For more complex queries, use SQLAlchemy 2.0’s query API:

from sqlalchemy import select

# Query patients matching a pattern
patients = session.scalars(
    select(Patient).where(Patient.PatientIdentifier.like("Patient_%"))
).all()

# Query with joins and filters
from sqlalchemy import and_

studies = session.scalars(
    select(Study)
    .join(Patient)
    .where(and_(
        Patient.PatientIdentifier == "Patient_001",
        Study.StudyDate >= "2024-01-01"
    ))
).all()

Attribute naming

The properties on each ORM object match the database column names (in capitalized camel case), but they’re also exposed in Python style (snake_case):

# Both styles work
patient_id = patient.PatientID  # Database style
patient_id = patient.patient_id  # Python style

identifier = patient.PatientIdentifier  # Database style
identifier = patient.patient_identifier  # Python style

study_date = study.StudyDate  # Database style
study_date = study.study_date  # Python style

Tip

For detailed information about all available entities, their properties, and relationships, see the Database Entities documentation.

For more information on using SQLAlchemy queries, see the SQLAlchemy documentation.

Next Steps

Now that you’re set up and familiar with the basics, explore these resources to learn more:

• ORM Configuration: Learn about all available configuration options, including database settings, file paths, and other global settings.

• Database Entities: Get detailed information about all database entities, their relationships, and how to work with them, including segmentations, form annotations, attributes, tasks, and more.

• Command Line Utilities: Discover command-line tools for database mirroring, thumbnail updates, model execution, and other maintenance tasks.

• Development and Migrations: Learn about database migrations, schema changes, and development workflows.

• Utilities: Explore utility functions and helpers available in the ORM.