Developer Guide

Codebase Structure

The codebase is organized in a modular, datatype / feature centric way so that adding a feature for a new datatype is pretty straightforward and requires isolated code changes. All the datatype specific logic lives in the corresponding feature module all of which are under ludwig/features/.

Feature classes contain raw data preprocessing logic specific to each data type. All input (output) features implement build_input (build_output) method which is used to build encodings (decode outputs). Output features also contain datatype-specific logic to compute output measures such as loss, accuracy, etc.

Encoders and decoders are modularized as well (they are under ludwig/models/modules) so that they can be used by multiple features. For example sequence encoders are shared among text, sequence, and timeseries features.

Various model architecture components which can be reused are also split into dedicated modules, for example convolutional modules, fully connected modules, etc.

Bulk of the training logic resides in ludwig/models/model.py which initializes a tensorflow session, feeds the data, and executes training.

Adding an Encoder

1. Add a new encoder class

Source code for encoders lives under ludwig/models/modules.New encoder objects should be defined in the corresponding files, for example all new sequence encoders should be added to ludwig/models/modules/sequence_encoders.py.

All the encoder parameters should be provided as arguments in the constructor with their default values set. For example RNN encoder takes the following list of arguments in its constructor:

  1. def __init__(
  2.     self,
  3.     should_embed=True,
  4.     vocab=None,
  5.     representation='dense',
  6.     embedding_size=256,
  7.     embeddings_trainable=True,
  8.     pretrained_embeddings=None,
  9.     embeddings_on_cpu=False,
  10.     num_layers=1,
  11.     state_size=256,
  12.     cell_type='rnn',
  13.     bidirectional=False,
  14.     dropout=False,
  15.     initializer=None,
  16.     regularize=True,
  17.     reduce_output='last',
  18.     **kwargs
  19. ):

Typically all the dependencies are initialized in the encoder's constructor (in the case of the RNN encoder these are EmbedSequence and RecurrentStack modules) so that at the end of the constructor call all the layers are fully described.

Actual creation of tensorflow variables takes place inside the call method of the encoder. All encoders should have the following signature:

  1. __call__(
  2.     self,
  3.     input_placeholder,
  4.     regularizer,
  5.     dropout,
  6.     is_training
  7. )

Inputs

  • input_placeholder (tf.Tensor): input tensor.
  • regularizer (A (Tensor -> Tensor or None) function): regularizer function passed to tf.get_variable method.
  • dropout (tf.Tensor(dtype: tf.float32)): dropout rate.

  • is_training (tf.Tensor(dtype: tf.bool), default: True): boolean indicating whether this is a training dataset. Return

  • hidden (tf.Tensor(dtype: tf.float32)): feature encodings.

  • hidden_size (int): feature encodings size. Encoders are initialized as class member variables in input feature object constructors and called inside build_input methods.

2. Add the new encoder class to the corresponding encoder registry

Mapping between encoder keywords in the model definition and encoder classes is done by encoder registries: for example sequence encoder registry is defined in ludwig/features/sequence_feature.py

  1. sequence_encoder_registry = {
  2.     'stacked_cnn': StackedCNN,
  3.     'parallel_cnn': ParallelCNN,
  4.     'stacked_parallel_cnn': StackedParallelCNN,
  5.     'rnn': RNN,
  6.     'cnnrnn': CNNRNN,
  7.     'embed': EmbedEncoder
  8. }

Adding a Decoder

1. Add a new decoder class

Souce code for decoders lives under ludwig/models/modules.New decoder objects should be defined in the corresponding files, for example all new sequence decoders should be added to ludwig/models/modules/sequence_decoders.py.

All the decoder parameters should be provided as arguments in the constructor with their default values set. For example Generator decoder takes the following list of arguments in its constructor:

  1. __init__(
  2.     self,
  3.     cell_type='rnn',
  4.     state_size=256,
  5.     embedding_size=64,
  6.     beam_width=1,
  7.     num_layers=1,
  8.     attention_mechanism=None,
  9.     tied_embeddings=None,
  10.     initializer=None,
  11.     regularize=True,
  12.     **kwargs
  13. )

Decoders are initialized as class member variables in output feature object constructors and called inside build_output methods.

2. Add the new decoder class to the corresponding decoder registry

Mapping between decoder keywords in the model definition and decoder classes is done by decoder registries: for example sequence decoder registry is defined in ludwig/features/sequence_feature.py

  1. sequence_decoder_registry = {
  2.     'generator': Generator,
  3.     'tagger': Tagger
  4. }

Adding a new Feature Type

1. Add a new feature class

Souce code for feature classes lives under ludwig/features.Input and output feature classes are defined in the same file, for example CategoryInputFeature and CategoryOutputFeature are defined in ludwig/features/category_feature.py.

An input features inherit from the InputFeature and corresponding base feature classes, for example CategoryInputFeature inherits from CategoryBaseFeature and InputFeature.

Similarly, output features inherit from the OutputFeature and corresponding base feature classes, for example CategoryOutputFeature inherits from CategoryBaseFeature and OutputFeature.

Feature parameters are provided in a dictionary of key-value pairs as an argument to the input or output feature constructor which contains default parameter values as well.

All input and output features should implement build_input and build_output methods correspondingly with the following signatures:

build_input

  1. build_input(
  2.     self,
  3.     regularizer,
  4.     dropout_rate,
  5.     is_training=False,
  6.     **kwargs
  7. )

Inputs

  • regularizer (A (Tensor -> Tensor or None) function): regularizer function passed to tf.get_variable method.
  • dropout_rate (tf.Tensor(dtype: tf.float32)): dropout rate.

  • is_training (tf.Tensor(dtype: tf.bool), default: True): boolean indicating whether this is a training dataset. Return

  • feature_representation (dict): the following dictionary

  1. {
  2.     'type': self.type, # str
  3.     'representation': feature_representation, # tf.Tensor(dtype: tf.float32)
  4.     'size': feature_representation_size, # int
  5.     'placeholder': placeholder # tf.Tensor(dtype: tf.float32)
  6. }

build_output

  1. build_output(
  2.     self,
  3.     hidden,
  4.     hidden_size,
  5.     regularizer=None,
  6.     **kwargs
  7. )

Inputs

  • hidden (tf.Tensor(dtype: tf.float32)): output feature representation.
  • hidden_size (int): output feature representation size.
  • regularizer (A (Tensor -> Tensor or None) function): regularizer function passed to tf.get_variable method. Return- train_mean_loss (tf.Tensor(dtype: tf.float32)): mean loss for train dataset.- eval_loss (tf.Tensor(dtype: tf.float32)): mean loss for evaluation dataset.- output_tensors (dict): dictionary containing feature specific output tensors (predictions, probabilities, losses, etc).

2. Add the new feature class to the corresponding feature registry

Input and output feature registries are defined in ludwig/features/feature_registries.py.

Style Guidelines

We expect contributions to mimic existing patterns in the codebase and demonstrate good practices: the code should be concise, readable, PEP8-compliant, and conforming to 80 character line length limit.

Tests

We are using pytest to run tests. Current test coverage is limited to several integration tests which ensure end-to-end functionality but we are planning to expand it.

Checklist

Before running tests, make sure 1. Your environment is properly setup.2. You have write access on the machine. Some of the tests require saving data to disk.

Running tests

To run all tests, just runpython -m pytest from the ludwig root directory.Note that you don't need to have ludwig module installed and in this casecode change will take effect immediately.

To run a single test, run

  1. python -m pytest path_to_filename::test_method_name

Example

  1. python -m pytest tests/integration_tests/test_experiment.py::test_visual_question_answering