motornet.task#

class motornet_tf.tasks.CentreOutReach(network, name: str = 'CentreOutReach', angular_step: float = 15, catch_trial_perc: float = 50, reaching_distance: float = 0.1, start_position: list | tuple | ndarray | None = None, deriv_weight: float = 0.0, go_cue_range: list | tuple | ndarray = (0.05, 0.25), **kwargs)#

Bases: Task

During training, the network will perform random reaches. During validation, the network will perform centre-out reaching movements.

Parameters:

  • network – motornet.nets.layers.Network object class or subclass. This is the network that will perform the task.

  • name – String, the name of the task object instance.

  • angular_step – Float, the angular distance (deg) between each centre-out reach during validation. For instance, if this is 45, the Task object will ask the network to perform reaches in 8 directions equally distributed around the center position.

  • catch_trial_perc – Float, the percentage of catch trials during training. A catch trial is a trial where no go-cue occurs, ensuring the network has to learn to wait for the go cue to actually occur without trying to “anticipate” the timing of the go-cue.

  • reaching_distance – Float, the reaching distance (m) for each centre-out reach during validation.

  • start_position – List, tuple or numpy.ndarray, indicating the start position around which the centre-out reaches will occur during validation. There should be as many elements as degrees of freedom in the plant. If None, the start position will be defined as the center of the joint space, based on the joint limits of the plant.

  • deriv_weight – Float, the weight of the muscle activation’s derivative contribution to the default muscle L2 loss.

  • go_cue_range – Two-items list, tuple or numpy.ndarray, indicating the lower and upper range of the time window (sec) in which the go cue may be presented. The go cue timing is randomly drawn from a uniform distribution bounded by these values.

  • **kwargs – This is passed as-is to the parent Task class.

generate(batch_size, n_timesteps, validation: bool = False)#

Generates inputs, targets, and initial states to be passed to the model.fit call.

Parameters:

  • batch_size – Integer, the batch size to use to create the inputs, targets, and initial states.

  • n_timesteps – Integer, the number of timesteps to use to create the inputs and targets. Initial states do not require a time dimension.

  • validation – Boolean, whether to generate trials for validation purposes or not (as opposed to training purposes). This is useful when one wants to test a network’s performance in a set of trial types that are not the same as those used for training.

Returns:

  • A dictionary to use as input to the model. Each value in the dictionary should be a tensor array. At the very least, the dictionary should contain a “inputs” key mapped to a tensor array, which will be passed as-is to the network’s input layer. Additional keys will be passed and handled didderently depending on what the Network passed at initialization does when it is called.

  • A tensor array of target values, that will be passed to all losses as the y_true input to compute loss values.

  • A list of initial state as tensor arrays, compatible with the initial_joint_state value set at initialization.

class motornet_tf.tasks.DelayedReach(network, name: str = 'DelayedReach', delay_range: list | tuple = (0.3, 0.6), deriv_weight: float = 0.0, **kwargs)#

Bases: Task

A random-delay reach to a random target from a random starting position.

Parameters:

  • network – motornet.nets.layers.Network object class or subclass. This is the network that will perform the task.

  • name – String, the name of the task object instance.

  • deriv_weight – Float, the weight of the muscle activation’s derivative contribution to the default muscle L2 loss.

  • delay_range – Two-items list, tuple or numpy.ndarray, indicating the lower and upper range of the time window (sec) in which the go cue may be presented. The delay is randomly drawn from a uniform distribution bounded by these values.

  • **kwargs – This is passed as-is to the parent Task class.

generate(batch_size, n_timesteps, validation: bool = False)#

Generates inputs, targets, and initial states to be passed to the model.fit call.

Parameters:

  • batch_size – Integer, the batch size to use to create the inputs, targets, and initial states.

  • n_timesteps – Integer, the number of timesteps to use to create the inputs and targets. Initial states do not require a time dimension.

  • validation – Boolean, whether to generate trials for validation purposes or not (as opposed to training purposes). This is useful when one wants to test a network’s performance in a set of trial types that are not the same as those used for training.

Returns:

  • A dictionary to use as input to the model. Each value in the dictionary should be a tensor array. At the very least, the dictionary should contain a “inputs” key mapped to a tensor array, which will be passed as-is to the network’s input layer. Additional keys will be passed and handled didderently depending on what the Network passed at initialization does when it is called.

  • A tensor array of target values, that will be passed to all losses as the y_true input to compute loss values.

  • A list of initial state as tensor arrays, compatible with the initial_joint_state value set at initialization.

class motornet_tf.tasks.RandomTargetReach(network, name: str = 'RandomTargetReach', deriv_weight: float = 0.0, **kwargs)#

Bases: Task

A reach to a random target from a random starting position.

Parameters:

  • network – motornet.nets.layers.Network object class or subclass. This is the network that will perform the task.

  • name – String, the name of the task object instance.

  • deriv_weight – Float, the weight of the muscle activation’s derivative contribution to the default muscle L2 loss.

  • **kwargs – This is passed as-is to the parent Task class.

generate(batch_size, n_timesteps, validation: bool = False)#

Generates inputs, targets, and initial states to be passed to the model.fit call.

Parameters:

  • batch_size – Integer, the batch size to use to create the inputs, targets, and initial states.

  • n_timesteps – Integer, the number of timesteps to use to create the inputs and targets. Initial states do not require a time dimension.

  • validation – Boolean, whether to generate trials for validation purposes or not (as opposed to training purposes). This is useful when one wants to test a network’s performance in a set of trial types that are not the same as those used for training.

Returns:

  • A dictionary to use as input to the model. Each value in the dictionary should be a tensor array. At the very least, the dictionary should contain a “inputs” key mapped to a tensor array, which will be passed as-is to the network’s input layer. Additional keys will be passed and handled didderently depending on what the Network passed at initialization does when it is called.

  • A tensor array of target values, that will be passed to all losses as the y_true input to compute loss values.

  • A list of initial state as tensor arrays, compatible with the initial_joint_state value set at initialization.

class motornet_tf.tasks.RandomTargetReachWithLoads(network, endpoint_load: float | list | tuple | ndarray, name: str = 'RandomTargetReachWithLoads', deriv_weight: float = 0.0, **kwargs)#

Bases: Task

A reach to a random target from a random starting position, with loads applied at the skeleton’s endpoint.

Parameters:

  • network – motornet.nets.layers.Network object class or subclass. This is the network that will perform the task.

  • endpoint_load – Float, or K-items list, tuple or numpy.ndarray, with K the space_dim attribute of the motornet.plants.skeletons.Skeleton object class or subclass, i.e., the dimensionality of the worldspace. Each element k in K indicates the the load (N) to apply to the skeleton’s endpoint for the k-th worldspace dimension. If a float is given, that load is applied to all dimensions.

  • name – String, the name of the task object instance.

  • deriv_weight – Float, the weight of the muscle activation’s derivative contribution to the default muscle L2 loss.

  • **kwargs – This is passed as-is to the parent Task class.

generate(batch_size, n_timesteps, validation: bool = False)#

Generates inputs, targets, and initial states to be passed to the model.fit call.

Parameters:

  • batch_size – Integer, the batch size to use to create the inputs, targets, and initial states.

  • n_timesteps – Integer, the number of timesteps to use to create the inputs and targets. Initial states do not require a time dimension.

  • validation – Boolean, whether to generate trials for validation purposes or not (as opposed to training purposes). This is useful when one wants to test a network’s performance in a set of trial types that are not the same as those used for training.

Returns:

  • A dictionary to use as input to the model. Each value in the dictionary should be a tensor array. At the very least, the dictionary should contain a “inputs” key mapped to a tensor array, which will be passed as-is to the network’s input layer. Additional keys will be passed and handled didderently depending on what the Network passed at initialization does when it is called.

  • A tensor array of target values, that will be passed to all losses as the y_true input to compute loss values.

  • A list of initial state as tensor arrays, compatible with the initial_joint_state value set at initialization.

class motornet_tf.tasks.Task(network, initial_joint_state=None, name: str = 'Task')#

Bases: Sequence

Base class for tasks.

Parameters:

  • network – motornet.nets.layers.Network object class or subclass. This is the network that will perform the task.

  • initial_joint_state –

    Tensor or numpy.ndarray, the desired initial joint states for the task, if a single set of pre-defined initial joint states is desired. If None, the initial joint states will be drawn from the motornet.nets.layers.Network.get_initial_state method at each call of generate().

    This parameter will be ignored on generate() calls where a joint_state is provided as input argument.

  • name – String, the name of the task object instance.

add_loss(assigned_output, loss, loss_weight=1.0, name=None)#

Add a loss to optimize during training.

Parameters:

  • assigned_output – String, the output state that the loss will be applied to. This should correspond to an output name from the Network object instance passed at initialization. The output names can be retrieved via the motornet.nets.layers.Network.output_names attribute.

  • loss – tensorflow.python.keras.losses.Loss object class or subclass. Loss subclasses specific to MotorNet are available in the motornet.nets.losses module.

  • loss_weight – Float, the weight of the loss when all contributing losses are added to the total loss.

  • name – String, the name (label) to give to the loss object. This is used to print, plot, and save losses during training.

Raises:

ValueError – If the assigned_output passed does not match any network output name.

abstract generate(batch_size, n_timesteps, validation: bool = False)#

Generates inputs, targets, and initial states to be passed to the model.fit call.

Parameters:

  • batch_size – Integer, the batch size to use to create the inputs, targets, and initial states.

  • n_timesteps – Integer, the number of timesteps to use to create the inputs and targets. Initial states do not require a time dimension.

  • validation – Boolean, whether to generate trials for validation purposes or not (as opposed to training purposes). This is useful when one wants to test a network’s performance in a set of trial types that are not the same as those used for training.

Returns:

  • A dictionary to use as input to the model. Each value in the dictionary should be a tensor array. At the very least, the dictionary should contain a “inputs” key mapped to a tensor array, which will be passed as-is to the network’s input layer. Additional keys will be passed and handled didderently depending on what the Network passed at initialization does when it is called.

  • A tensor array of target values, that will be passed to all losses as the y_true input to compute loss values.

  • A list of initial state as tensor arrays, compatible with the initial_joint_state value set at initialization.

get_attributes()#

Gets all non-callable attributes declared in the object instance, except for loss-related attributes.

Returns:

  • A list of attribute names as string elements.

  • A list of attribute values.

get_initial_state(batch_size, joint_state=None)#

Computes initial state instances that are biomechanically compatible with each other.

Parameters:

  • batch_size – Integer, the batch size defining the size of each state’s first dimension.

  • joint_state – The joint state from which the other state values are inferred. If provided, this is passed as-is to the motornet.nets.layers.Network.get_initial_state() method, and therefore obeys the logic documented there. If not provided and an initial_joint_state was defined at initialization, that:attr:initial_joint_state will be passed instead. If neither is provided, then None is passed as “input” argument.

Returns:

A ‘list’ containing the output of the motornet.nets.layers.Network.get_initial_state() method, which is usually a tensor array per state.

get_initial_state_layers()#

Creates tensorflow.keras.layers.Input layers to build the entrypoint layers of the network states. See the tensorflow documentation for more information about what tensorflow.keras.layers.Input objects do. Below is an example code using the current method to create a model. See get_input_dict_layers() for more information about how to create a set of input layers for network inputs.

import motornet as mn
import tensorflow as tf

plant = mn.plants.ReluPointMass24()
network = mn.nets.layers.GRUNetwork(plant=plant, n_units=50)
task = mn.tasks.CentreOutReach(network=network)

rnn = tf.keras.layers.RNN(cell=network, return_sequences=True)

inputs = task.get_input_dict_layers()
state_i = task.get_initial_state_layers()
state_f = rnn(inputs, initial_state=state_i)
Returns:

A list of tensorflow.keras.layers.Input object instances with dimensionality corresponding to the (initial) states provided by the motornet.nets.layers.Network object instance passed at initialization.

get_input_dict_layers()#

Creates tensorflow.keras.layers.Input layers to build the entrypoint layers of the network inputs. See the tensorflow documentation for more information about what tensorflow.keras.layers.Input objects do. Below is an example code using the current method to create a model. See get_initial_state_layers() for more information about how to create a set of input layers for initial states.

import motornet as mn
import tensorflow as tf

plant = mn.plants.ReluPointMass24()
network = mn.nets.layers.GRUNetwork(plant=plant, n_units=50)
task = mn.tasks.CentreOutReach(network=network)

rnn = tf.keras.layers.RNN(cell=network, return_sequences=True)

inputs = task.get_input_dict_layers()
state_i = task.get_initial_state_layers()
state_f = rnn(inputs, initial_state=state_i)
Returns:

A dictionary, with the same keys as the inputs dictionary from the generate() method. These keys are mapped onto tensorflow.keras.layers.Input object instances with dimensionality corresponding to the inputs provided in the inputs dictionary from the generate() method.

get_input_dim()#

Gets the dimensionality of each value in the input dictionary produced by the generate() method.

Returns:

A dictionary with keys corresponding to those of the input dictionary produced by the generate() method, mapped to lists indicating the dimensionality (shape) of each value in the input dictionary.

get_losses()#

Gets the currently declared losses and their corresponding loss weight.

Returns:

  • A dictionary containing loss objects.

  • A dictionary containing float values corresponding to each loss’ weight.

get_save_config()#

Gets the task object’s configuration as a dictionary.

Returns:

A dictionary containing the parameters of the task’s configuration. All parameters held as non-callbale attributes by the object instance will be included in the dictionary.

print_attributes()#

Prints all non-callable attributes declared in the object instance, except for loss-related attributes. To print loss-related attributes, see print_losses().

print_losses()#

Prints all currently declared losses in a readable format, including the default losses declared at initialization. This method prints the assigned output, loss object instance, loss weight and loss name of each loss. It also specifies if each loss is part of a compounded loss or not.

set_training_params(batch_size, n_timesteps)#

Sets default training parameters for the generate() call. These will be overridden if the generate() method is called with alternative values for these parameters.

Parameters:

  • batch_size – Integer, the batch size to use to create the inputs, targets, and initial states.

  • n_timesteps – Integer, the number of timesteps to use to create the inputs and targets. Initial states do not require a time dimension.