datalad.api.ukb_init(participant, records, force=False, bids=False, dataset=None)

Initialize an existing dataset to track a UKBiobank participant

A batch file for the ‘ukbfetch’ tool will be generated and placed into the dataset. By selecting the relevant data records, raw and/or preprocessed data will be tracked.

After initialization the dataset will contain at least three branches:

  • ‘incoming’: to track the pristine ZIP files downloaded from UKB
  • ‘incoming-native’: to track individual files (some extracted from ZIP files)
  • ‘incoming-bids’: to track individual files in a layout where file name conform to BIDS-conventions
  • main branch: based off of incoming-native or incoming-bids (if enabled) with potential manual modifications applied


Initialize a dataset in the current directory:

> ukb_init(participant="5874415", records=["20227_2_0", "20249_2_0"])

Initialize a dataset in the current directory in BIDS layout:

> ukb_init(participant="5874415", records=["20227_2_0"], bids=True)
  • participant (1-item sequence of str) – UKBiobank participant ID to use for this dataset (note: these encoded IDs are unique to each application/project).
  • records (non-empty sequence of str) – One or more data record identifiers.
  • force (bool, optional) – force (re-)initialization. [Default: False]
  • bids (bool, optional) – additionally maintain an incoming-bids branch with a BIDS-like organization. [Default: False]
  • dataset (Dataset or None, optional) – specify the dataset to perform the initialization on. [Default: None]
  • on_failure ({'ignore', 'continue', 'stop'}, optional) – behavior to perform on failure: ‘ignore’ any failure is reported, but does not cause an exception; ‘continue’ if any failure occurs an exception will be raised at the end, but processing other actions will continue for as long as possible; ‘stop’: processing will stop on first failure and an exception is raised. A failure is any result with status ‘impossible’ or ‘error’. Raised exception is an IncompleteResultsError that carries the result dictionaries of the failures in its failed attribute. [Default: ‘continue’]
  • result_filter (callable or None, optional) – if given, each to-be-returned status dictionary is passed to this callable, and is only returned if the callable’s return value does not evaluate to False or a ValueError exception is raised. If the given callable supports **kwargs it will additionally be passed the keyword arguments of the original API call. [Default: None]
  • result_renderer ({'default', 'json', 'json_pp', 'tailored'} or None, optional) – format of return value rendering on stdout. [Default: None]
  • result_xfm ({'datasets', 'successdatasets-or-none', 'paths', 'relpaths', 'metadata'} or callable or None, optional) – if given, each to-be-returned result status dictionary is passed to this callable, and its return value becomes the result instead. This is different from result_filter, as it can perform arbitrary transformation of the result value. This is mostly useful for top- level command invocations that need to provide the results in a particular format. Instead of a callable, a label for a pre-crafted result transformation can be given. [Default: None]
  • return_type ({'generator', 'list', 'item-or-list'}, optional) – return value behavior switch. If ‘item-or-list’ a single value is returned instead of a one-item return value list, or a list in case of multiple return values. None is return in case of an empty list. [Default: ‘list’]