How do I write album solutions?

First, install album by following these instructions.

Now, find a place for your new solution. Create a new folder - maybe called my-solutions - then clone one of our templates into it:

album clone album:template-python:0.1.0 --name SOLUTION_NAME --target my-solutions

Edit the file called solution.py located in my-solutions/SOLUTION_NAME. See the example solution on this site 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

Something does not work…

Our solution development guide might be useful. In any case please reach out to us and so we can remove barriers or fix issues.

I am happy with my first draft and I want others to use it!

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. Read this guide for details!

Writing album solutions

This is an exemplary album solution.

The only mandatory arguments of the setup method are group, name, version and album-api-version.


from album.runner.api import setup

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

env_file = """name: template-python
channels:
  - conda-forge
  - defaults
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 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 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 version of the album runner compatible with this solution code.
    album_api_version="0.3.1",
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}
)