Asset - PsyNet 11.10.0-dev0 documentation

class psynet.asset.Asset(*args, **kwargs)[source]¶

Bases: AssetSpecification, Base, SQLMixin

Assets represent particular files (or sometimes collections of files) that are used within an experiment. It is encouraged to register things like audio files and video files as assets so that they can be managed appropriately by PsyNet’s deploy and export mechanisms.

Parameters:

local_key (str) – A string identifier for the asset, for example "stimulus". If provided, this string identifier should together with parent and module_id uniquely identify that asset (i.e. no other asset should share that combination of properties).
description (str) – An optional longer string that provides further documentation about the asset.
is_folder (bool) – Whether the asset is a folder.
data_type (str) – Experimental: the nature of the asset’s data. Could be used to determine visualization methods etc.
extension (str) – The file extension, if applicable.
parent (object) – The object that ‘owns’ the asset, if applicable, for example a Participant or a Node.
key_within_module (str) – A string that uniquely identifies the asset within a given module. If left unspecified, this will be automatically generated with reference to the parent and the local_key arguments.
key_within_experiment (str) – A string that uniquely identifies the asset within a given experiment. If left unspecified, this will be automatically generated with reference to the key_within_module and the module_id arguments.
module_id (str) – The module within which the asset is located.
personal (bool) – Whether the asset is ‘personal’ and hence omitted from anonymous database exports.

needs_storage_backend¶

Whether the asset type needs a storage backend, e.g. a file server, or whether it can do without (e.g. in the case of an externally hosted resource accessible by a URL).

Type:: bool

psynet_version¶

The version of PsyNet used to create the asset.

Type:: str

deployment_id¶

A string used to identify the particular experiment deployment.

Type:: str

deposited¶

Whether the asset has been deposited yet.

Type:: bool

inherited¶

Whether the asset was inherited from a previous experiment, typically via the InheritedAssets functionality.

Type:: bool

inherited_from¶

Identifies the source of an inherited asset.

Type:: str

export_path¶

A relative path that will be used by default when the asset is exported.

Type:: str

participant_id¶

ID of the participant who ‘owns’ the asset, if applicable.

Type:: int

content_id¶

A token used for checking whether the contents of two assets are equivalent. This takes various forms depending on the asset type. For a file, the content_id would typically be a hash; for an externally hosted asset, it would be the URL, etc.

Type:: str

host_path¶

The filepath used to host the asset within the storage repository, if applicable.

Type:: str

url¶

The URL that can be used to access the asset from the perspective of the experiment front-end.

Type:: str

storage¶

The storage backend used for the asset.

Type:: AssetStorage

async_processes¶

Lists all async processes that have been created for the asset, including completed ones.

Type:: list

participant¶: If the parent is a Participant, returns that participant.

participants¶

Lists all participants associated with the asset.

Type:: list

trial¶: If the parent is a trial, returns that trial.

trials¶

Lists all trials associated with the asset.

Type:: list

node¶: If the parent is a Node, returns that participant.

nodes¶

Lists all nodes associated with the asset.

Type:: list

network¶: If the parent is a Network, returns that participant.

networks¶

Lists all networks associated with the asset.

Type:: list

errors¶

Lists the errors associated with the asset.

Type:: list

Linking assets to other database objects¶

PsyNet assets may be linked to other database objects. There are two kinds of links that may be used. First, an asset may possess a parent. This parental relationship is strict in the sense that an asset may not possess more than one parent.

However, in addition to the parental relationship, it is possible to link the asset to an arbitrary number of additional database objects. These latter links have a key-value construction, meaning that one can access a given asset by reference to a given key, for example: node.assets["response"].

Importantly, the same asset can have different keys for different objects; for example, it might be the response for one node, but the stimulus for another node. These latter relationships are instantiated with logic like the following:

participant.assets["stimulus"] = my_asset

creation_time¶: the time at which the Network was created.

delete_input()[source]¶: Deletes the input file(s) that make(s) up the asset.

deposit(storage=None, async_=False, delete_input=False)[source]¶

Parameters:

storage – If set to an AssetStorage object, the asset will be deposited to the provided storage location rather than defaulting to the Experiment class’s storage location.
async – If set to True, then the asset deposit will be performed asynchronously and the program’s execution will continue without waiting for the deposit to complete. It is sensible to set this to True if you see that the participant interface is being held up noticeably by waiting for the deposit to complete.
delete_input (bool) – If set to True, then the input file will be deleted after it has been deposited.

details¶: a generic column for storing structured JSON data

failed = None¶: boolean indicating whether the Network has failed which prompts Dallinger to ignore it unless specified otherwise. Objects are usually failed to indicate something has gone wrong.

failed_reason = None¶: an optional reason the object was failed. If the object is failed as part of a cascading failure triggered from another object, the chain of objects will be captured in this field.

id¶: a unique number for every entry. 1, 2, 3 and so on…

prepare_for_deployment(registry)[source]¶: Runs in advance of the experiment being deployed to the remote server.

property1¶: a generic column that can be used to store experiment-specific details in String form.

property2¶: a generic column that can be used to store experiment-specific details in String form.

property3¶: a generic column that can be used to store experiment-specific details in String form.

property4¶: a generic column that can be used to store experiment-specific details in String form.

property5¶: a generic column that can be used to store experiment-specific details in String form.

registry¶

time_of_death = None¶: the time at which failing occurred

type¶

vars¶

class psynet.asset.AssetCollection(local_key, key_within_module, key_within_experiment, description)[source]¶

Bases: AssetSpecification

A base class for specifying a collection of assets.

class psynet.asset.AssetLink(local_key, asset)[source]¶

Bases: object

These objects define many-to-many mappings between assets and other database objects. When we write something like participant.assets["stimulus"] = my_asset, this creates an object subclassing AssetLink to represent that relationship.

class psynet.asset.AssetModuleState(*args, **kwargs)[source]¶

Bases: AssetLink, Base, SQLMixin

asset_id¶

creation_time¶: the time at which the Network was created.

details¶: a generic column for storing structured JSON data

local_key¶

property1¶: a generic column that can be used to store experiment-specific details in String form.

property2¶: a generic column that can be used to store experiment-specific details in String form.

property3¶: a generic column that can be used to store experiment-specific details in String form.

property4¶: a generic column that can be used to store experiment-specific details in String form.

property5¶: a generic column that can be used to store experiment-specific details in String form.

type¶

vars¶

class psynet.asset.AssetNetwork(*args, **kwargs)[source]¶

Bases: AssetLink, Base, SQLMixin

asset_id¶

creation_time¶: the time at which the Network was created.

details¶: a generic column for storing structured JSON data

local_key¶

property1¶: a generic column that can be used to store experiment-specific details in String form.

property2¶: a generic column that can be used to store experiment-specific details in String form.

property3¶: a generic column that can be used to store experiment-specific details in String form.

property4¶: a generic column that can be used to store experiment-specific details in String form.

property5¶: a generic column that can be used to store experiment-specific details in String form.

type¶

vars¶

class psynet.asset.AssetNode(*args, **kwargs)[source]¶

Bases: AssetLink, Base, SQLMixin

asset_id¶

creation_time¶: the time at which the Network was created.

details¶: a generic column for storing structured JSON data

local_key¶

property1¶: a generic column that can be used to store experiment-specific details in String form.

property2¶: a generic column that can be used to store experiment-specific details in String form.

property3¶: a generic column that can be used to store experiment-specific details in String form.

property4¶: a generic column that can be used to store experiment-specific details in String form.

property5¶: a generic column that can be used to store experiment-specific details in String form.

type¶

vars¶

class psynet.asset.AssetParticipant(*args, **kwargs)[source]¶

Bases: AssetLink, Base, SQLMixin

asset_id¶

creation_time¶: the time at which the Network was created.

details¶: a generic column for storing structured JSON data

local_key¶

property1¶: a generic column that can be used to store experiment-specific details in String form.

property2¶: a generic column that can be used to store experiment-specific details in String form.

property3¶: a generic column that can be used to store experiment-specific details in String form.

property4¶: a generic column that can be used to store experiment-specific details in String form.

property5¶: a generic column that can be used to store experiment-specific details in String form.

type¶

vars¶

class psynet.asset.AssetSpecification(local_key, key_within_module, key_within_experiment, description)[source]¶

Bases: NullElt

A base class for asset specifications. An asset specification defines some kind of asset or collection or assets. It can be included within an experiment timeline.

Parameters:

local_key (str) – A string identifier for the asset, for example "stimulus". If provided, this string identifier should together with parent and module_id uniquely identify that asset (i.e. no other asset should share that combination of properties).
description (str) – An optional longer string that provides further documentation about the asset.

class psynet.asset.AssetStorage[source]¶

Bases: object

Defines a storage back-end for storing assets.

check_cache(host_path, is_folder)[source]¶

Checks whether the registry can find an asset cached at host_path. The implementation is permitted to make optimizations for speed that may result in missed caches, i.e. returning False when the cache did actually exists. However, the implementation should only return True if it is certain that the asset cache exists.

Returns:

True or False.

class psynet.asset.AssetTrial(*args, **kwargs)[source]¶

Bases: AssetLink, Base, SQLMixin

asset_id¶

creation_time¶: the time at which the Network was created.

details¶: a generic column for storing structured JSON data

local_key¶

property1¶: a generic column that can be used to store experiment-specific details in String form.

property2¶: a generic column that can be used to store experiment-specific details in String form.

property3¶: a generic column that can be used to store experiment-specific details in String form.

property4¶: a generic column that can be used to store experiment-specific details in String form.

property5¶: a generic column that can be used to store experiment-specific details in String form.

type¶

vars¶

exception psynet.asset.AwsCliError[source]¶

Bases: RuntimeError

class psynet.asset.CachedAsset(*args, **kwargs)[source]¶

Bases: ManagedAsset

The classic use of a CachedAsset would be to store some kind of stimulus that is pre-defined in advance of experiment launch. For example:

asset = CachedAsset(
   key_within_module="bier",
   input_path="bier.wav",
   description="A recording of someone saying 'bier'",
)

Cached assets are most commonly instantiated by passing them to the assets arguments of modules or nodes when defining the Experiment timeline. PsyNet compiles these assets together before experiment deployment and makes sure they are uploaded if necessary.

In contrast to Experiment Assets, Cached Assets are shared between different experiments, so as to avoid duplicating time-consuming file generation or upload routines. The cached assets are stored in the selected asset storage back-end, and if PsyNet detects that the requested asset exists already then it will skip creating/uploading that asset. Under the hood there is some special logic to ensure that the caches are invalidated if the file content has changed.

Parameters:

input_path (str) – Path to the file/folder from which the asset is to be created.
local_key (str) – A string identifier for the asset, for example "stimulus". If provided, this string identifier should together with parent and module_id should uniquely identify that asset (i.e. no other asset should share that combination of properties).
description (str) – An optional longer string that provides further documentation about the asset.
is_folder (bool) – Whether the asset is a folder.
data_type (str) – Experimental: the nature of the asset’s data. Could be used to determine visualization methods etc.
extension (str) – The file extension, if applicable.
parent (object) – The object that ‘owns’ the asset, if applicable, for example a Participant or a Node.
key_within_module (str) – An optional key that uniquely identifies the asset within a given module. If left unspecified, this will be automatically generated with reference to the parent and the local_key arguments.
key_within_experiment (str) – A string that uniquely identifies the asset within a given experiment. If left unspecified, this will be automatically generated with reference to the key_within_module and the module_id arguments.
module_id (str) – Identifies the module with which the asset should be associated. If left blank, PsyNet will attempt to infer the module_id from the parent parameter, if provided.
personal (bool) – Whether the asset is ‘personal’ and hence omitted from anonymous database exports.
obfuscate (int) – Determines the extent to which the asset’s generated URL should be obfuscated. By default, obfuscate=1, which means that the URL contains a human-readable component containing useful metadata (e.g the participant ID), but also contains a randomly generated string so that malicious agents cannot retrieve arbitrary assets by guessing URLs. If obfuscate=0, then the randomly generated string is not added. If obfuscate=2, then the human-readable component is omitted, and only the random portion is kept. This might be useful in cases where you’re worried about participants cheating on the experiment by looking at file URLs.

md5_contents¶

Contains an automatically generated MD5 hash of the object’s contents, where ‘contents’ is liberally defined; it could mean hashing the file itself, or hashing the arguments of the function used to generate that file.

Type:: str

size_mb¶

The size of the asset’s file(s) (in MB).

Type:: float

deposit_time_sec¶

The time it took to deposit the asset.

Type:: float

needs_storage_backend¶

Whether the asset type needs a storage backend, e.g. a file server, or whether it can do without (e.g. in the case of an externally hosted resource accessible by a URL).

Type:: bool

psynet_version¶

The version of PsyNet used to create the asset.

Type:: str

deployment_id¶

A string used to identify the particular experiment deployment.

Type:: str

deposited¶

Whether the asset has been deposited yet.

Type:: bool

inherited¶

Whether the asset was inherited from a previous experiment, typically via the InheritedAssets functionality.

Type:: bool

inherited_from¶

Identifies the source of an inherited asset.

Type:: str

export_path¶

A relative path that will be used by default when the asset is exported.

Type:: str

participant_id¶

ID of the participant who ‘owns’ the asset, if applicable.

Type:: int

content_id¶

A token used for checking whether the contents of two assets are equivalent. This takes various forms depending on the asset type. For a file, the content_id would typically be a hash; for an externally hosted asset, it would be the URL, etc.

Type:: str

host_path¶

The filepath used to host the asset within the storage repository, if applicable.

Type:: str

url¶

The URL that can be used to access the asset from the perspective of the experiment front-end.

Type:: str

storage¶

The storage backend used for the asset.

Type:: AssetStorage

async_processes¶

Lists all async processes that have been created for the asset, including completed ones.

Type:: list

participant¶: If the parent is a Participant, returns that participant.

participants¶

Lists all participants associated with the asset.

Type:: list

trial¶: If the parent is a trial, returns that trial.

trials¶

Lists all trials associated with the asset.

Type:: list

node¶: If the parent is a Node, returns that participant.

nodes¶

Lists all nodes associated with the asset.

Type:: list

network¶: If the parent is a Network, returns that participant.

networks¶

Lists all networks associated with the asset.

Type:: list

errors¶

Lists the errors associated with the asset.

Type:: list

Linking assets to other database objects¶

PsyNet assets may be linked to other database objects. There are two kinds of links that may be used. First, an asset may possess a parent. This parental relationship is strict in the sense that an asset may not possess more than one parent.

However, in addition to the parental relationship, it is possible to link the asset to an arbitrary number of additional database objects. These latter links have a key-value construction, meaning that one can access a given asset by reference to a given key, for example: node.assets["response"].

Importantly, the same asset can have different keys for different objects; for example, it might be the response for one node, but the stimulus for another node. These latter relationships are instantiated with logic like the following:

participant.assets["stimulus"] = my_asset

creation_time¶: the time at which the Network was created.

delete_input()[source]¶: Deletes the input file(s) that make(s) up the asset.

details¶: a generic column for storing structured JSON data

id¶: a unique number for every entry. 1, 2, 3 and so on…

property1¶: a generic column that can be used to store experiment-specific details in String form.

property2¶: a generic column that can be used to store experiment-specific details in String form.

property3¶: a generic column that can be used to store experiment-specific details in String form.

property4¶: a generic column that can be used to store experiment-specific details in String form.

property5¶: a generic column that can be used to store experiment-specific details in String form.

type¶

vars¶

class psynet.asset.CachedFunctionAsset(*args, **kwargs)[source]¶

Bases: FunctionAssetMixin, CachedAsset

A Cached Function Asset is a type of asset whose files are created by running a function, and whose outputs are stored in a general repository that is shared between multiple experiment deployments, to avoid redundant computation or file uploads.

Parameters:

function (callable) – A function responsible for generating the asset. The function should receive an argument called path and create a file or a folder at that path. It can also receive additional arguments specified via the arguments parameter.
local_key (str) – A string identifier for the asset, for example "stimulus". If provided, this string identifier should together with parent and module_id should uniquely identify that asset (i.e. no other asset should share that combination of properties).
arguments (dict) – An optional dictionary of arguments that should be passed to the function.
is_folder (bool) – Whether the asset is a folder.
description (str) – An optional longer string that provides further documentation about the asset.
data_type (str) – Experimental: the nature of the asset’s data. Could be used to determine visualization methods etc.
extension (str) – The file extension, if applicable.
key_within_module (str) – An optional key that uniquely identifies the asset within a given module. If left unspecified, this will be automatically generated with reference to the parent and the local_key arguments.
key_within_experiment (str) – A string that uniquely identifies the asset within a given experiment. If left unspecified, this will be automatically generated with reference to the key_within_module and the module_id arguments.
module_id (str) – Identifies the module with which the asset should be associated. If left blank, PsyNet will attempt to infer the module_id from the parent parameter, if provided.
parent (object) – The object that ‘owns’ the asset, if applicable, for example a Participant or a Node.
personal (bool) – Whether the asset is ‘personal’ and hence omitted from anonymous database exports.
obfuscate (int) – Determines the extent to which the asset’s generated URL should be obfuscated. By default, obfuscate=1, which means that the URL contains a human-readable component containing useful metadata (e.g the participant ID), but also contains a randomly generated string so that malicious agents cannot retrieve arbitrary assets by guessing URLs. If obfuscate=0, then the randomly generated string is not added. If obfuscate=2, then the human-readable component is omitted, and only the random portion is kept. This might be useful in cases where you’re worried about participants cheating on the experiment by looking at file URLs.

computation_time_sec¶

The time taken to generate the asset.

Type:: float

md5_contents¶

Contains an automatically generated MD5 hash of the object’s contents, where ‘contents’ is liberally defined; it could mean hashing the file itself, or hashing the arguments of the function used to generate that file.

Type:: str

size_mb¶

The size of the asset’s file(s) (in MB).

Type:: float

deposit_time_sec¶

The time it took to deposit the asset.

Type:: float

needs_storage_backend¶

Whether the asset type needs a storage backend, e.g. a file server, or whether it can do without (e.g. in the case of an externally hosted resource accessible by a URL).

Type:: bool

psynet_version¶

The version of PsyNet used to create the asset.

Type:: str

deployment_id¶

A string used to identify the particular experiment deployment.

Type:: str

deposited¶

Whether the asset has been deposited yet.

Type:: bool

inherited¶

Whether the asset was inherited from a previous experiment, typically via the InheritedAssets functionality.

Type:: bool

inherited_from¶

Identifies the source of an inherited asset.

Type:: str

export_path¶

A relative path that will be used by default when the asset is exported.

Type:: str

participant_id¶

ID of the participant who ‘owns’ the asset, if applicable.

Type:: int

content_id¶

A token used for checking whether the contents of two assets are equivalent. This takes various forms depending on the asset type. For a file, the content_id would typically be a hash; for an externally hosted asset, it would be the URL, etc.

Type:: str

host_path¶

The filepath used to host the asset within the storage repository, if applicable.

Type:: str

url¶

The URL that can be used to access the asset from the perspective of the experiment front-end.

Type:: str

storage¶

The storage backend used for the asset.

Type:: AssetStorage

async_processes¶

Lists all async processes that have been created for the asset, including completed ones.

Type:: list

participant¶: If the parent is a Participant, returns that participant.

participants¶

Lists all participants associated with the asset.

Type:: list

trial¶: If the parent is a trial, returns that trial.

trials¶

Lists all trials associated with the asset.

Type:: list

node¶: If the parent is a Node, returns that participant.

nodes¶

Lists all nodes associated with the asset.

Type:: list

network¶: If the parent is a Network, returns that participant.

networks¶

Lists all networks associated with the asset.

Type:: list

errors¶

Lists the errors associated with the asset.

Type:: list

Linking assets to other database objects¶

PsyNet assets may be linked to other database objects. There are two kinds of links that may be used. First, an asset may possess a parent. This parental relationship is strict in the sense that an asset may not possess more than one parent.

However, in addition to the parental relationship, it is possible to link the asset to an arbitrary number of additional database objects. These latter links have a key-value construction, meaning that one can access a given asset by reference to a given key, for example: node.assets["response"].

Importantly, the same asset can have different keys for different objects; for example, it might be the response for one node, but the stimulus for another node. These latter relationships are instantiated with logic like the following:

participant.assets["stimulus"] = my_asset
db.session.commit()

creation_time¶: the time at which the Network was created.

details¶: a generic column for storing structured JSON data

id¶: a unique number for every entry. 1, 2, 3 and so on…

property1¶: a generic column that can be used to store experiment-specific details in String form.

property2¶: a generic column that can be used to store experiment-specific details in String form.

property3¶: a generic column that can be used to store experiment-specific details in String form.

property4¶: a generic column that can be used to store experiment-specific details in String form.

property5¶: a generic column that can be used to store experiment-specific details in String form.

type¶

vars¶

class psynet.asset.DebugStorage(*args, **kwargs)[source]¶

Bases: LocalStorage

A local storage back-end used for debugging.

Deprecated since version 11.0.0: Use LocalStorage instead.

class psynet.asset.ExperimentAsset(*args, **kwargs)[source]¶

Bases: ManagedAsset

The ExperimentAsset class is one of the most commonly used Asset classes. It refers to assets that are specific to the current experiment deployment. This would typically mean assets that are generated during the course of the experiment, for example recordings from a singer, or stimuli generated on the basis of participant responses.

Examples

import tempfile

with tempfile.NamedTemporaryFile("w") as file:
    file.write(f"Your message here")
    asset = ExperimentAsset(
        local_key="my_message",
        input_path=file.name,
        extension=".txt",
        parent=participant,
    )
    asset.deposit()

Parameters:

input_path (str) – Path to the file/folder from which the asset is to be created.
local_key (str) – A string identifier for the asset, for example "stimulus". If provided, this string identifier should together with parent and module_id should uniquely identify that asset (i.e. no other asset should share that combination of properties).
description (str) – An optional longer string that provides further documentation about the asset.
is_folder (bool) – Whether the asset is a folder.
data_type (str) – Experimental: the nature of the asset’s data. Could be used to determine visualization methods etc.
extension (str) – The file extension, if applicable.
parent (object) – The object that ‘owns’ the asset, if applicable, for example a Participant or a Node.
key_within_module (str) – An optional key that uniquely identifies the asset within a given module. If left unspecified, this will be automatically generated with reference to the parent and the local_key arguments.
key_within_experiment (str) – A string that uniquely identifies the asset within a given experiment. If left unspecified, this will be automatically generated with reference to the key_within_module and the module_id arguments.
module_id (str) – Identifies the module with which the asset should be associated. If left blank, PsyNet will attempt to infer the module_id from the parent parameter, if provided.
personal (bool) – Whether the asset is ‘personal’ and hence omitted from anonymous database exports.
obfuscate (int) – Determines the extent to which the asset’s generated URL should be obfuscated. By default, obfuscate=1, which means that the URL contains a human-readable component containing useful metadata (e.g the participant ID), but also contains a randomly generated string so that malicious agents cannot retrieve arbitrary assets by guessing URLs. If obfuscate=0, then the randomly generated string is not added. If obfuscate=2, then the human-readable component is omitted, and only the random portion is kept. This might be useful in cases where you’re worried about participants cheating on the experiment by looking at file URLs.

needs_storage_backend¶

Whether the asset type needs a storage backend, e.g. a file server, or whether it can do without (e.g. in the case of an externally hosted resource accessible by a URL).

Type:: bool

psynet_version¶

The version of PsyNet used to create the asset.

Type:: str

deployment_id¶

A string used to identify the particular experiment deployment.

Type:: str

deposited¶

Whether the asset has been deposited yet.

Type:: bool

inherited¶

Whether the asset was inherited from a previous experiment, typically via the InheritedAssets functionality.

Type:: bool

inherited_from¶

Identifies the source of an inherited asset.

Type:: str

export_path¶

A relative path constructed that will be used by default when the asset is exported.

Type:: str

participant_id¶

ID of the participant who ‘owns’ the asset, if applicable.

Type:: int

content_id¶

A token used for checking whether the contents of two assets are equivalent. This takes various forms depending on the asset type. For a file, the content_id would typically be a hash; for an externally hosted asset, it would be the URL, etc.

Type:: str

host_path¶

The filepath used to host the asset within the storage repository, if applicable.

Type:: str

url¶

The URL that can be used to access the asset from the perspective of the experiment front-end.

Type:: str

storage¶

The storage backend used for the asset.

Type:: AssetStorage

async_processes¶

Lists all async processes that have been created for the asset, including completed ones.

Type:: list

participant¶: If the parent is a Participant, returns that participant.

participants¶

Lists all participants associated with the asset.

Type:: list

trial¶: If the parent is a trial, returns that trial.

trials¶

Lists all trials associated with the asset.

Type:: list

node¶: If the parent is a Node, returns that participant.

nodes¶

Lists all nodes associated with the asset.

Type:: list

network¶: If the parent is a Network, returns that participant.

networks¶

Lists all networks associated with the asset.

Type:: list

errors¶

Lists the errors associated with the asset.

Type:: list

Linking assets to other database objects¶

PsyNet assets may be linked to other database objects. There are two kinds of links that may be used. First, an asset may possess a parent. This parental relationship is strict in the sense that an asset may not possess more than one parent.

However, in addition to the parental relationship, it is possible to link the asset to an arbitrary number of additional database objects. These latter links have a key-value construction, meaning that one can access a given asset by reference to a given key, for example: node.assets["response"].

Importantly, the same asset can have different keys for different objects; for example, it might be the response for one node, but the stimulus for another node. These latter relationships are instantiated with logic like the following:

participant.assets["stimulus"] = my_asset

creation_time¶: the time at which the Network was created.

details¶: a generic column for storing structured JSON data

id¶: a unique number for every entry. 1, 2, 3 and so on…

property1¶: a generic column that can be used to store experiment-specific details in String form.

property2¶: a generic column that can be used to store experiment-specific details in String form.

property3¶: a generic column that can be used to store experiment-specific details in String form.

property4¶: a generic column that can be used to store experiment-specific details in String form.

property5¶: a generic column that can be used to store experiment-specific details in String form.

type¶

vars¶

class psynet.asset.ExternalAsset(*args, **kwargs)[source]¶

Bases: Asset

An External Asset is an asset that is not managed by PsyNet. This would typically mean some kind of file that is hosted on a remote web server and is accessible by a URL.

Parameters:

url (str) – The URL at which the external asset may be accessed.
local_key (str) – A string identifier for the asset, for example "stimulus". If provided, this string identifier should together with parent and module_id uniquely identify that asset (i.e. no other asset should share that combination of properties).
description (str) – An optional longer string that provides further documentation about the asset.
is_folder (bool) – Whether the asset is a folder.
data_type (str) – Experimental: the nature of the asset’s data. Could be used to determine visualization methods etc.
extension (str) – The file extension, if applicable.
parent (object) – The object that ‘owns’ the asset, if applicable, for example a Participant or a Node.
key_within_module (str) – A string that uniquely identifies the asset within a given module. If left unspecified, this will be automatically generated with reference to the parent and the local_key arguments.
key_within_experiment (str) – A string that uniquely identifies the asset within a given experiment. If left unspecified, this will be automatically generated with reference to the key_within_module and the module_id arguments.
module_id (str) – The module within which the asset is located.
personal (bool) – Whether the asset is ‘personal’ and hence omitted from anonymous database exports.

psynet_version¶

The version of PsyNet used to create the asset.

Type:: str

deployment_id¶

A string used to identify the particular experiment deployment.

Type:: str

deposited¶

Whether the asset has been deposited yet.

Type:: bool

inherited¶

Whether the asset was inherited from a previous experiment, typically via the InheritedAssets functionality.

Type:: bool

inherited_from¶

Identifies the source of an inherited asset.

Type:: str

export_path¶

A relative path that will be used by default when the asset is exported.

Type:: str

participant_id¶

ID of the participant who ‘owns’ the asset, if applicable.

Type:: int

content_id¶

A token used for checking whether the contents of two assets are equivalent. This takes various forms depending on the asset type. For a file, the content_id would typically be a hash; for an externally hosted asset, it would be the URL, etc.

Type:: str

host_path¶

The filepath used to host the asset within the storage repository, if applicable.

Type:: str

url¶

The URL that can be used to access the asset from the perspective of the experiment front-end.

Type:: str

storage¶

The storage backend used for the asset.

Type:: AssetStorage

async_processes¶

Lists all async processes that have been created for the asset, including completed ones.

Type:: list

participant¶: If the parent is a Participant, returns that participant.

participants¶

Lists all participants associated with the asset.

Type:: list

trial¶: If the parent is a trial, returns that trial.

trials¶

Lists all trials associated with the asset.

Type:: list

node¶: If the parent is a Node, returns that participant.

nodes¶

Lists all nodes associated with the asset.

Type:: list

network¶: If the parent is a Network, returns that participant.

networks¶

Lists all networks associated with the asset.

Type:: list

errors¶

Lists the errors associated with the asset.

Type:: list

Linking assets to other database objects¶

PsyNet assets may be linked to other database objects. There are two kinds of links that may be used. First, an asset may possess a parent. This parental relationship is strict in the sense that an asset may not possess more than one parent.

However, in addition to the parental relationship, it is possible to link the asset to an arbitrary number of additional database objects. These latter links have a key-value construction, meaning that one can access a given asset by reference to a given key, for example: node.assets["response"].

Importantly, the same asset can have different keys for different objects; for example, it might be the response for one node, but the stimulus for another node. These latter relationships are instantiated with logic like the following:

participant.assets["stimulus"] = my_asset
db.session.commit()

creation_time¶: the time at which the Network was created.

delete_input()[source]¶: Deletes the input file(s) that make(s) up the asset.

details¶: a generic column for storing structured JSON data

id¶: a unique number for every entry. 1, 2, 3 and so on…

property1¶: a generic column that can be used to store experiment-specific details in String form.

property2¶: a generic column that can be used to store experiment-specific details in String form.

property3¶: a generic column that can be used to store experiment-specific details in String form.

property4¶: a generic column that can be used to store experiment-specific details in String form.

property5¶: a generic column that can be used to store experiment-specific details in String form.

type¶

vars¶

class psynet.asset.ExternalS3Asset(*args, **kwargs)[source]¶

Bases: ExternalAsset

Represents an external asset that is stored in an Amazon Web Services S3 bucket.

creation_time¶: the time at which the Network was created.

property default_storage¶: The notional storage back-end for external web-hosted assets.

delete_input()[source]¶: Deletes the input file(s) that make(s) up the asset.

details¶: a generic column for storing structured JSON data

id¶: a unique number for every entry. 1, 2, 3 and so on…

property1¶: a generic column that can be used to store experiment-specific details in String form.

property2¶: a generic column that can be used to store experiment-specific details in String form.

property3¶: a generic column that can be used to store experiment-specific details in String form.

property4¶: a generic column that can be used to store experiment-specific details in String form.

property5¶: a generic column that can be used to store experiment-specific details in String form.

type¶

vars¶

class psynet.asset.FastFunctionAsset(*args, **kwargs)[source]¶

Bases: OnDemandAsset

Deprecated since version 11.7.0: Use OnDemandAsset instead.

creation_time¶: the time at which the Network was created.

details¶: a generic column for storing structured JSON data

id¶: a unique number for every entry. 1, 2, 3 and so on…

property1¶: a generic column that can be used to store experiment-specific details in String form.

property2¶: a generic column that can be used to store experiment-specific details in String form.

property3¶: a generic column that can be used to store experiment-specific details in String form.

property4¶: a generic column that can be used to store experiment-specific details in String form.

property5¶: a generic column that can be used to store experiment-specific details in String form.

type¶

vars¶

class psynet.asset.FunctionAssetMixin(function, *, arguments=None, is_folder=False, description=None, data_type=None, extension=None, local_key=None, key_within_module=None, key_within_experiment=None, module_id=None, parent=None, personal=False, obfuscate=1)[source]¶

Bases: object

This Mixin is used to define Asset classes that create their assets not from input files but from functions that are called with a specified set of arguments. It is not to be instantiated directly.

Parameters:

function (callable) – A function responsible for generating the asset. The function should receive an argument called path and create a file or a folder at that path. It can also receive additional arguments specified via the arguments parameter.
arguments (dict) – An optional dictionary of arguments that should be passed to the function.

computation_time_sec¶

The time taken to generate the asset.

Type:: float

property instructions¶: The ‘instructions’ that define how to create the asset.

class psynet.asset.InheritedAssets(path, key)[source]¶

Bases: AssetCollection

Experimental: Provides a way to load assets from a previously deployed experiment into a new experiment.

Parameters:

path (str) – Path to a CSV file specifying the previous assets. This CSV file should come from the db/asset.csv file of an experiment export. The CSV file can optionally be customized by deleting rows corresponding to unneeded assets, or it can be merged with analogous CSV files from other experiments.
key (str) – A string that is used to identify the source of the imported assets in the Asset.inherited_from attribute.

class psynet.asset.LocalStorage(root=None)[source]¶

Bases: AssetStorage

Stores assets in a local folder on the same computer that is running your Python code. This approach is suitable when you are running experiments on a single local machine (e.g. when doing fieldwork or laboratory-based data collection), and when you are deploying your experiments to your own remote web server via Docker. It is not appropriate if you deploy your experiments via Heroku, because Heroku deployments split the processing over multiple web servers, and these different web servers do not share the same file system.

check_cache(host_path, is_folder)[source]¶

Checks whether the registry can find an asset cached at host_path. The implementation is permitted to make optimizations for speed that may result in missed caches, i.e. returning False when the cache did actually exists. However, the implementation should only return True if it is certain that the asset cache exists.

Returns:

True or False.

property public_path¶: This is the publicly exposed path by which the web browser can access the storage registry. This corresponds to a (symlinked) directory inside the experiment directory.

property root¶: We defer the registration of the root until as late as possible to avoid circular imports when loading the experiment.

class psynet.asset.ManagedAsset(*args, **kwargs)[source]¶

Bases: Asset

This is a parent class for assets that are actively ‘managed’ by PsyNet. Active managing means that PsyNet takes responsibility for storing the asset in its own storage repositories. This class is not generally instantiated directly, but is instead instantiated via its subclasses.

Parameters:

input_path (str) – Path to the file/folder from which the asset is to be created.
local_key (str) – A string identifier for the asset, for example "stimulus". If provided, this string identifier should together with parent and module_id should uniquely identify that asset (i.e. no other asset should share that combination of properties).
description (str) – An optional longer string that provides further documentation about the asset.
is_folder (bool) – Whether the asset is a folder.
data_type (str) – Experimental: the nature of the asset’s data. Could be used to determine visualization methods etc.
extension (str) – The file extension, if applicable.
parent (object) – The object that ‘owns’ the asset, if applicable, for example a Participant or a Node.
key_within_module (str) – An optional key that uniquely identifies the asset within a given module. If left unspecified, this will be automatically generated with reference to the parent and the local_key arguments.
key_within_experiment (str) – A string that uniquely identifies the asset within a given experiment. If left unspecified, this will be automatically generated with reference to the key_within_module and the module_id arguments.
module_id (str) – Identifies the module with which the asset should be associated. If left blank, PsyNet will attempt to infer the module_id from the parent parameter, if provided.
personal (bool) – Whether the asset is ‘personal’ and hence omitted from anonymous database exports.
obfuscate (int) – Determines the extent to which the asset’s generated URL should be obfuscated. By default, obfuscate=1, which means that the URL contains a human-readable component containing useful metadata (e.g the participant ID), but also contains a randomly generated string so that malicious agents cannot retrieve arbitrary assets by guessing URLs. If obfuscate=0, then the randomly generated string is not added. If obfuscate=2, then the human-readable component is omitted, and only the random portion is kept. This might be useful in cases where you’re worried about participants cheating on the experiment by looking at file URLs.

md5_contents¶

Contains an automatically generated MD5 hash of the object’s contents, where ‘contents’ is liberally defined; it could mean hashing the file itself, or hashing the arguments of the function used to generate that file.

Type:: str

size_mb¶

The size of the asset’s file(s) (in MB).

Type:: float

deposit_time_sec¶

The time it took to deposit the asset.

Type:: float

needs_storage_backend¶

Whether the asset type needs a storage backend, e.g. a file server, or whether it can do without (e.g. in the case of an externally hosted resource accessible by a URL).

Type:: bool

psynet_version¶

The version of PsyNet used to create the asset.

Type:: str

deployment_id¶

A string used to identify the particular experiment deployment.

Type:: str

deposited¶

Whether the asset has been deposited yet.

Type:: bool

inherited¶

Whether the asset was inherited from a previous experiment, typically via the InheritedAssets functionality.

Type:: bool

inherited_from¶

Identifies the source of an inherited asset.

Type:: str

export_path¶

A relative path constructed from the key that will be used by default when the asset is exported.

Type:: str

participant_id¶

ID of the participant who ‘owns’ the asset, if applicable.

Type:: int

content_id¶

A token used for checking whether the contents of two assets are equivalent. This takes various forms depending on the asset type. For a file, the content_id would typically be a hash; for an externally hosted asset, it would be the URL, etc.

Type:: str

host_path¶

The filepath used to host the asset within the storage repository, if applicable.

Type:: str

url¶

The URL that can be used to access the asset from the perspective of the experiment front-end.

Type:: str

storage¶

The storage backend used for the asset.

Type:: AssetStorage

async_processes¶

Lists all async processes that have been created for the asset, including completed ones.

Type:: list

participant¶: If the parent is a Participant, returns that participant.

participants¶

Lists all participants associated with the asset.

Type:: list

trial¶: If the parent is a trial, returns that trial.

trials¶

Lists all trials associated with the asset.

Type:: list

node¶: If the parent is a Node, returns that participant.

nodes¶

Lists all nodes associated with the asset.

Type:: list

network¶: If the parent is a Network, returns that participant.

networks¶

Lists all networks associated with the asset.

Type:: list

errors¶

Lists the errors associated with the asset.

Type:: list

Linking assets to other database objects¶

PsyNet assets may be linked to other database objects. There are two kinds of links that may be used. First, an asset may possess a parent. This parental relationship is strict in the sense that an asset may not possess more than one parent.

However, in addition to the parental relationship, it is possible to link the asset to an arbitrary number of additional database objects. These latter links have a key-value construction, meaning that one can access a given asset by reference to a given key, for example: node.assets["response"].

Importantly, the same asset can have different keys for different objects; for example, it might be the response for one node, but the stimulus for another node. These latter relationships are instantiated with logic like the following:

participant.assets["stimulus"] = my_asset

creation_time¶: the time at which the Network was created.

delete_input()[source]¶: Deletes the input file(s) that make(s) up the asset.

details¶: a generic column for storing structured JSON data

id¶: a unique number for every entry. 1, 2, 3 and so on…

property1¶: a generic column that can be used to store experiment-specific details in String form.

property2¶: a generic column that can be used to store experiment-specific details in String form.

property3¶: a generic column that can be used to store experiment-specific details in String form.

property4¶: a generic column that can be used to store experiment-specific details in String form.

property5¶: a generic column that can be used to store experiment-specific details in String form.

type¶

vars¶

class psynet.asset.NoStorage[source]¶

Bases: AssetStorage

A ‘null’ storage back-end for assets that don’t require any storage.

class psynet.asset.OnDemandAsset(*args, **kwargs)[source]¶

Bases: FunctionAssetMixin, ExperimentAsset

An on-demand asset is an asset whose files are not stored directly in any storage back-end, but instead are created on demand when the asset is requested. This creation is typically triggered by making a call to the asset’s URL, accessible via the OnDemandAsset.url attribute.

Parameters:

function (callable) – A function responsible for generating the asset. The function should receive an argument called path and create a file or a folder at that path. It can also receive additional arguments specified via the arguments parameter.
local_key (str) – A string identifier for the asset, for example "stimulus". If provided, this string identifier should together with parent and module_id should uniquely identify that asset (i.e. no other asset should share that combination of properties).
arguments (dict) – An optional dictionary of arguments that should be passed to the function.
is_folder (bool) – Whether the asset is a folder.
description (str) – An optional longer string that provides further documentation about the asset.
data_type (str) – Experimental: the nature of the asset’s data. Could be used to determine visualization methods etc.
extension (str) – The file extension, if applicable.
key_within_module (str) – An optional key that uniquely identifies the asset within a given module. If left unspecified, this will be automatically generated with reference to the parent and the local_key arguments.
key_within_experiment (str) – A string that uniquely identifies the asset within a given experiment. If left unspecified, this will be automatically generated with reference to the key_within_module and the module_id arguments.
module_id (str) – Identifies the module with which the asset should be associated. If left blank, PsyNet will attempt to infer the module_id from the parent parameter, if provided.
parent (object) – The object that ‘owns’ the asset, if applicable, for example a Participant or a Node.
personal (bool) – Whether the asset is ‘personal’ and hence omitted from anonymous database exports.
obfuscate (int) – Determines the extent to which the asset’s generated URL should be obfuscated. By default, obfuscate=1, which means that the URL contains a human-readable component containing useful metadata (e.g the participant ID), but also contains a randomly generated string so that malicious agents cannot retrieve arbitrary assets by guessing URLs. If obfuscate=0, then the randomly generated string is not added. If obfuscate=2, then the human-readable component is omitted, and only the random portion is kept. This might be useful in cases where you’re worried about participants cheating on the experiment by looking at file URLs.

secret¶

A randomly generated string that is used to prevent malicious agents from guessing the asset’s URL. TODO - check whether the URL obfuscation functionality makes this redundant.

Type:: str

computation_time_sec¶

The time taken to generate the asset. TODO - check whether this is populated in practice.

Type:: float

psynet_version¶

The version of PsyNet used to create the asset.

Type:: str

deployment_id¶

A string used to identify the particular experiment deployment.

Type:: str

deposited¶

Whether the asset has been deposited yet.

Type:: bool

inherited¶

Whether the asset was inherited from a previous experiment, typically via the InheritedAssets functionality.

Type:: bool

inherited_from¶

Identifies the source of an inherited asset.

Type:: str

export_path¶

A relative path that will be used by default when the asset is exported.

Type:: str

participant_id¶

ID of the participant who ‘owns’ the asset, if applicable.

Type:: int

content_id¶

A token used for checking whether the contents of two assets are equivalent. This takes various forms depending on the asset type. For a file, the content_id would typically be a hash; for an externally hosted asset, it would be the URL, etc.

Type:: str

host_path¶

The filepath used to host the asset within the storage repository, if applicable.

Type:: str

url¶

The URL that can be used to access the asset from the perspective of the experiment front-end.

Type:: str

storage¶

The storage backend used for the asset.

Type:: AssetStorage

async_processes¶

Lists all async processes that have been created for the asset, including completed ones.

Type:: list

participant¶: If the parent is a Participant, returns that participant.

participants¶

Lists all participants associated with the asset.

Type:: list

trial¶: If the parent is a trial, returns that trial.

trials¶

Lists all trials associated with the asset.

Type:: list

node¶: If the parent is a Node, returns that participant.

nodes¶

Lists all nodes associated with the asset.

Type:: list

network¶: If the parent is a Network, returns that participant.

networks¶

Lists all networks associated with the asset.

Type:: list

errors¶

Lists the errors associated with the asset.

Type:: list

Linking assets to other database objects¶

PsyNet assets may be linked to other database objects. There are two kinds of links that may be used. First, an asset may possess a parent. This parental relationship is strict in the sense that an asset may not possess more than one parent.

However, in addition to the parental relationship, it is possible to link the asset to an arbitrary number of additional database objects. These latter links have a key-value construction, meaning that one can access a given asset by reference to a given key, for example: node.assets["response"].

Importantly, the same asset can have different keys for different objects; for example, it might be the response for one node, but the stimulus for another node. These latter relationships are instantiated with logic like the following:

participant.assets["stimulus"] = my_asset

creation_time¶: the time at which the Network was created.

details¶: a generic column for storing structured JSON data

id¶: a unique number for every entry. 1, 2, 3 and so on…

property1¶: a generic column that can be used to store experiment-specific details in String form.

property2¶: a generic column that can be used to store experiment-specific details in String form.

property3¶: a generic column that can be used to store experiment-specific details in String form.

property4¶: a generic column that can be used to store experiment-specific details in String form.

property5¶: a generic column that can be used to store experiment-specific details in String form.

type¶

vars¶

class psynet.asset.S3Storage(s3_bucket, root, backend='boto3')[source]¶

Bases: AssetStorage

A storage back-end that stores assets using Amazon Web Services’ S3 Storage system. This service is relatively inexpensive as long as your file collection does not number more than a few gigabytes. To use this service you will need to sign up for an Amazon Web Services account.

Parameters:

s3_bucket (str) – The name of the S3 bucket to use.
root (str) – The root directory within the bucket to use.
backend (str) – The backend to use for transferring files to S3. Can be either “boto3” or “awscli”. “awscli” relies on aws client being installed. It is faster than “boto3” (especially for uploading folders) but requires more dependencies which are not supported on Heroku. The default is “boto3”.

check_cache(host_path, is_folder, use_cache=None)[source]¶: Checks whether a file or folder is present in the remote bucket. Uses caching where appropriate for efficiency.

class psynet.asset.WebStorage[source]¶

Bases: AssetStorage

The notional storage back-end for external web-hosted assets.

psynet.asset.list_files_in_s3_bucket(bucket_name, prefix='')[source]¶

Lists files in an S3 bucket.

Parameters:

bucket_name (str) – Bucket to list files within.
prefix (str) – Only lists files whose keys begin with this string.

Returns:

A generator that yields keys.

Asset¶

Linking assets to other database objects¶

Linking assets to other database objects¶

Linking assets to other database objects¶

Linking assets to other database objects¶

Linking assets to other database objects¶

Linking assets to other database objects¶

Linking assets to other database objects¶