5.3. UCTB.model_unit package

5.3.1. UCTB.model_unit.BaseModel module

class UCTB.model_unit.BaseModel.BaseModel(code_version, model_dir, gpu_device)

Bases: object

BaseModel is the base class for many models, such as STMeta, ST-MGCN and ST_ResNet,

you can also build your own model using this class. More information can be found in tutorial.

Parameters
  • code_version – Current version of this model code, which will be used as filename for saving the model.

  • model_dir – The directory to store model files. Default:’model_dir’.

  • gpu_device – To specify the GPU to use. Default: ‘0’.

build(init_vars=True, max_to_keep=5)
Args

init_vars(bool): auto init the parameters if set to True, else no parameters will be initialized. max_to_keep: max file to keep, which equals to max_to_keep in tf.train.Saver.

close()

Close the session, release memory.

fit(sequence_length, output_names=('loss', ), op_names=('train_op', ), evaluate_loss_name='loss', batch_size=64, max_epoch=10000, validate_ratio=0.1, shuffle_data=True, early_stop_method='t-test', early_stop_length=10, early_stop_patience=0.1, verbose=True, save_model=True, save_model_name=None, auto_load_model=True, return_outputs=False, **kwargs)
Parameters
  • sequence_length – int, the sequence length which is use in mini-batch training

  • output_names – list, [output_tensor1_name, output_tensor1_name, …]

  • op_names – list, [operation1_name, operation2_name, …]

  • evaluate_loss_name – str, should be on of the output_names, evaluate_loss_name was use in early-stopping

  • batch_size – int, default 64, batch size

  • max_epoch – int, default 10000, max number of epochs

  • validate_ratio – float, default 0.1, the ration of data that will be used as validation dataset

  • shuffle_data – bool, default True, whether shuffle data in mini-batch train

  • early_stop_method – should be ‘t-test’ or ‘naive’, both method are explained in train.EarlyStopping

  • early_stop_length – int, must provide when early_stop_method=’t-test’

  • early_stop_patience – int, must provide when early_stop_method=’naive’

  • verbose – Bool, flag to print training information or not

  • save_model – Bool, flog to save model or not

  • save_model_name – String, filename for saving the model, which will overwrite the code_version.

  • auto_load_model – Bool, the “fit” function will automatically load the model from disk, if exists, before the training. Set to False to disable the auto-loading.

  • return_outputs – Bool, set True to return the training log, otherwise nothing will be returned

load(subscript)
Parameters

subscript – String, subscript will be appended to the code version as the model file name, and load the corresponding model using this filename

load_event_scalar(scalar_name='val_loss')
Parameters

scalar_name – load the corresponding scalar name from tensorboard-file, e.g. load_event_scalar(‘val_loss)

predict(sequence_length, output_names=('prediction', ), cache_volume=64, **kwargs)
Parameters
  • output_names – list, [output_tensor_name1, output_tensor_name2, …]

  • sequence_length – int, the length of sequence, which is use in mini-batch training

  • cache_volume – int, default 64, we need to set cache_volume if the cache can not hold the whole validation dataset

:param : return: outputs_dict: dict, like {output_tensor1_name: output_tensor1_value, …}

save(subscript, global_step)
Parameters
  • subscript – String, subscript will be appended to the code version as the model filename, and save the corresponding model using this filename

  • global_step – Int, current training steps

5.3.2. UCTB.model_unit.DCRNN_CELL module

class UCTB.model_unit.DCRNN_CELL.DCGRUCell(num_units, input_dim, num_graphs, supports, max_diffusion_step, num_nodes, num_proj=None, activation=<function tanh>, reuse=None, use_gc_for_ru=True, name=None)

Bases: tensorflow.python.ops.rnn_cell_impl.RNNCell

Graph Convolution Gated Recurrent Unit cell.

call(inputs, **kwargs)

This is where the layer’s logic lives.

Parameters
  • inputs – Input tensor, or list/tuple of input tensors.

  • **kwargs – Additional keyword arguments.

Returns

A tensor or list/tuple of tensors.

compute_output_shape(input_shape)

Computes the output shape of the layer.

Assumes that the layer will be built to match that input shape provided.

Parameters

input_shape – Shape tuple (tuple of integers) or list of shape tuples (one per output tensor of the layer). Shape tuples can include None for free dimensions, instead of an integer.

Returns

An input shape tuple.

property output_size

size of outputs produced by this cell.

Type

Integer or TensorShape

property state_size

size(s) of state(s) used by this cell.

It can be represented by an Integer, a TensorShape or a tuple of Integers or TensorShapes.

5.3.3. UCTB.model_unit.GraphModelLayers module

class UCTB.model_unit.GraphModelLayers.GAL

Bases: object

This class provides static methods for adding Graph Attention Layer.

static add_ga_layer_matrix(inputs, units, num_head, activation=<function tanh>)

This method use Multi-head attention technique to add Graph Attention Layer.

Parameters
  • input (ndarray) – The set of node features data, with shape [batch, num_node, num_featuer].

  • unit (int) – The number of merge_gal_units used in GAL.

  • num_head (int) – The number of multi-head used in GAL.

  • activation (function) – activation function. default:tf.nn.tanh.

Returns

The weight matrix after softmax function. gc_output: The final GAL aggregated feature representation from input feature.

Return type

alpha

static add_residual_ga_layer(inputs, units, num_head, activation=<function tanh>)

Call the add_ga_layer_matrix function to build the Graph Attention Layer, and add the residual layer to optimize the deep neural network.

static attention_merge_weight(inputs, units, num_head, activation=<function leaky_relu>)
class UCTB.model_unit.GraphModelLayers.GCL

Bases: object

This class provides static methods for adding Graph Convolution Layer.

static add_gc_layer(inputs, gcn_k, laplacian_matrix, output_size, dtype=tf.float32, use_bias=True, trainable=True, initializer=None, regularizer=None, activation=<function tanh>)
Parameters
  • Input (ndarray) – The input features with shape [batch, num_node, num_feature].

  • gcn_k (int) – The highest order of Chebyshev Polynomial approximation in GCN.

  • laplacian_matrix (ndarray) – Laplacian matrix used in GCN, with shape [num_node, num_node].

  • output_size (int) – Number of output channels.

  • dtype – Data type. default:tf.float32.

  • use_bias (bool) – It determines whether to add bias in the output. default:True.

  • trainable (bool) – It determines whether weights tensor can be trained. default:True.

  • initializer – It determines whether the “weight” tensor is initialized. default:None.

  • regularizer – It determines whether the “weight” tensor is regularized. default:None.

  • activation (function) – activation function. default:tf.nn.tanh.

Returns

Returns the result of convolution of inputs and laplacian_matrix

static add_multi_gc_layers(inputs, gcn_k, gcn_l, output_size, laplacian_matrix, activation=<function tanh>)

Call add_gc_layer function to add multi Graph Convolution Layer.`gcn_l` is the number of layers added.

class UCTB.model_unit.GraphModelLayers.GraphBuilder

Bases: object

This class provides static methods for transforming raw data into various graphs. eg: correlation, distance, interaction graph.

static adjacent_to_laplacian(adjacent_matrix)

Turn adjacent_matrix into Laplace matrix.

static correlation_adjacent(traffic_data, threshold)

Calculate correlation graph based on pearson coefficient.

Parameters
  • traffic_data (ndarray) – numpy array with shape [sequence_length, num_node].

  • threshold (float) – float between [-1, 1], nodes with Pearson Correlation coefficient larger than this threshold will be linked together.

static distance_adjacent(lat_lng_list, threshold)

Calculate distance graph based on geographic distance.

Parameters
  • lat_lng_list (list) – A list of geographic locations. The format of each element in the list is [latitude, longitude].

  • threshold (float) – (meters) nodes with geographic distacne smaller than this threshold will be linked together.

static haversine(lat1, lon1, lat2, lon2)

Calculate the great circle distance between two points on the earth (specified in decimal degrees)

static interaction_adjacent(interaction_matrix, threshold)

Binarize interaction_matrix based on threshold.

Parameters
  • interaction_matrix (ndarray) –

    with shape [num_node, num_node], where each element represents the number of interactions during a certain time,

    e.g. 6 monthes, between the corresponding nodes.

  • threshold (float or int) – nodes with number of interactions between them greater than this threshold will be linked together.

5.3.4. UCTB.model_unit.ST_RNN module

class UCTB.model_unit.ST_RNN.GCLSTMCell(units, num_nodes, laplacian_matrix, gcn_k=1, gcn_l=1, **kwargs)

Bases: tensorflow.python.keras.layers.recurrent.LSTMCell

GCLSTMCell is one of our implemented ST-RNN models in handling the spatial and temporal features. We performed GCN on both LSTM inputs and hidden-states. The code is inherited from tf.keras.layers.LSTMCell, thus it can be used almost the same as LSTMCell except that you need to provide the GCN parameters in the __init__ function.

Parameters
  • units (int) – number of units of LSTM

  • num_nodes (int) – number of nodes in the graph

  • laplacian_matrix (ndarray) – laplacian matrix used in GCN, with shape [num_node, num_node]

  • gcn_k (int) – highest order of Chebyshev Polynomial approximation in GCN

  • gcn_l (int) – number of GCN layers

  • kwargs – other parameters supported by LSTMCell, such as activation, kernel_initializer … and so on.

call(inputs, states, training=None)

This is where the layer’s logic lives.

Parameters
  • inputs – Input tensor, or list/tuple of input tensors.

  • **kwargs – Additional keyword arguments.

Returns

A tensor or list/tuple of tensors.