Usage Examples¶

Basic Usage¶

Create Configuration for Specific Assay¶

from seqnado import Assay
from your_module import ThirdPartyToolsConfig

# Create configuration with assay-specific defaults
config = ThirdPartyToolsConfig.for_assay(Assay.ATAC)

# Export to dictionary
config_dict = config.model_dump(exclude_none=True)

Custom Tool Configuration¶

# Override specific tools during creation
config = ThirdPartyToolsConfig.for_assay(
    Assay.ATAC,
    bowtie2=Bowtie2(
        align=ToolConfig(threads=16, options="--very-fast")
    ),
    samtools=Samtools(
        sort=ToolConfig(threads=12, options="-@ {threads} -m 4G")
    )
)

Manual Configuration¶

# Create empty configuration and add tools manually
config = ThirdPartyToolsConfig()

# Add specific tools
config.bowtie2 = Bowtie2()
config.samtools = Samtools()
config.deeptools = Deeptools()

# Check which tools are configured
configured_tools = config.get_configured_tools()
print(f"Configured tools: {list(configured_tools.keys())}")

Advanced Usage¶

Option Filtering¶

from your_module import OptionsBase, ToolConfig

# Create options with exclusions
options = OptionsBase(
    value="--very-sensitive --threads 8 --fast",
    exclude={"--fast"}  # This option will be filtered out
)

# The filtered result will be: "--very-sensitive --threads 8"
print(options.option_string_filtered)

Dynamic Thread Configuration¶

# Use template strings for dynamic values
config = ThirdPartyToolsConfig.for_assay(
    Assay.RNA,
    samtools=Samtools(
        sort=ToolConfig(
            threads=16,
            options="-@ {threads} -m 2G"  # {threads} will be replaced
        )
    )
)

Serialization Options¶

# Standard dictionary export
config_dict = config.model_dump(exclude_none=True)

# Include descriptions as help fields
config_with_help = config.dump_with_descriptions()

# Export to YAML with comments (requires PyYAML)
yaml_output = config.dump_yaml_with_comments()

# Export to TOML with comments (requires tomli-w)  
toml_output = config.dump_toml_with_comments()

Integration Examples¶

With Configuration Files¶

import json
from pathlib import Path

# Save configuration
config = ThirdPartyToolsConfig.for_assay(Assay.CHIP)
config_path = Path("config.json")
config_path.write_text(config.model_dump_json(indent=2, exclude_none=True))

# Load configuration
config_data = json.loads(config_path.read_text())
loaded_config = ThirdPartyToolsConfig(**config_data)

With Environment-Specific Overrides¶

import os

def create_config_for_environment():
    # Base configuration
    config = ThirdPartyToolsConfig.for_assay(Assay.ATAC)

    # Override based on environment
    if os.getenv("HIGH_MEMORY") == "true":
        config.samtools.sort.options = "-@ {threads} -m 8G"

    if os.getenv("FAST_MODE") == "true":
        config.bowtie2.align.align.options = "--very-fast"

    return config

Validation and Error Handling¶

try:
    # This will raise validation error for invalid options
    config = ThirdPartyToolsConfig(
        bowtie2=Bowtie2(
            align=ToolConfig(
                threads=0,  # Invalid: less than minimum
                options="--invalid'quote"  # Invalid: bad quoting
            )
        )
    )
except ValueError as e:
    print(f"Configuration error: {e}")