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

To use the upload / TUS-based file transfer features (CLI complete-upload-workflow and Python upload helpers), you will need tuspy and you can install it via:

pip install "abromics-library[upload]"

or by installing tuspy directly:

pip install tuspy>=0.2.4

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:

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

If you are already using the ABRomics web interface and its TSV template, you can reuse the same TSV for the library and CLI.
The only additional column you need to add for the Python/CLI workflow is:

• Project Name * – the project name as it exists in ABRomics (must match the name of the project you create or select.

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