album

album turns scientific routines into executable building blocks. A solution packages a routine with its own environment, so it installs and runs with the same commands on Linux, Windows and macOS - whatever language or tool it uses. Catalogs share solutions within a lab, a community or with everyone. Because every solution is a tested, versioned building block, LLM agents can find and run solutions instead of inventing commands.

Album: executable building blocks for scientific imaging routines (arXiv:2110.00601)

Installation

command line

graphical interface

Who we are

Click here for background information about Album, including its home, Helmholtz Imaging.

Users

one-point access to topic specific, not tool specific software solutions
all solutions are installed in the same fashion across platforms (Linux, Windows, MacOS)
browse existing catalogs easily online
keep your data, run solutions locally
let an LLM agent find and run solutions from your catalogs

How can Album help you?

Click here for an introduction into why Album exists, what working with it looks like and how it works with LLM agents.

Creators

create reproducible, automated routines by wrapping existing code
share your solutions with others via online catalog
highlight specific software use cases
keep ownership of your solutions - catalogs can live anywhere in git repositories
draft solutions with an LLM and check them with album test

Run a solution from a catalog

Click here to learn how to run an existing solution from a catalog. It's a breeze!

Create a solution, wrap existing tools

Click here to read about how to wrap existing code into an Album solution - yourself or with an LLM. It's a single Python file!

Run solutions in a data workflow

Every solution is one command with its own environment, so workflow engines such as Snakemake or Nextflow run it like any other step - even when the steps need conflicting dependencies. To run one solution on many files, use album-distributed.

Solutions in data workflows

Run solutions on the cluster / in the cloud

Install Album on the shared filesystem of an HPC cluster and run solutions in SLURM jobs, or build a container image of a solution and run it on a cloud VM.

Clusters and the cloud

Sharing solutions via catalogs

Package your solution

When a solution is mature, make it last: build a container image, an installer that sets up Album and the solution with a double click, or publish each version with a DOI.

Container images · Installers · DOIs

Repositories / releases

List of catalogs

This is a curated list of public catalogs. Please contact us to add yours to the list.

Follow this guide to learn how to benefit from Album catalogs and access their solutions.

Example solution

An Album solution is a single Python file. It includes all metadata and entry points to installing and launching the solution via a joint setup method provided by the Album API.

The only mandatory arguments of the setup method are group, name, version and album_api_version. group, name, and version build the identifier of the solution.

Here is an example with (almost) all available solution setup parameters. It counts the words in a text file, and album test checks it: pre_test writes a sample text, run counts its words and test checks the count. Move the mouse over a line to see what it does. All setup parameters are described in the Album documentation.


from album.runner.api import setup

The environment of the solution in conda environment file syntax. Album creates it with micromamba when the solution is installed. Linked below in dependencies.


env_file = """
channels:
  - conda-forge
dependencies:
  - python=3.12
"""

Optional. Runs once in the solution environment after it is created, for example to download a model or build a tool. Linked below as install.


def install():
    print("Installing this solution...")

What the solution does. Runs in the solution environment on album run and reads its arguments with get_args(). Linked below as run.


def run():
    from album.runner.api import get_args

    args = get_args()
    words = len(args.input.read_text().split())
    args.output.write_text(str(words))
    print("Counted %s words in %s" % (words, args.input))

Runs first on album test: prepares test data and returns the arguments for run. Linked below as pre_test.


def pre_test():
    import tempfile
    from pathlib import Path

    folder = Path(tempfile.mkdtemp())
    text = folder.joinpath("text.txt")
    text.write_text("Album runs every solution in its own environment.")
    return {"--input": str(text), "--output": str(folder.joinpath("count.txt"))}

Runs on album test after run: checks the result and fails the test by raising an error. Linked below as test.


def test():
    from album.runner.api import get_args

    count = get_args().output.read_text()
    assert count == "8", "expected 8 words, got %s" % count

Optional. Runs on album uninstall, before the environment and the files of the solution are removed. Linked below as uninstall.


def uninstall():
    print("Uninstalling this solution...")

Album reads the metadata and the entry points of the solution from this call.


setup(

The group or organization the solution belongs to.

    group="my-group",

The name of the solution.

    name="count-words",

The version of the solution. Group, name and version identify it. A -SNAPSHOT suffix marks a version that is not final.

    version="0.1.0",

The version of album-solution-api the solution is written for. Album installs it into the solution environment.

    album_api_version="0.7.3",

The title of the solution.

    title="Count words",

A short description of what the solution does.

    description="Counts the words in a text file.",

The people who wrote this solution (a list of strings).

    solution_creators=["Your name"],

What to cite when the solution is used: the tools and algorithms it wraps. album info lists them, album run prints them at the end.

    cite=[{

The citation as text.

        "text": "Your citation text",

The DOI of the cited work, if there is one.

        "doi": "your.citation.doi"

}],

Keywords that help others find the solution.

    tags=["text", "example"],

The license of the solution, for example MIT, Apache or GPL.

    license="MIT",

Markdown files or links with the documentation of the solution. Files have to be in the solution folder.

    documentation=["documentation.md"],

Cover images shown for the solution on the catalog website.

    covers=[{
        "description": "Cover image.",
        "source": "cover.png"
    }],

The arguments of the solution. album info lists them, album run takes them as --name value.

    args=[{

The name of the argument: --input on the command line, get_args().input in the code.

        "name": "input",

str, int, float, bool, file or directory (string, integer and boolean work as well). A file argument arrives in the code as a path.

        "type": "file",

Album stops before run if a required argument is missing. For album test, pre_test can provide it.

        "required": True,

Shown by album info and in the form of the graphical interface.

        "description": "The text file."

    }, {
        "name": "output",
        "type": "file",
        "required": True,
        "description": "The file the number of words is written to."
    }],

The install method above. When a solution is installed, album creates its environment and then calls install in it.

    install=install,

The run method above.

    run=run,

Called by album test before run. Returns the arguments for run, here a test file and an output path.

    pre_test=pre_test,

Called by album test after run. Fails the test by raising an error, here when the count is not 8.

    test=test,

The uninstall method above. Album calls it before it removes the environment and the files of the solution.

    uninstall=uninstall,

The environment of the solution: an environment file (environment_file), a parent solution whose environment it reuses (parent), or files to download at install time (resource_file).

    dependencies={"environment_file": env_file}