Snakemake storage plugin: irods

A plugin for handling input and output on iRODS.

Installation

Install this plugin by installing it with pip or mamba, e.g.:

pip install snakemake-storage-plugin-irods

Usage

Queries

Queries to this storage should have the following format:

Query type	Query	Description
any	irods://folder/myfile.txt	A file in a folder on the iRODS server.

As default provider

If you want all your input and output (which is not explicitly marked to come from another storage) to be written to and read from this storage, you can use it as a default provider via:

snakemake --default-storage-provider irods --default-storage-prefix ...

with ... being the prefix of a query under which you want to store all your results. You can also pass custom settings via command line arguments:

snakemake --default-storage-provider irods --default-storage-prefix ... \
    --storage-irods-max-requests-per-second ... \        --storage-irods-host ... \        --storage-irods-port ... \        --storage-irods-username ... \        --storage-irods-password ... \        --storage-irods-zone ... \        --storage-irods-home ... \        --storage-irods-authentication-scheme ...

Within the workflow

If you want to use this storage plugin only for specific items, you can register it inside of your workflow:

# register storage provider (not needed if no custom settings are to be defined here)
storage:
    provider="irods",
    # optionally add custom settings here if needed
    # alternatively they can be passed via command line arguments
    # starting with --storage-irods-..., see
    # snakemake --help
    # Maximum number of requests per second for this storage provider. If nothing is specified, the default implemented by the storage plugin is used.
    max_requests_per_second=...,
    # The host name of the iRODS server. Will also be read from ~/.irods/irods_environment.json if present.
    host=...,
    # The port of the iRODS server. Will also be read from ~/.irods/irods_environment.json if present.
    port=...,
    # The user name for the iRODS server. Will also be read from ~/.irods/irods_environment.json if present.
    username=...,
    # The password for the iRODS server. Will also be read from ~/.irods/irods_environment.json if present.
    password=...,
    # The zone for the iRODS server. Will also be read from ~/.irods/irods_environment.json if present.
    zone=...,
    # The home parameter for the iRODS server. Will also be read from ~/.irods/irods_environment.json if present.
    home=...,
    # The authentication scheme for the iRODS server. Will also be read from ~/.irods/irods_environment.json if present.
    authentication_scheme=...,

rule example:
    input:
        storage.irods(
            # define query to the storage backend here
            ...
        ),
    output:
        "example.txt"
    shell:
        "..."

Using multiple entities of the same storage plugin

In case you have to use this storage plugin multiple times, but with different settings (e.g. to connect to different storage servers), you can register it multiple times, each time providing a different tag:

# register shared settings
storage:
    provider="irods",
    # optionally add custom settings here if needed
    # alternatively they can be passed via command line arguments
    # starting with --storage-irods-..., see below
    # Maximum number of requests per second for this storage provider. If nothing is specified, the default implemented by the storage plugin is used.
    max_requests_per_second=...,
    # The host name of the iRODS server. Will also be read from ~/.irods/irods_environment.json if present.
    host=...,
    # The port of the iRODS server. Will also be read from ~/.irods/irods_environment.json if present.
    port=...,
    # The user name for the iRODS server. Will also be read from ~/.irods/irods_environment.json if present.
    username=...,
    # The password for the iRODS server. Will also be read from ~/.irods/irods_environment.json if present.
    password=...,
    # The zone for the iRODS server. Will also be read from ~/.irods/irods_environment.json if present.
    zone=...,
    # The home parameter for the iRODS server. Will also be read from ~/.irods/irods_environment.json if present.
    home=...,
    # The authentication scheme for the iRODS server. Will also be read from ~/.irods/irods_environment.json if present.
    authentication_scheme=...,

# register multiple tagged entities
storage foo:
    provider="irods",
    # optionally add custom settings here if needed
    # alternatively they can be passed via command line arguments
    # starting with --storage-irods-..., see below.
    # To only pass a setting to this tagged entity, prefix the given value with
    # the tag name, i.e. foo:max_requests_per_second=...
    # Maximum number of requests per second for this storage provider. If nothing is specified, the default implemented by the storage plugin is used.
    max_requests_per_second=...,
    # The host name of the iRODS server. Will also be read from ~/.irods/irods_environment.json if present.
    host=...,
    # The port of the iRODS server. Will also be read from ~/.irods/irods_environment.json if present.
    port=...,
    # The user name for the iRODS server. Will also be read from ~/.irods/irods_environment.json if present.
    username=...,
    # The password for the iRODS server. Will also be read from ~/.irods/irods_environment.json if present.
    password=...,
    # The zone for the iRODS server. Will also be read from ~/.irods/irods_environment.json if present.
    zone=...,
    # The home parameter for the iRODS server. Will also be read from ~/.irods/irods_environment.json if present.
    home=...,
    # The authentication scheme for the iRODS server. Will also be read from ~/.irods/irods_environment.json if present.
    authentication_scheme=...,

rule example:
    input:
        storage.foo(
            # define query to the storage backend here
            ...
        ),
    output:
        "example.txt"
    shell:
        "..."

Settings

The storage plugin has the following settings (which can be passed via command line, the workflow or environment variables, if provided in the respective columns):

CLI setting	Workflow setting	Envvar setting	Description	Default	Choices	Required	Type
--storage-irods-max-requests-per-second VALUE	max_requests_per_second		Maximum number of requests per second for this storage provider. If nothing is specified, the default implemented by the storage plugin is used.	None		✗	str
--storage-irods-host VALUE	host		The host name of the iRODS server. Will also be read from ~/.irods/irods_environment.json if present.	None		✓	str
--storage-irods-port VALUE	port		The port of the iRODS server. Will also be read from ~/.irods/irods_environment.json if present.	None		✓	str
--storage-irods-username VALUE	username	SNAKEMAKE_STORAGE_IRODS_USERNAME	The user name for the iRODS server. Will also be read from ~/.irods/irods_environment.json if present.	None		✓	str
--storage-irods-password VALUE	password	SNAKEMAKE_STORAGE_IRODS_PASSWORD	The password for the iRODS server. Will also be read from ~/.irods/irods_environment.json if present.	None		✓	str
--storage-irods-zone VALUE	zone		The zone for the iRODS server. Will also be read from ~/.irods/irods_environment.json if present.	None		✓	str
--storage-irods-home VALUE	home		The home parameter for the iRODS server. Will also be read from ~/.irods/irods_environment.json if present.	None		✓	str
--storage-irods-authentication-scheme VALUE	authentication_scheme		The authentication scheme for the iRODS server. Will also be read from ~/.irods/irods_environment.json if present.	'native'		✓	str