Skip to main content

Nestly is a collection of functions designed to make running software with combinatorial choices of parameters easier.

Project description

nestly is a collection of functions designed to ease running software with combinatorial choices of parameters. It can easily do so for “cartesian products” of parameter choices, but can do much more– arbitrary “backwards-looking” dependencies can be used.

The vision here is that we take a fixed set of parameters and generate a single type of output for each defined combination, which can then be combined in some way for comparison and retrieval. We would like to set things up tidily with nested directories for output reflecting nested parameter choices.

The full documentation is available on ReadTheDocs.


The easiest way is with pip:

$ pip install nestly

Or, for the latest commit from master:

$ pip install git+git://

Python 2.7 is required.

Introductory example

Imagine you’d like to try all possible combinations of the following:




approximate, exhaustive


10, 100, 1000

input file

any file matching inputs/file*

For this we can write a little The guts are:

nest = Nest()

nest.add('strategy', ('exhaustive', 'approximate'))
nest.add('run_count', [10**i for i in xrange(3)])
nest.add('input_file', glob.glob(os.path.join(input_dir, 'file*')),

Running, you get a directory tree like:

├── approximate
│   ├── 10
│   │   ├── file1
│   │   │   └── control.json
│   │   ├── file2
│   │       └── control.json
│   ├── 100
│   │   ├── file1
│   │   │   └── control.json
│   │   ├── file2
│   │       └── control.json
│   └── 1000
│       ├── file1
│       │   └── control.json
│       ├── file2
│           └── control.json
└── exhaustive
    ├── 10
    │   ├── file1
    │   │   └── control.json
    │   ├── file2
    │       └── control.json
    ├── 100
    │   ├── file1
    │   │   └── control.json
    │   ├── file2
    │       └── control.json
    └── 1000
        ├── file1
        │   └── control.json
        ├── file2
            └── control.json

With the final control.json reading, for example:

    "input_file": "/Users/cmccoy/Development/nestly/examples/basic_nest/inputs/file3",
    "run_count": "1000",
    "strategy": "exhaustive"

The control files created then serve as inputs to nestrun for template substition, for example:

nestrun --save-cmd-file \
        --template='my_command -s {strategy} --count={run_count} {input_file}' \
        $(find runs -name "control.json")

This command runs my_command in all of the tip directories with the appropriate values for the parameters.

This was a “cartesian product” example. The “meal” example in the repository exhibits a setup with more complex dependencies between the nests.


nestrun takes a template and a list of control.json files with variables to substitute. By default, substitution is performed using the Python built-in str.format method. See the Python Formatter documentation for details on syntax, and examples/jsonrun/ for an example.

SCons integration

There is also a nestly.scons module to integrate nestly with the make replacement SCons.

Running the tests


python test

The mock library is required, but will be downloaded if missing.


McCoy CO, Gallagher A, Hoffman NG, Matsen FA (2013) nestly–a framework for running software with nested parameter choices and aggregating results. Bioinformatics 29: 387-388. pubmed


nestly source code is freely available under the MIT License.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

nestly-0.6.1.tar.gz (15.8 kB view hashes)

Uploaded Source

Built Distribution

nestly-0.6.1-py2.py3-none-any.whl (18.5 kB view hashes)

Uploaded Python 2 Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page