Basic Examples

Basic examples for using the Nexus API

Basic Examples

This section provides practical examples to help you understand how to use the Nexus API effectively.

Basic Usage

python
from miura.api.nexus import Nexus
from miura.api.datasources import LocalDataSource

# Initialize the client
nexus = Nexus()

# List projects
projects = nexus.list_projects()
print(f"Found {len(projects)} projects")

# Get a specific project
project = nexus.get_project("my-project")

# List collections in the project
collections = project.list_collections()
print(f"Project has {len(collections)} collections")

# Get a specific collection
collection = project.get_collection("my-collection")

# List groups in the collection
groups = collection.get_groups()
print(f"Collection has groups: {groups['groups']}")

# Get a specific group
group = collection.get_group("raw")

# Browse items in the group
items = group.get_items()
print(f"Group has {len(items['data']['items'])} items")

# Close the client
nexus.close()

Upload Data

python
from miura.api.nexus import Nexus
from miura.api.datasources import LocalDataSource

# Initialize the client
nexus = Nexus()

# Create a data source
datasource = LocalDataSource("/path/to/local/data")

# Get or create a project
project = nexus.create_project("my-project")

# Create a collection
collection = project.create_collection(
    name="my-collection",
    schema={"type": "object", "properties": {"file_type": {"type": "string"}}},
    metadata={"description": "My data collection"}
)

# Upload data to the collection
result = collection.upload(datasource, group_name="raw")
print(f"Upload completed: {result['files_uploaded']} files uploaded")

# Close the client
nexus.close()

Download Data

python
from miura.api.nexus import Nexus

# Initialize the client
nexus = Nexus()

# Download entire collection
result = nexus.download("my-project/my-collection", "./downloads/")
print(f"Download completed: {result['files_downloaded']} files downloaded")

# Download specific group
result = nexus.download("my-project/my-collection/raw", "./downloads/")
print(f"Download completed: {result['files_downloaded']} files downloaded")

# Download specific subdirectory
result = nexus.download("my-project/my-collection/raw/data", "./downloads/")
print(f"Download completed: {result['files_downloaded']} files downloaded")

# Close the client
nexus.close()

Hierarchical Navigation

python
from miura.api.nexus import Nexus

# Initialize the client
nexus = Nexus()

# Navigate using hierarchical paths
project = nexus.get("my-project")  # Returns Project object
collection = nexus.get("my-project/my-collection")  # Returns Collection object
group = nexus.get("my-project/my-collection/raw")  # Returns Group object

# All objects support the same interface
project.print_info()
collection.print_info()
group.print_info()

# Close the client
nexus.close()

Complete Workflow Example

python
import miura

# 1. Authenticate
token = miura.auth.get_token("user@example.com", "password")

# 2. Create project
project = miura.nexus.create_project(
    name="CFD Research",
    description="Computational fluid dynamics research project",
    token=token
)

# 3. Define collection schema
schema = {
    "name": "CFD Schema",
    "path": "/",
    "children": [
        {
            "path": "/case_\\d{3}",
            "description": "CFD case folder",
            "isRequired": True,
            "occurrence": "any"
        }
    ]
}

# 4. Create collection
collection = project.create_collection("CFD Cases", schema)

# 5. Register data source
s3_ds = miura.data.S3DataSource("s3://cfd-data/cases")
collection.register_data_source(s3_ds)

# 6. Add processing hook
hook = miura.nexus.hooks.DatasetFractionSplitHook(
    "train_test_split",
    "case_*",
    [0.8, 0.2]
)
collection.register_before_plan_hook(hook)

# 7. Process data
loading_plan = collection.make_loading_plan()
loading_plan.apply()

# 8. Access processed data
url = collection.get_presigned_url("/case_001/results.vtk")
print(f"Download URL: {url}")

Integration with Scientific Workflows

python
import numpy as np
import pandas as pd

# Load data through Epico
url = collection.get_presigned_url("/case_001/results.csv")
df = pd.read_csv(url)

# Process data
results = df.groupby('parameter').mean()

# Save results back to collection
# (Implementation depends on upload capabilities)

Error Handling Example

python
try:
    project = miura.nexus.create_project("My Project", token=token)
except miura.exceptions.AuthenticationError:
    print("Authentication failed. Please check your credentials.")
except miura.exceptions.ValidationError as e:
    print(f"Validation error: {e}")
except miura.exceptions.ServiceError as e:
    print(f"Service error: {e}")

Configuration Example

python
import os

# Set configuration
os.environ["EPICO_BASE_URL"] = "https://my-dms.example.com"
os.environ["EPICO_TIMEOUT"] = "60"
os.environ["EPICO_DEBUG"] = "true"

Batch Operations

python
# Process multiple collections
collections = project.list_collections()
for collection in collections:
    loading_plan = collection.make_loading_plan()
    loading_plan.apply()

Custom Authentication

python
# Use custom authentication provider
token = miura.auth.get_token_with_provider(
    provider="keycloak",
    username="user@example.com",
    password="password",
    realm="dms"
)

Async Operations

python
import asyncio

async def process_collection(collection):
    loading_plan = await collection.make_loading_plan_async()
    await loading_plan.apply_async()

# Run async operations
collections = project.list_collections()
tasks = [process_collection(c) for c in collections]
await asyncio.gather(*tasks)
These examples provide a foundation for working with the Nexus API. Start with the basic examples and gradually work your way up to more complex integrations.

© 2025