Create a Derivative

Create a Derivative#

An important functionality of ancpBIDS is to create and write derivatives.

In the examples in this page, we’ll create a derivative that extracts basic MEG header information from raw files and stores it as JSON sidecar files.

Create a Derivative in the Memory Graph#

The function create_derivative registers a derivative within the in-memory graph. The given name (e.g., “Meg_QC”) will be the derivatives’ folder name. You can also add as well as a description to the derivatives folder (e.g., dataset_description). This step only defines what will be written later.

  DERIVATIVE_NAME = "Meg_QC"
  derivative = dataset.create_derivative(name= DERIVATIVE_NAME)
  derivative.dataset_description.GeneratedBy.Name = "MEG header extraction"

Create a Folder#

The function create_folder creates new folders and subfolders, for example pipelines (e.g., “calculation/”).

    PIPELINE_FOLDER = "calculation" 
    calculation_folder = derivative.create_folder(name = PIPELINE_FOLDER)

You can also use the function create_folder to create subject folder specifying the schema.

for sid in subjects:

  subject_folder = calculation_folder.create_folder(
            type_=schema.Subject,
            name="sub-" + sid
  )

Artifacts#

ancpBIDS works with artifacts, which are intrnal objects that represents a BIDS file. It is not the file itself, but a representation of it that carries structured BIDS information. For example, when we create a derivative sidecar JSON file with metadata from a raw file, we need to create an artifact with the query information from the BIDS raw dataset.

First: we query the information we want#

SCOPE = "raw"
SUFFIX = "meg"
EXTENSIONS = [".fif", ".fif.gz"]


raw_artifacts = list(dataset.query(
    subj=sid,
    suffix=SUFFIX,
    scope=SCOPE,
    extension=EXTENSIONS,
    return_type="object",
))

print(raw_artifacts)

#Output:
# [{'name': 'sub-009_ses-1_task-deduction_run[...]', 'extension': '.fif', 'suffix': 'meg'}, {'name': 'sub-009_ses-1_task-induction_run[...]', 'extension': '.fif', 'suffix': 'meg'}]

very old#

write_derivative() saves the provided derivative folder to the dataset. Note that a ‘derivatives’ folder will be created if not present. Optionally, you may also use the DatasetOptions class to set your preference in the handling of writing a derivative to your file system.

from ancpbids import write_derivative

target_dir = '/path/to/your/target/directory'
write_derivative(dataset, target_dir)

Important

TODO: provide a more elaborative example using write_derivative() (deprecated) and artifact.write() (preferred)

–>

Contents