Table Of Contents

Previous topic

Project Modules

Next topic

scripts Package

This Page

nestly Package

nestly Package

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

core Module

Core functions for building nests.

class nestly.core.Nest(control_name='control.json', indent=2, fail_on_clash=False, warn_on_clash=True, base_dict=None)[source]

Bases: object

Nests are used to build nested parameter selections, culminating in a directory structure representing choices made, and a JSON dictionary with all selections.

Build parameter combinations with Nest.add(), then create a nested directory structure with

  • control_name – Name JSON file to be created in each leaf
  • indent – Indentation level in json file
  • fail_on_clash – Error if a nest level attempts to overwrite a previous value
  • warn_on_clash – Print a warning if a nest level attempts ot overwrite a previous value
  • base_dict – Base dictionary to start all control dictionaries from (default: {})
add(name, nestable, create_dir=True, update=False, label_func=<type 'str'>, template_subs=False)[source]

Add a level to the nest

  • name (string) – Name of the level. Forms the key in the output dictionary.
  • nestable – Either an iterable object containing values, _or_ a function which takes a single argument (the control dictionary) and returns an iterable object containing values
  • create_dir (boolean) – Should a directory level be created for this nestable?
  • update (boolean) – Should the control dictionary be updated with the results of each value returned by the nestable? Only valid for dictionary results; useful for updating multiple values. At a minimum, a key-value pair corresponding to name must be returned.
  • label_func – Function to be called to convert each value to a directory label.
  • template_subs (boolean) – Should the strings in / returned by nestable be treated as templates? If true, str.format is called with the current values of the control dictionary.

Build a nested directory structure, starting in root

Parameters:root – Root directory for structure

Create an iterator of (directory, control_dict) tuples for all valid parameter choices in this Nest.

Parameters:root – Root directory
Return type:Generator of (directory, control_dictionary) tuples.
nestly.core.control_iter(base_dir, control_name='control.json')[source]

Generate the names of all control files under base_dir

nestly.core.nest_map(control_iter, map_fn)[source]

Apply map_fn to the directories defined by control_iter

For each control file in control_iter, map_fn is called with the directory and control file contents as arguments.


>>> list(nest_map(['run1/control.json', 'run2/control.json'],
...               lambda d, c: c['run_id']))
[1, 2]
  • control_iter – Iterable of paths to JSON control files
  • map_fn (function) – Function to run for each control file. It should accept two arguments: the directory of the control file and the json-decoded contents of the control file.

A generator of the results of applying map_fn to elements in control_iter


Return the basename, minus extension, of a path.

Parameters:path (string) – Path to file