Sequence Model#

Extensions that are used for training and running inference with the sequence model.

Accessor: sequence

DataFrame Extensions#

These can be called on the DataFrame

class animal_soup.SequenceModelDataframeExtension(df)#

Pandas dataframe extensions for training the sequence model.

train(mode='fast', batch_size=32, gpu_id=0, initial_lr=0.0001, stop_method='learning_rate', model_in=None, model_out=None, ethogram_mode='inference')#

Method for training the sequence model with trials in the current dataframe.

Note: In order to train the sequence model. You will have to done feature extractor inference. This can be done using a for-loop and doing feature extractor inference on each row. For example:

for ix, row in df.iterrows():
    row.feature_extractor.infer()
Parameters:

  • mode (str, default "fast") – One of [“slow”, “medium”, “fast”]. Indicates which pre-trained TGMJ model to use for training. Argument will be ignored if using non-default pre-trained model checkpoint for training.

  • batch_size (int, default 32) – Batch size.

  • gpu_id (int, default 0) – Specify which gpu to use for training the model.

  • initial_lr (float, default 0.0001) – Initial learning rate.

  • stop_method (str, default learning_rate) –

    Method for stopping training. Argument must be one of [“learning_rate”, “num_epochs”]

    stop method

    description

    learning_rate

    Stop training when learning rate drops below a given threshold, means loss has stopped improving

    num_epochs

    Stop training after a given number of epochs

  • model_in (str or Path, default None) – If you want to retrain the model using different model weights than the default. User can provide a location to a different model checkpoint. For example, if you had retrained the sequence model previously and wanted to use those weights instead.

  • model_out (str or Path, default None) – User provided location of where to store model output such as model checkpoint with updated weights, hdf5 file with model results/metrics, etc. Should be a directory. By default, the model output will get stored in the same directory as the dataframe.

  • ethogram_mode (str, default 'inference') – One of [“inference”, “ground”]. Specifies the location of where to look for ground truth ethograms for training. If “inference”, will try to use ethograms stored from running inference. If “ground”, will look for a column in the dataframe called “ethograms” to use for training.

Series Extensions#

These can be called on an individual Series, or rows, of the DataFrame

class animal_soup.SequenceModelSeriesExtensions(s)#

Pandas series extensions for inference of the sequence model.

Parameters:

s (Series) –

infer(mode='fast', model_in=None, gpu_id=0)#

Note: Every sequence model is a TGMJ model. However, depending on the architecture used for training the flow generator and feature extractor model the sequence model can have highly variable results. You should specify the mode to match the mode you used for inference with the feature extractor.

Parameters:

  • mode (str, default 'fast') –

    One of [“slow”, “medium”, “fast”]. Indicates what sequence model and thresholds to use. Should match the mode that was used when doing feature extraction.

    mode

    flow model

    feature model

    sequence model

    slow

    TinyMotionNet

    ResNet3D-34

    TGMJ

    medium

    MotionNet

    ResNet50

    TGMJ

    fast

    TinyMotionNet3D

    ResNet18

    TGMJ

  • model_in (str or Path, default None) – If you want to use your own model instead of the default you can provide a location to a different model checkpoint. For example, if you retrained the sequence model for a new behavioral task or setup and want to use those weights for inference instead of the default models.

  • gpu_id (int, default 0) – Specify which gpu to use for training the model.