def within_subjects(cls, ivs, n_participants, design_matrix=None, ordering=None, filename=None):
"""
Create a within-subjects |Experiment|, with all the IVs at the |trial| level.
Parameters
----------
ivs : list or dict
A list of the experiment's IVs, specified in the form of tuples
with the first element being the IV name and the second element a list of its possible values.
Alternatively, the IVs at each level can be specified in a dictionary.
See the |IV docs| more on specifying IVs.
n_participants : int
Number of participants to initialize.
design_matrix : array-like, optional
Design matrix for the experiment. If not specified, IVs will be fully crossed.
See the |design matrix docs| for more details.
ordering : |Ordering|, optional
An instance of the class |Ordering| or one of its subclasses, specifying how the trials will be ordered.
If not specified, |Shuffle| will be used.
filename : str, optional
File location to save the experiment.
Returns
-------
|Experiment|
"""
levels_and_designs = [('participant', [Design(ordering=order.Shuffle(n_participants))]),
('trial', [Design(ivs=ivs, design_matrix=design_matrix, ordering=ordering)])]
return cls.new(DesignTree.new(levels_and_designs), filename=filename)
def from_dict(cls, spec):
"""
Construct an |Experiment| based on a dictionary specification.
Parameters
----------
spec : dict
`spec` should have, at minimum, a key named ``'design'``.
The value of this key specifies the |DesignTree|.
See |DesignTree.from_spec| for details.
The value of the key ``'filename'`` or ``'file'``, if one exists,is saved in |Experiment.filename|.
All other fields are saved in |Experiment.experiment_data|.
Returns
-------
|Experiment|
See Also
--------
experimentator.Experiment.from_yaml_file
"""
tree = DesignTree.from_spec(spec.pop('design'))
filename = spec.pop('filename', spec.pop('file', None))
self = cls.new(tree, filename=filename)
self.experiment_data = spec
return self
def from_dict(cls, spec):
"""
Construct an |Experiment| based on a dictionary specification.
Parameters
----------
spec : dict
`spec` should have, at minimum, a key named ``'design'``.
The value of this key specifies the |DesignTree|.
See |DesignTree.from_spec| for details.
The value of the key ``'filename'`` or ``'file'``, if one exists,is saved in |Experiment.filename|.
All other fields are saved in |Experiment.experiment_data|.
Returns
-------
|Experiment|
See Also
--------
experimentator.Experiment.from_yaml_file
"""
tree = DesignTree.from_spec(spec.pop('design'))
filename = spec.pop('filename', spec.pop('file', None))
self = cls.new(tree, filename=filename)
self.experiment_data = spec
return self
def blocked(cls, trial_ivs, n_participants, design_matrices=None, orderings=None, block_ivs=None, filename=None):
"""Create a blocked within-subjects |Experiment|,
in which all the IVs are at either the trial level or the block level.
Parameters
----------
trial_ivs : list or dict
A list of the IVs to define at the trial level, specified in the form of tuples
with the first element being the IV name and the second element a list of its possible values.
Alternatively, the IVs at each level can be specified in a dictionary.
See the |IV docs| more on specifying IVs.
n_participants : int
Number of participants to initialize.
If a |NonAtomicOrdering| is used,
this is the number of participants per order.
design_matrices : dict, optional
Design matrices for the experiment.
Keys are ``'trial'`` and ``'block'``; values are the respective design matrices (if any).
If not specified, IVs will be fully crossed.
See the |design matrix docs| for details.
orderings : dict, optional
Dictionary with keys of ``'trial'`` and ``'block'``.
Each value should be an instance of the class |Ordering| or one of its subclasses,
specifying how the trials will be ordered
If not specified, |Shuffle| will be used.
block_ivs : list or dict, optional
IVs to define at the block level.
See |IV docs| for more on specifying IVs.
filename : str, optional
File location to save the experiment.
Notes
-----
For blocks to have any effect,
you should either define at least one IV at the block level
or use the ordering ``Ordering(n)`` to create ``n`` blocks for every participant.
Returns
-------
|Experiment|
"""
if not design_matrices:
design_matrices = {}
if not orderings:
orderings = {}
levels_and_designs = [('participant', [Design(ordering=order.Shuffle(n_participants))]),
('block', [Design(ivs=block_ivs,
design_matrix=design_matrices.get('block'),
ordering=orderings.get('block'))]),
('trial', [Design(ivs=trial_ivs,
design_matrix=design_matrices.get('trial'),
ordering=orderings.get('trial'))])]
return cls.new(DesignTree.new(levels_and_designs), filename=filename)
def basic(cls,
levels,
ivs_by_level,
design_matrices_by_level=None,
ordering_by_level=None,
filename=None):
"""Construct a homogeneously-organized |Experiment|,
with arbitrary levels but only one |Design| at each level,
and the same structure throughout its hierarchy.
Parameters
----------
levels : sequence of str
Names of the levels of the experiment
ivs_by_level : dict
Dictionary specifying the IVs and their possible values at every level.
The keys are be the level names,
and the values are lists of the IVs at that level,
specified in the form of tuples with the first element being the IV name
and the second element a list of its possible values.
Alternatively, the IVs at each level can be specified in a dictionary.
See |IV docs| for more on specifying IVs.
design_matrices_by_level : dict, optional
Specify the design matrix for any levels.
Keys are level names; values are design matrices.
Any levels without a design matrix will be fully crossed.
See |design matrix docs| for details.
ordering_by_level : dict, optional
Specify the ordering for each level.
Keys are level names; values are instance objects from |experimentator.order|.
For any levels without an order specified, |Shuffle| will be used.
filename : str, optional
File location to save the experiment.
Returns
-------
|Experiment|
"""
if not design_matrices_by_level:
design_matrices_by_level = {}
if not ordering_by_level:
ordering_by_level = {}
levels_and_designs = [(level, [
Design(ivs=ivs_by_level.get(level),
design_matrix=design_matrices_by_level.get(level),
ordering=ordering_by_level.get(level))
]) for level in levels]
return cls.new(DesignTree.new(levels_and_designs), filename=filename)
def basic(cls, levels, ivs_by_level, design_matrices_by_level=None, ordering_by_level=None, filename=None):
"""Construct a homogeneously-organized |Experiment|,
with arbitrary levels but only one |Design| at each level,
and the same structure throughout its hierarchy.
Parameters
----------
levels : sequence of str
Names of the levels of the experiment
ivs_by_level : dict
Dictionary specifying the IVs and their possible values at every level.
The keys are be the level names,
and the values are lists of the IVs at that level,
specified in the form of tuples with the first element being the IV name
and the second element a list of its possible values.
Alternatively, the IVs at each level can be specified in a dictionary.
See |IV docs| for more on specifying IVs.
design_matrices_by_level : dict, optional
Specify the design matrix for any levels.
Keys are level names; values are design matrices.
Any levels without a design matrix will be fully crossed.
See |design matrix docs| for details.
ordering_by_level : dict, optional
Specify the ordering for each level.
Keys are level names; values are instance objects from |experimentator.order|.
For any levels without an order specified, |Shuffle| will be used.
filename : str, optional
File location to save the experiment.
Returns
-------
|Experiment|
"""
if not design_matrices_by_level:
design_matrices_by_level = {}
if not ordering_by_level:
ordering_by_level = {}
levels_and_designs = [(level, [Design(ivs=ivs_by_level.get(level),
design_matrix=design_matrices_by_level.get(level),
ordering=ordering_by_level.get(level))])
for level in levels]
return cls.new(DesignTree.new(levels_and_designs), filename=filename)
def within_subjects(cls,
ivs,
n_participants,
design_matrix=None,
ordering=None,
filename=None):
"""
Create a within-subjects |Experiment|, with all the IVs at the |trial| level.
Parameters
----------
ivs : list or dict
A list of the experiment's IVs, specified in the form of tuples
with the first element being the IV name and the second element a list of its possible values.
Alternatively, the IVs at each level can be specified in a dictionary.
See the |IV docs| more on specifying IVs.
n_participants : int
Number of participants to initialize.
design_matrix : array-like, optional
Design matrix for the experiment. If not specified, IVs will be fully crossed.
See the |design matrix docs| for more details.
ordering : |Ordering|, optional
An instance of the class |Ordering| or one of its subclasses, specifying how the trials will be ordered.
If not specified, |Shuffle| will be used.
filename : str, optional
File location to save the experiment.
Returns
-------
|Experiment|
"""
levels_and_designs = [
('participant', [Design(ordering=order.Shuffle(n_participants))]),
('trial',
[Design(ivs=ivs, design_matrix=design_matrix, ordering=ordering)])
]
return cls.new(DesignTree.new(levels_and_designs), filename=filename)
def blocked(cls,
trial_ivs,
n_participants,
design_matrices=None,
orderings=None,
block_ivs=None,
filename=None):
"""Create a blocked within-subjects |Experiment|,
in which all the IVs are at either the trial level or the block level.
Parameters
----------
trial_ivs : list or dict
A list of the IVs to define at the trial level, specified in the form of tuples
with the first element being the IV name and the second element a list of its possible values.
Alternatively, the IVs at each level can be specified in a dictionary.
See the |IV docs| more on specifying IVs.
n_participants : int
Number of participants to initialize.
If a |NonAtomicOrdering| is used,
this is the number of participants per order.
design_matrices : dict, optional
Design matrices for the experiment.
Keys are ``'trial'`` and ``'block'``; values are the respective design matrices (if any).
If not specified, IVs will be fully crossed.
See the |design matrix docs| for details.
orderings : dict, optional
Dictionary with keys of ``'trial'`` and ``'block'``.
Each value should be an instance of the class |Ordering| or one of its subclasses,
specifying how the trials will be ordered
If not specified, |Shuffle| will be used.
block_ivs : list or dict, optional
IVs to define at the block level.
See |IV docs| for more on specifying IVs.
filename : str, optional
File location to save the experiment.
Notes
-----
For blocks to have any effect,
you should either define at least one IV at the block level
or use the ordering ``Ordering(n)`` to create ``n`` blocks for every participant.
Returns
-------
|Experiment|
"""
if not design_matrices:
design_matrices = {}
if not orderings:
orderings = {}
levels_and_designs = [
('participant', [Design(ordering=order.Shuffle(n_participants))]),
('block', [
Design(ivs=block_ivs,
design_matrix=design_matrices.get('block'),
ordering=orderings.get('block'))
]),
('trial', [
Design(ivs=trial_ivs,
design_matrix=design_matrices.get('trial'),
ordering=orderings.get('trial'))
])
]
return cls.new(DesignTree.new(levels_and_designs), filename=filename)
