albumaboutcatalogsdocs
sharing favourite solutions across tools and domains

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.

Albrecht, J.P.*, Schmidt, D.*, and Harrington, K., 2021. Album: a framework for scientific data processing with software solutions of heterogeneous tools. arXiv preprint arXiv:2110.00601.
https://arxiv.org/abs/2110.00601
pipPyPI versionalbumGitlab pipeline status album corerunnerGitlab pipeline status album runneruiGitlab pipeline status album UIwebsiteGitlab pipeline status album solutions websitegatsby-themeGitlab pipeline status album gatsby theme
What is album?
With album you can easily share your (scientific) solutions with others. Solutions are organized in catalogs.
How does that work?
album can be used via command line or via graphical interface (album-app). Catalogs can live in a git repo or a local folder, for example on a network drive. Adding a catalog will extend your local collection of solutions. Solutions are executed in their own versioned environments.
How do I install album?
album is not yet released officially, but you can install the most recent development version, assuming conda is installed:
conda env create -f https://gitlab.com/album-app/album/-/raw/main/album.yml
conda activate album
Got it, what next?
You can now install and run solutions - here is an example:
album install album:template-python:0.1.0-SNAPSHOT
album run album:template-python:0.1.0-SNAPSHOT --name "Edda"
Not very exciting, where do I find solutions matching my problem?
album solutions are collected in so called catalogs and can be hosted online or locally. Check out the list of catalogs we are aware of.
You can give this catalog a try:
album add-catalog https://gitlab.com/album-app/catalogs/capture-knowledge
album install ida-mdc:fiji-app:0.1.0
album run ida-mdc:fiji-app:0.1.0
How do I know what's in my local collection?
Start here:
album index
I want to write album solutions.
Find a place for your new solution and clone one of our templates into it:
mkdir my-solutions
album clone album:template-python:0.1.0-SNAPSHOT --name SOLUTION_NAME --target my-solutions
Edit the file called solution.py located in my-solutions/SOLUTION_NAME. See the example solution below for more details.
Got it, how do I run the solution locally?
album install my-solutions/SOLUTION_NAME
album run my-solutions/SOLUTION_NAME --parameter1 PARAMETER_VALUE
I'm happy with my first draft and I want to get feedback!
One can run the same album commands using URLs. In case you got everything in one file, upload the solution file somewhere and share the link, otherwise do the same with the zipped folder.
You can also create a catalog to collect multiple solutions. This will make it easier to share them with others and let them know about new versions.
album clone catalog --target-dir ./ --name CATALOG_NAME
Use album clone catalog-gatsby instead if you want gitlab to generate a catalog website for you. Now add the catalog to your local collection and deploy your solution into the catalog:
album add-catalog ./CATALOG_NAME
album deploy my-solutions/SOLUTION_NAME --catalog CATALOG_NAME
Upload the catalog i.e. to gitlab and share the URL with your colleagues.
And what do they do with the URL?
album add-catalog CATALOG_REPOSITORY_URL
.. and each time something changes in your catalog, they can propagate the changes into their local collection:
album update
album upgrade
Is there an alternative to using the command line?
Yes, there's a graphical interface for setting up album, installing, and running solutions. Please wait for the first official album release to let us catch up on documenting everything!
What's in a solution?

from album.runner import setup, get_args
from io import StringIO
The conda environment associated with this solution, linked below as a setup parameter.

env_file = StringIO("""name: template-python
channels:
  - conda-forge
  - defaults
dependencies:
  - python=3.6
""")
The install method of this solution, linked below as a setup parameter.

def install():
    print("Python template :: install")
The run method of this solution, linked below as a setup parameter.

def run():
    print("Python template :: run")
    print("Hello " + str(get_args().name) + ", nice to meet you!")
The close method of this solution, linked below as a setup parameter.

def close():
    print("Python template :: close")
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 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 authors of the solution [list of strings]
    authors=["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 the URL of the git repository that stores the code that this solution provides.
    git_repo="https://gitlab.com/album-app/catalogs/default",
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 minimum version of album required to run this solution.
    min_album_version="0.1.0",
The most recent version of album that was tested with this solution.
    tested_album_version="0.1.0",
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 to you want to be addressed?"
    }],
The install function for the solution. This can either be a variable that points to a function, or a lambda function. This function is evaluated in the album environment.
    install=install,
The run function for the solution. This can either be a variable that points to a function, or a lambda function. This function is evaluated within the solutions environment.
    run=run,
The close function for the solution. This can either be a variable that points to a function, or a lambda function. This function is evaluated in the solution environment when the solution finishes running.
    close=close,
This is a dictionary that specifies the environment of the solution.
    dependencies={'environment_file': env_file}
)