Study-design-driven creation of ISA content¶
In addition to the basic classes for creating ISA objects (such as
Assay described previously),
the ISA API also provides a set of helper Python classes to bootstrap the creation of ISA documents from key parameters obtained from the Design of Experiment (DoE).
The methods allow the creation of the study Treatment plan, the Sample collection Plan and the study assay plan.
The core functions of the ISA-API create mode which are covered in this section are:
- Assay ‘topology modifiers’ that support creating experimental graphs with specific characteristics for different technologies, such as
The package containing all the classes for study-design-based creation of ISA content is
To use this package, include the following import statement in your code, which includes all the objects available in the package
>>> from isatools.create.models import *
Alternatively, you can include specific classes and objects that you are interested in. For example
>>> from isatools.create.models import * from isatools.create.models import (InterventionStudyDesign, Treatment, Characteristic, TreatmentFactory, TreatmentSequence, AssayType, SampleAssayPlan, INTERVENTIONS, BASE_FACTORS_ as BASE_FACTORS, IsaModelObjectFactory, MSAssayTopologyModifiers, DNASeqAssayTopologyModifiers)
Currently, we only support intervention designs by creating objects of the class
`InterventionStudyDesign` (see code snippet below). We will soon also support
>>> study_design = InterventionStudyDesign()
“An intervention design is a study design in which a controlled process applied to the subjects (the intervention) serves as the independent variable manipulated by the experimentalist. The treatment (perturbation or intervention) defined can be defined as a combination of values taken by independent variable manipulated by the experimentalists are applied to the recruited subjects assigned (possibly by applying specific methods) to treatment groups. The specificity of intervention design is the fact that independent variables are being manipulated and a response of the biological system is evaluated via response variables as monitored by possibly a series of assays.”
Creation of treatments: Treatment, TreatmentFactory, TreatmentSequence¶
Treatment class is defined as a tuple of factor values (as defined in the ISA model v1) and a treatment type.
agent = StudyFactor(name="agent", factor_type="agent value") intensity = StudyFactor(name="intensity", factor_type="intensity value") duration = StudyFactor(name="duration post exposure", factor_type="duration value") treatment = Treatment(treatment_type=INTERVENTIONS['CHEMICAL'], factor_values=( FactorValue(factor_name=agent, value='ibuprofen'), FactorValue(factor_name=intensity, value='low dose'), FactorValue(factor_name=duration, value='2 hr') ))
For convenience, a few objects are provided with some common:
INTERVENTIONSsuch as chemical, behavioural, surgical, biological, radiological, and
BASE_FACTORSrepresenting a perturbation agent, intensity and duration of the treatment
but if these are not suitable for your purposes, you can build your own intervention type and factors.
In the example above we use one of the common interventions but created our own set of ``StudyFactor``s.
Instead of creating individual treatments, you may want to create all the treatments required for a specific design type.
TreatmentFactory class provides utility methods to create a set of
Treatment objects. One of the utility methods is that
for creating the set of treatments corresponding to a full factorial design (using method
This computes all the combinations of factor values, returning an empty set if one of the factors has no associated values.
An example of using the
TreatmentFactory class is as follows:
factorial_design_treatments object will contain the set of 18 treatments that result from performing all the combinations of the 3x3x2 factor values shown above.
A set of treatments may be combined in a
TreatmentSequence class provides a way of building is an ordered sequence of treatments, where each
treatment is assigned a rank, or epoch number, with the following properties: the epoch numbers always start with 1 (lowest epoch number),
all epochs should be positive integers, epoch numbers may be repeated (for concomitant treatments),
no value should be missing between the lowest epoch (1) and the highest epoch.
Creation of Sample and Assay Plans¶
After you have identified the treatments, to describe your experiment fully you will need to indicate
the sampling plan (i.e. in which way you select the samples) as well as the assay plan (i.e. what
measurements you are taken from the samples). For this purpose, we provide the
Taking into account the specifics of Data Acquisition events dependent on methodology and technology¶
The Assay ‘topology modifiers’ functions (such as
MSAssayTopologyModifiers for Mass Spectrometry based assays or
DNASeqAssayTopologyModifiers for DNA sequence assays) are present to support specific branching or pooling events affecting the underlying experimental graph, which we aim to represent with ISA objects.
Depending on the assay and the technology used to acquire data, the number of ‘hinge points’ may vary but the basic principle remains the same. Some are common to all: for instance, irrespective of the technique, one may carry out several data acquisition on the same input material (technical replication). On the other hand, when using a technique such as mass spectrometry
an range of setting may be set by the operators, such as the type of injections modes, the type of acquisition modes. When using sequencing technology, different instruments may be used, libraries may be prepared as single or paired ends.
The ‘Topology Modifiers’ method in the ISA-API allows to specify those in a flexible yet generic way.
We will explain each of these objects and how to use them below.