album

album is a decentralized distribution platform for solutions to specific scientific problems. It works across platforms, tools, and data domains and is designed to address limitations in reproducibility of scientific data software solutions and workflows, particularly when interactivity is needed. album can be used to programmatically define how to interoperate between applications. It can ship versatile applications while tweaking them for a specific target audience or use case.

https://arxiv.org/abs/2110.00601

Installation

command line

graphical interface (experimental)

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

How can Album help you?

Click here for an introduction into why Album exists and where it can improve your experience with (scientific) software.

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

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. It's a single Python file!

Run solutions in a data workflow

Coming soon - we will share best practices for how to integrate Album into existing Data Version Control / workflow strategies.

Run solutions on the cluster / in the cloud

Coming soon - we will share best practices for running Album solutions in the cloud / on a cluster. Album catalogs already ship a Docker script for each solution.

Sharing solutions via catalogs

Package your solution

Coming soon - we are working on providing a single command for generating a single file executable that takes care of installing Conda, Album and a specific solution all at once.

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.


from album.runner.api import setup

The conda environment associated with this solution, linked below as a setup parameter.


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

The install method of this solution, linked below as a setup parameter.


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

The run method of this solution, linked below as a setup parameter.


def run():
    from album.runner.api import get_args
    print("Running this solution...")
    print("Hello ", str(get_args().name), ", nice to meet you!")

The pre_test method of this solution, linked below as a setup parameter.


def pre_test():
    return {'--name': 'Elsa'}

The test method of this solution, linked below as a setup parameter.


def test():
    from album.runner.api import get_args
    assert(get_args().name == 'Elsa')

The uninstall method of this solution, linked below as a setup parameter.


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

This enables album to parse the metadata of this solution.


setup(

The group/organization associated with the specific solution.

    group="album",

The name of the solution itself.

    name="template-python",

The version of the solution. Note that the -SNAPSHOT convention is used to indicate a version is not yet final.

    version="0.2.0",

The version of the album runner compatible with this solution code.

    album_api_version="0.5.1",

The title of the solution.

    title="Python template",

This is a short description of the specific solution.

    description="An album solution template for running Python code.",

These are the creators of the solution [list of strings]

    solution_creators=["Your name"],

This is a list of dictionaries that specify the citations associated with this solution file.

    cite=[{

text for the text representation of the citation (Harvard format)

        "text": "Your first citation text",

doi the DOI URL of the solution, if one is available

        "doi": "your first citation doi"

}],

This is a list of strings for tags that descript the specific solution.

    tags=["template", "java"],

The license of the solution (e.g. MIT, Apache, GPL, ...)

    license="UNLICENSE",

A link to the documentation for the solution.

    documentation="",

This is a list of cover images to be displayed for this solution in a catalog.

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

The arguments that can be (and may be required) to run the specific solution.

    args=[{

The name of the solution argument.

        "name": "name",

The type of the argument. Currently supported: string, file, directory.

        "type": "string",

The default value of the argument.

        "default": "Bugs Bunny",

The description of the argument.

        "description": "How do you want to be addressed?"

}],

The optional install function for the solution. When a solution is installed, the solution environment will be created and, if defined, the install method of the solution will be called in this environment.

    install=install,

The run function for the solution.

    run=run,

The method is called during `album test your-solution`. This function is evaluated before the `run` and `test` function are evaluated. The purpose of this function is to do things like prepare files for testing and generate the input arguments. It can return a map which will be used as input parameters for the `run` call.

    pre_test=pre_test,

The method is called during `album test your-solution`. It is called after `pre_test` and `run` and should fail or succeed based on what was stored during the `run` call and the given input parameters. You can make it fail by throwing an error.

    test=test,

The optional uninstall function for the solution. When a solution is uninstalled, this method will be called if defined - afterwards, the environment of the solution and all associated solution files will be deleted.

    uninstall=uninstall,

This is a dictionary that specifies the environment of the solution.

    dependencies={'environment_file': env_file}