abromics-library 1.1.0

Lightweight Python SDK for ABRomics API

ABRomics Lightweight Python SDK

A lightweight Python SDK for interacting with the ABRomics API, including resumable file uploads via TUS protocol.

Installation

From PyPI (Recommended)

pip install abromics-library

Upgrade to Latest Version

To upgrade an existing installation to the latest released version on PyPI:

pip install --upgrade abromics-library

Or, explicitly using Python:

python -m pip install --upgrade abromics-library

You can check your currently installed version with:

python -m pip show abromics-library

From Source

git clone https://gitlab.com/ifb-elixirfr/abromics/abromics-library.git
cd abromics-library
pip install -e .

Prerequisites

• Python 3.8+
• ABRomics backend running
• API key with complete_workflow_upload scope

Quick Start

1. Get Your API Key

1. Go to your ABRomics web interface
2. Navigate to the API Keys page
3. Create a new API key with scope complete_workflow_upload
4. Copy the API key (starts with abk_)

2. Set Environment Variables (Optional)

export ABROMICS_API_KEY="abk_your_api_key_here"
export ABROMICS_BASE_URL="http://localhost:8000"  # Your ABRomics backend URL

Usage

Command Line Interface (CLI)

The ABRomics CLI provides essential commands for managing projects and uploading data:

Command	Description
project create	Create a new project
check-data	List strain/sample combinations for a strain in a project (table: metadata & assembly status)
complete-upload-workflow	Complete workflow: TSV processing + file uploads

Create Project

# Create a new FASTQ project
abromics --api-key "abk_your_api_key_here" --base-url "https://analysis.abromics.fr" project create \
  --name "My FASTQ Project" \
  --template 1 \
  --description "Optional project description"

# Create a new FASTA project
abromics --api-key "abk_your_api_key_here" --base-url "https://analysis.abromics.fr" project create \
  --name "My FASTA Project" \
  --template 2 \
  --description "Optional project description"

Parameters:

• --name - Project name (required)
• --template - Template ID (required): 1 for FASTQ, 2 for FASTA
• --description - Project description (optional)

Check data

Check whether metadata (sample record) or assembly (FASTA file) exists for a strain in a project. Prints a table of all strain/sample combinations matching the given strain name; the same strain name can appear with different sample names (Sample Name).

abromics --api-key "abk_your_api_key_here" --base-url "https://analysis.abromics.fr" \
  check-data --strain-name "ST-FA-1128" --project-id 133

Example output when matches exist:

Strain ID   Sample name   Metadata   Assembly
----------  ------------  ---------  --------
ST-FA-1128  SRR1501128    present    present
ST-FA-1128  SRR1501129    present    absent

If no sample matches the strain name in the project, the command prints absent.

Parameters:

• --strain-name - Strain name (Strain Name / Strain ID) to look up; can match multiple samples in the project (required)
• --project-id - Project ID to scope the check (required)

Complete Workflow

# One command does everything: validates TSV, creates samples, uploads files
abromics complete-upload-workflow \
  --metadata-tsv "/path/to/samples_fastq_projects.tsv" \
  --data-dir "/path/to/sequence/files"

You can optionally export a machine-readable summary of sample creation and file uploads:

# JSON summary to stdout
abromics complete-upload-workflow \
  --metadata-tsv "/path/to/samples_fastq_projects.tsv" \
  --data-dir "/path/to/sequence/files" \
  --summary-format json \
  --summary-output -

# TSV summary to a file
abromics complete-upload-workflow \
  --metadata-tsv "/path/to/samples_fastq_projects.tsv" \
  --data-dir "/path/to/sequence/files" \
  --summary-format tsv \
  --summary-output "workflow_summary.tsv"

Options:

• --summary-format: table (default, human-readable), json, or tsv.
• --summary-output: path to write the summary file. If omitted it defaults to -, meaning the summary is printed to the terminal (standard output) where you launched the command.

What this command does:

• ✅ Auto-detects file types (FASTQ/FASTA)
• ✅ Creates samples from TSV metadata
• ✅ Uploads sequence files to samples
• ✅ Handles multiple projects automatically

Python Library

Basic Usage

from abromics import AbromicsClient

# Initialize client
client = AbromicsClient(
    api_key="abk_your_api_key_here",
    base_url="http://localhost:8000"
)

# Step 1: Create project (template 1 for FASTQ, 2 for FASTA)
project = client.projects.create(
    name="My FASTQ Project",
    template=1,
    description="Project for FASTQ sequencing data"
)

# Step 2: Complete workflow (auto-detects file types)
result = client.batch.process_tsv_and_upload(
    project_id=project.id,
    tsv_file="samples_metadata.tsv",
    files_directory="/path/to/sequence/files"
)

if result['success']:
    print("✅ Workflow completed successfully!")

Advanced Usage

# Individual operations
sample = client.samples.create(
    project_id=project.id,
    metadata={
        "Sample Name": "SAMPLE_001",
        "Strain Name": "ST-001",
        "Host species": "Homo sapiens",
        "Microorganism scientific name": "Escherichia coli",
        "Country": "France"
    }
)

# File upload with progress tracking
def progress_callback(message, current, total):
    print(f"{message}: {current}/{total}")

uploader = client.upload.create_uploader()
result = uploader.upload_file(
    file_path="/path/to/sequence.fastq.gz",
    metadata={
        "sample_id": str(sample.id),
        "file_type": "FASTQ_GZ",
        "type": "PAIRED_FORWARD"
    },
    progress_callback=progress_callback
)

TSV File Format

The TSV file should contain sample metadata with these columns:

Required Fields (marked with *)

• Sample Name * - Unique sample identifier (column Sample ID * is also accepted)
• Strain Name * - Unique strain identifier (column Strain ID * is also accepted)
• Host species * - Host species name
• Microorganism scientific name * - Scientific name of microorganism
• Country * - Country where sample was collected
• Sample type * - Type of sample
• Sample source * - Source of the sample
• Instrument model * - Sequencing instrument model
• Collected date * - Date when sample was collected
• Project Name * - Name of the project

File Type Fields (one of these)

• R1 fastq filename * + R2 fastq filename * - For FASTQ files
• Fasta filename * - For FASTA files

Optional Fields

• Region - Region where sample was collected
• Place - Specific place where sample was collected
• Travel countries - Countries visited before collection
• Accession number - Public database accession number
• Sample comment - Additional comments about the sample

Example TSV

Sample Name *	Strain Name *	R1 fastq filename *	R2 fastq filename *	Host species *	Microorganism scientific name *	Country *	Project Name *
SAMPLE_001	ST-001	sample_R1.fastq.gz	sample_R2.fastq.gz	Homo sapiens	Escherichia coli	France	My Project

Examples

CLI Examples

# Create a FASTQ project first
abromics --api-key "abk_your_api_key_here" --base-url "https://analysis.abromics.fr" project create \
  --name "My FASTQ Project" \
  --template 1 \
  --description "Project for FASTQ sequencing data"

# Or create a FASTA project
abromics --api-key "abk_your_api_key_here" --base-url "https://analysis.abromics.fr" project create \
  --name "My FASTA Project" \
  --template 2 \
  --description "Project for FASTA assembly data"

# Complete workflow (TSV + file uploads)
abromics complete-upload-workflow \
  --metadata-tsv "examples/samples_fastq_projects.tsv" \
  --data-dir "examples/sequence_files/"

Python Examples

# Run the example script
python examples/python_library_example.py

Configuration

Environment Variables

export ABROMICS_API_KEY="abk_your_api_key_here"        # Required
export ABROMICS_BASE_URL="http://localhost:8000"       # Optional

Priority Order

1. Command-line arguments (--api-key, --base-url)
2. Environment variables (ABROMICS_API_KEY, ABROMICS_BASE_URL)
3. Default values (base URL only)

API Reference

Client

client = AbromicsClient(api_key, base_url, timeout)

Projects

# Create FASTQ project
project = client.projects.create(
    name="My FASTQ Project",
    template=1,  # Template 1 for FASTQ, 2 for FASTA
    description="Optional description"
)

# Create FASTA project
project = client.projects.create(
    name="My FASTA Project",
    template=2,  # Template 1 for FASTQ, 2 for FASTA
    description="Optional description"
)

# List projects
projects = client.projects.list()

# Get project
project = client.projects.get(project_id)

Samples

# Create sample
sample = client.samples.create(project_id, metadata)

# List samples
samples = client.samples.list(project_id=1)

# Get sample
sample = client.samples.get(sample_id)

Batch Operations

# Complete workflow
result = client.batch.process_tsv_and_upload(
    project_id, tsv_file, files_directory
)

Troubleshooting

Common Issues

1. API Key Error: Make sure you have a valid API key with the correct scope
2. File Not Found: Check that TSV file and data directory paths are correct
3. Connection Error: Ensure the ABRomics backend is running on the specified URL
4. Permission Error: Verify your API key has the complete_workflow_upload scope
5. Mixed File Types: Don't mix FASTQ and FASTA files in the same directory

Getting Help

• Check the main library documentation above
• Verify your TSV file structure matches the expected format
• Ensure all required fields are present and non-empty
• Check that sequence files exist in the specified directory

Development

# Install in development mode
pip install -e .

# Run tests
pytest

# Run CLI
python -m abromics.cli --help

Publishing

For instructions on how to publish a new version to PyPI, see HowToPublish.md.

License

MIT License