API Reference

This page is automatically generated from the docstrings in our code.

pyecoacc.models.pipeline

get_default_random_forest_pipeline()

Builds a default Random Forest classification pipeline (250 trees) with ACC stats features.

Returns:

Name	Type	Description
Model	Pipeline	A pipeline object with the default model.

Source code in pyecoacc/models/pipeline.py

def get_default_random_forest_pipeline():
    """
    Builds a default Random Forest classification pipeline (250 trees) with ACC stats features.

    Returns:
        Model (Pipeline): A pipeline object with the default model.
    """
    model = RandomForestClassifier(n_estimators=250, max_depth=10)
    features = ACCStatsTransformer()
    return make_classifier_pipeline(features, model, feature_scaler=False, feature_selector=False)

make_classifier_pipeline(features, model, feature_scaler=False, feature_selector=False, k_selection=25)

Make a custom classification pipeline with optional feature scaling and selection.

Parameters:

Name	Type	Description	Default
features	Transformer	transforms the raw data into features, for example the pyecoacc ACCStatsTransformer object.	required
model	Estimator	the classification model to use. For example, an sklearn RandomForestClassifier object.	required
feature_scaler	bool	If True, applies StandardScaler to the features. Defaults to False.	False
feature_selector	bool	if True, applies SelectKBest to the features. Defaults to False.	False
k_selection	int	The number of top features to select. Defaults to 25.	25

Returns:

Name	Type	Description
Model	Pipeline	A pipeline object with the specified model.

Source code in pyecoacc/models/pipeline.py

def make_classifier_pipeline(features, model, feature_scaler=False, feature_selector=False, k_selection=25):
    """Make a custom classification pipeline with optional feature scaling and selection.

    Args:
        features (sklearn.Transformer): transforms the raw data into features, for example the pyecoacc ACCStatsTransformer object.
        model (sklearn.Estimator): the classification model to use. For example, an sklearn RandomForestClassifier object. 
        feature_scaler (bool, optional): If True, applies StandardScaler to the features. Defaults to False.
        feature_selector (bool, optional): if True, applies SelectKBest to the features. Defaults to False.
        k_selection (int, optional): The number of top features to select. Defaults to 25.

    Returns:
        Model (Pipeline): A pipeline object with the specified model.
    """

    steps = [
        ('features', features),
        ('model', model)
    ]

    if feature_scaler:
        scaling_step = ('scaler', StandardScaler())
        steps.insert(1, scaling_step)

    if feature_selector:
        selection_step = ('selection', SelectKBest(score_func=f_classif, k=k_selection))
        steps.insert(1, selection_step)

    return Pipeline(steps)

pyecoacc.models.deep.cnn

BehaviorCNNClassifier(num_classes, sequence_length, conv_filters=[32, 64, 128, 256], fc_layers=[256, 512], kernel_size=5)

Bases: Module

A Convolutional Neural Network for classifying behaviors from accelerometer data.

Parameters:

Name	Type	Description	Default
num_classes	int	the number of behavior classes to predict.	required
sequence_length	int	the length of the input accelerometer sequence.	required
conv_filters	list	the number of filters in each convolutional block. Defaults to [32, 64, 128, 256].	[32, 64, 128, 256]
fc_layers	list	the size of each fully connected layer. Defaults to [256, 512].	[256, 512]
kernel_size	int	the kernel size for convolutional layers. Defaults to 5.	5

Source code in pyecoacc/models/deep/cnn.py

def __init__(self, num_classes, sequence_length, conv_filters=[32, 64, 128, 256], 
             fc_layers=[256, 512], kernel_size=5):
    """
    Args:
        num_classes (int): the number of behavior classes to predict.
        sequence_length (int): the length of the input accelerometer sequence.
        conv_filters (list, optional): the number of filters in each convolutional block. Defaults to [32, 64, 128, 256].
        fc_layers (list, optional): the size of each fully connected layer. Defaults to [256, 512].
        kernel_size (int, optional): the kernel size for convolutional layers. Defaults to 5.
    """
    super().__init__()

    self.conv_blocks = nn.ModuleList()
    in_channels = 3  # XYZ 

    # 1. Dynamically build Convolutional Blocks
    for out_channels in conv_filters:
        block = nn.Sequential(
            nn.Conv1d(in_channels, out_channels, kernel_size=kernel_size, stride=1, padding=kernel_size//2),
            nn.BatchNorm1d(out_channels),
            nn.ReLU(),
            nn.MaxPool1d(kernel_size=2, stride=2),
            nn.Dropout(0.4)
        )
        self.conv_blocks.append(block)
        in_channels = out_channels

    self.flattened_size = self._get_flatten_size(sequence_length)

    # 2. Dynamically build Fully Connected Layers
    self.fc_blocks = nn.ModuleList()
    curr_features = self.flattened_size

    for hidden_units in fc_layers:
        self.fc_blocks.append(nn.Linear(curr_features, hidden_units))
        self.fc_blocks.append(nn.ReLU())
        self.fc_blocks.append(nn.Dropout(0.4))
        curr_features = hidden_units

    # Final Output Layer
    self.output_layer = nn.Linear(curr_features, num_classes)

CNNInputReshaper

Bases: BaseEstimator, TransformerMixin

Reshapes input data for CNN processing of accelerometer data. Transforms 2D input (n_samples, 3*sequence_length) into 3D output (n_samples, 3, sequence_length) for CNN input. This is used as a first step in an sklearn pipeline to generate sklearn-compatible CNN models.

make_cnn_model(sequence_length, num_behav, conv_filters=[32, 64, 128, 256], fc_layers=[256, 512], kernel_size=5, max_epoch=200, lr=0.001, l2=0.0005, verbose=1, validation=0.2, patience=50, allow_cuda=True)

Generate an sklearn-compatible model from a CNN specification

Parameters:

Name	Type	Description	Default
num_classes	int	the number of behavior classes to predict.	required
sequence_length	int	the length of the input accelerometer sequence.	required
conv_filters	list	the number of filters in each convolutional block. Defaults to [32, 64, 128, 256].	[32, 64, 128, 256]
fc_layers	list	the size of each fully connected layer. Defaults to [256, 512].	[256, 512]
kernel_size	int	the kernel size for convolutional layers. Defaults to 5.	5
max_epoch	int	Maximum number of epochs used for training the model. Defaults to 200.	200
lr	float	learning rate. Defaults to .001.	0.001
l2	float	regularization strength. Defaults to 5e-4.	0.0005
verbose	int	specifies verbosity level. Defaults to 1.	1
validation	float	fraction of data used for validation. Defaults to .2.	0.2
patience	int	number of epochs to wait before early stopping. Defaults to 50.	50
allow_cuda	bool	whether to use CUDA if available. Defaults to True.	True

Returns:

Name	Type	Description
Model	Pipeline	The CNN model wrapped in an sklearn Pipeline.

Source code in pyecoacc/models/deep/cnn.py

def make_cnn_model(sequence_length, num_behav, 
                   conv_filters=[32, 64, 128, 256], 
                   fc_layers=[256, 512], 
                   kernel_size=5,
                   max_epoch=200, lr=.001, l2=5e-4, verbose=1, validation=.2, patience=50, allow_cuda=True):
    """Generate an sklearn-compatible model from a CNN specification

    Args:
        num_classes (int): the number of behavior classes to predict.
        sequence_length (int): the length of the input accelerometer sequence.
        conv_filters (list, optional): the number of filters in each convolutional block. Defaults to [32, 64, 128, 256].
        fc_layers (list, optional): the size of each fully connected layer. Defaults to [256, 512].
        kernel_size (int, optional): the kernel size for convolutional layers. Defaults to 5.
        max_epoch (int, optional): Maximum number of epochs used for training the model. Defaults to 200.
        lr (float, optional): learning rate. Defaults to .001.
        l2 (float, optional): regularization strength. Defaults to 5e-4.
        verbose (int, optional): specifies verbosity level. Defaults to 1.
        validation (float, optional): fraction of data used for validation. Defaults to .2.
        patience (int, optional): number of epochs to wait before early stopping. Defaults to 50.
        allow_cuda (bool, optional): whether to use CUDA if available. Defaults to True.

    Returns:
        Model (Pipeline): The CNN model wrapped in an sklearn Pipeline.
    """

    net = NeuralNetClassifier(
        module=BehaviorCNNClassifier,
        module__conv_filters=conv_filters,
        module__fc_layers=fc_layers,
        module__kernel_size=kernel_size,  
        module__num_classes=num_behav,
        module__sequence_length=sequence_length,
        criterion=nn.CrossEntropyLoss,
        optimizer__weight_decay=l2,

        max_epochs=max_epoch,
        lr=lr,
        optimizer=torch.optim.Adam,
        train_split=ValidSplit(validation) if validation is not None else validation,

        callbacks=[
            EarlyStopping(monitor='valid_acc', lower_is_better=False, patience=patience, load_best=True),
            Checkpoint(monitor='valid_acc_best')
        ],

        verbose=verbose,
        device='cuda' if torch.cuda.is_available() and allow_cuda else 'cpu'
    )

    return Pipeline([
        ('reshape', CNNInputReshaper()),
        ('CNN', net)
    ])