API Reference: Policies

masterful.FitPolicy

class masterful.FitPolicy(loss_types=(), loss_configs=(), loss_pure_functions=(), loss_weights=(), metrics_types=(), metrics_configs=(), metrics_pure_functions=(), batch_size=None, optimizer_type=None, optimizer_config=None, learning_rate_callback_type=None, learning_rate_callback_config=None, learning_rate_schedule=None, epochs_callback_type=None, epochs_callback_config=None, epochs=None, callback_types=(), callback_configs=(), warmup_initial_lr=None, warmup_final_lr=None, warmup_steps=None, mirror=None, rot90=None, rotate=None, hsv_cluster=None, contrast_cluster=None, blur_cluster=None, spatial_cluster=None, hsv_cluster_to_index=None, contrast_cluster_to_index=None, blur_cluster_to_index=None, spatial_cluster_to_index=None, hsv_magnitude_table=None, contrast_magnitude_table=None, blur_magnitude_table=None, spatial_magnitude_table=None, mixup=None, cutmix=None, lsr=None, synthetic_proportion=None, unlabeled_switch=None)

Describes the policy for use by masterful.core.fit.

A note on learning rates: Keras provides multiple ways to control learning rate. * Most subclasses of tf.keras.optimizers.Optimizer accept a learning_rate scalar arg. * Most subclasses of tf.keras.optimizers.Optimizer accept a learning_rate_scheduler callable, which itself simply accept a step arg and returns a scalar value. * Callbacks like tf.keras.callbacks.LearningRateScheduler and tf.keras.callbacks.ReduceLROnPlateau assume the optimizer has an LR value (which is sometimes a python attribute and sometimes a tf.Variable) and updates it directly using tf.keras.backend.set_value().

To reduce complexity, Masterful.core.fit takes learning rate optimization away from optimizer entirely. It ignores any learning rate passed as a constructor arg to an optimizer. Instead, training starts with warmup_initial_lr, proceeds to warmup_final_lr, then continues training.

To control learning rate using a fixed schedule, a learning rate schedule callable can be passed. The callable should be a pure function that does not read state - it should be cachable / memoizable with no change in behavior. This will override warmup (so it should handle warmup interally).

To control a learning rate using a dynamic callback, FitPolicy holds the type and config of a callback. Internally, Fit will instantiate a callback of type learning_rate_callback_type with args learning_rate_callback_config. As a convenience function. FitPolicy can snapshot the state and config from an instance of a callback using merge_from_learning_rate_callback. Note that future changes to the instance of callback previously passed to FitPolicy will not affect FitPolicy, because merge_from_xyz takes a snapshot of the instance, not a reference to the instance.

A note on epochs: (TODO).

Parameters

  • loss_types (Sequence[type]) –

  • loss_configs (Sequence[Dict]) –

  • loss_pure_functions (Sequence[Callable[[tensorflow.python.framework.ops.Tensor, tensorflow.python.framework.ops.Tensor], tensorflow.python.framework.ops.Tensor]]) –

  • loss_weights (Union[Sequence[float], Dict[str, float]]) –

  • metrics_types (Sequence[type]) –

  • metrics_configs (Sequence[Dict]) –

  • metrics_pure_functions (Sequence[Callable[[tensorflow.python.framework.ops.Tensor, tensorflow.python.framework.ops.Tensor], tensorflow.python.framework.ops.Tensor]]) –

  • batch_size (int) –

  • optimizer_type (type) –

  • optimizer_config (Dict) –

  • learning_rate_callback_type (type) –

  • learning_rate_callback_config (Union[dataclasses.dataclass, Dict]) –

  • learning_rate_schedule (Callable) –

  • epochs_callback_type (type) –

  • epochs_callback_config (Union[dataclasses.dataclass, Dict]) –

  • epochs (int) –

  • callback_types (Sequence[type]) –

  • callback_configs (Sequence[Dict]) –

  • warmup_initial_lr (float) –

  • warmup_final_lr (float) –

  • warmup_steps (int) –

  • mirror (float) –

  • rot90 (float) –

  • rotate (int) –

  • hsv_cluster (int) –

  • contrast_cluster (int) –

  • blur_cluster (int) –

  • spatial_cluster (int) –

  • hsv_cluster_to_index (numpy.ndarray) –

  • contrast_cluster_to_index (numpy.ndarray) –

  • blur_cluster_to_index (numpy.ndarray) –

  • spatial_cluster_to_index (numpy.ndarray) –

  • hsv_magnitude_table (numpy.ndarray) –

  • contrast_magnitude_table (numpy.ndarray) –

  • blur_magnitude_table (numpy.ndarray) –

  • spatial_magnitude_table (numpy.ndarray) –

  • mixup (float) –

  • cutmix (float) –

  • lsr (float) –

  • synthetic_proportion (Sequence[float]) –

  • unlabeled_switch (Sequence[int]) –

Return type

None

batch_size

Int. The batch size to use.

Type

int

loss_types
Type

Sequence[type]

loss_configs
Type

Sequence[Dict]

loss_pure_functions

Matches tf.keras.model.compile(loss) argument. name, callable, sequence of name or callable, or dictionary of name or callable where the dict key matches an output name. Like learning rate schedule, these should be pure functions that do not read or write any state. In C++ terms, these would be const functions.

Type

Sequence[Callable[[tensorflow.python.framework.ops.Tensor, tensorflow.python.framework.ops.Tensor], tensorflow.python.framework.ops.Tensor]]

loss_weights

Sequence[Union[Dict]] Matches tf.keras.model.compile(loss_weights).

Type

Union[Sequence[float], Dict[str, float]]

metrics_types
Type

Sequence[type]

metrics_configs
Type

Sequence[Dict]

metrics_pure_functions

Matches tf.keras.model.compile(metrics) argument. name, callable, sequence of name or callable, or dictionary of name or callable where the dict key matches an output name. Like learning rate schedule, these should be pure functions that do not read or write any state. In C++ terms, these would be const functions.

Type

Sequence[Callable[[tensorflow.python.framework.ops.Tensor, tensorflow.python.framework.ops.Tensor], tensorflow.python.framework.ops.Tensor]]

optimizer_type

tf.keras.optimizers.Optimizer. The type of optimizer to use. See note on learning rates.

Type

type

optimizer_config

Optimizer specific configuration. This will be passed to tf.keras.optimizers.Optimizer.from_config(optimizer_config). See note on learning rates.

Type

Dict

learning_rate_callback_type

To control learning rate using a callback, this attribute holds the type of a callback and the learning_rate_callback_config holds the config.

Type

type

learning_rate_callback_config

This dictionary is passed as keyword args to learning_rate_callback_type. See note on learning rates.

Type

Union[dataclasses.dataclass, Dict]

learning_rate_schedule

A callable that matches the signature f(step)->lr. See note on learning rates.

Type

Callable

epochs_callback_type

To control early stopping behavior, a callback’s type is stored in epochs_callback_type and

Type

type

epochs_callback_config
Type

Union[dataclasses.dataclass, Dict]

epochs

A fixed number of epochs to run. Either this value or the epochs callback type and epochs_callback_config

Type

int

callback_types

List of types for any custom callbacks during training. These callbacks must be read-only and not update any internal training state.

Type

Sequence[type]

callback_configs

kwargs parameters for initializing any callbacks.

Type

Sequence[Dict]

warmup_initial_lr

The initial learning rate to start warming up a model.

Type

float

warmup_final_lr

The final learning rate to finish warming up a model.

Type

float

warmup_steps

The number of steps to warm up a model.

Type

int

mirror

Boolean, controls whether mirror is never performed or performed 50%.

Type

float

rot90

Boolean, controls whether images are rotate uniformly at 0, 90, 180, 270 or not at all. These are the “pixel perfect” rotations.

Type

float

rotate

Int. Controls whether images are uniformly rotated. A magnitude of 100 corresponds to +/- 180 degrees. 50 corresponds to +/- 90 degrees. 17 corresponds to +/- 30 degrees.

Type

int

hsv_cluster

Int. After HSV transforms are analyzed and clustered by model response, this scalar controls which cluster of HSV transformations is applied.

Type

int

contrast_cluster

Int. After constrast transforms are analyzed and clustered by model response, this scalar controls which cluster of contrast transformation magnitudes is applied.

Type

int

blur_cluster

Int. After blur transforms are analyzed and clustered by model response, this scalar controls which cluster of blur transformation magnitudes is applied.

Type

int

spatial_cluster

Int. After spatial transforms are analyzed and clustered by model response, this scalar controls which cluster of spatial transformation magnitudes is applied.

Type

int

hsv_cluster_details

Matrix of numbers implemented either as tuple of tuples or numpy.ndarray. Describes the clustering of HSV transforms and magnitudes.

contrast_clustering_details

Matrix of numbers implemented either as tuple of tuples or numpy.ndarray. Describes the clustering of HSV transforms and magnitudes.

blur_clustering_details

Matrix of numbers implemented either as tuple of tuples or numpy.ndarray. Describes the clustering of HSV transforms and magnitudes.

spatial_clustering_details

Matrix of numbers implemented either as tuple of tuples or numpy.ndarray. Describes the clustering of HSV transforms and magnitudes.

mixup

The percentage of a batch to replace with the mixup transformation.

Type

float

cutmix

The percentage of a batch to replace with the mixup transformation.

Type

float

synthetic_proportions

The target proportion of synthetic data in the blended training data. For example, if there are 100 real datapoints and the synthetic proprotion is set to 10%, all 100 real datapoints are always used so 11 synthetic datapoints will be added for a total cardinality of 111 data points, 11 of which (9.9%) will be synthetic, and 100 of which (90.1%) will be real.

unlabeled_usage

Determines whether fit will attempt to use noisy student training to learn from unlabeled data. Only applicable if fit receives unlabeled data.

MetricTypes
static load_from(path)

Loads a policy from the given path.

Parameters

path (str) – The full path to the policy file to load.

Returns

A new instance of FitPolicy.

Return type

masterful.policy.FitPolicy

static merge_from_dict(fit_policy, updates)

Create new FitPolicy instance from a dict and existing FitPolicy instance.

Parameters

  • fit_policy (masterful.policy.FitPolicy) – An existing instance of FitPolicy to pull attribute values from.

  • updates (Dict) – A set of updates to attributes.

Returns

A new instance of FitPolicy with attributes from fit_policy and updates. FitPolicy is a dataclass so it holds values as attributes; updates is a dict so it holds values as key-value pairs. The values from updates takes precendence, then the values from fit_policy’s attributes.

Raises

ValueError – if a key in update does not correspond to an attribute in FitPolicy.

Return type

masterful.policy.FitPolicy

static merge_from_epochs_callback(fit_policy, callback)

Merges the type and config from an instance of callback.

Parameters
Return type

masterful.policy.FitPolicy

static merge_from_learning_rate_callback(fit_policy, callback)

Merges the type and config from an instance of callback.

See note on learning rates. The instance is not stored and any future changes by the user to the instance will not update this FitPolicy.

Parameters
Return type

masterful.policy.FitPolicy

static merge_from_optimizer(fit_policy, optimizer)

Merges the type and config from an instance of optimizer.

See note on learning rates. The instance is not stored and any future changes by the user to the instance will not update this FitPolicy.

Parameters
Return type

masterful.policy.FitPolicy

save_to(path)

Saves a policy to the given path.

Parameters

DistillationPolicy

masterful.DistillationPolicy

class masterful.DistillationPolicy(batch_size=None)

Training policy for use with knowledge distillation.

Parameters

batch_size (int) –

Return type

None

batch_size

The batch size to use for training.

Type

int

masterful.EnsemblePolicy

class masterful.EnsemblePolicy(loss_types=(), loss_configs=(), loss_pure_functions=(), loss_weights=(), metrics_types=(), metrics_configs=(), metrics_pure_functions=(), batch_size=None, optimizer_type=None, optimizer_config=None, learning_rate_callback_type=None, learning_rate_callback_config=None, learning_rate_schedule=None, epochs_callback_type=None, epochs_callback_config=None, epochs=None, callback_types=(), callback_configs=(), warmup_initial_lr=None, warmup_final_lr=None, warmup_steps=None, mirror=None, rot90=None, rotate=None, hsv_cluster=None, contrast_cluster=None, blur_cluster=None, spatial_cluster=None, hsv_cluster_to_index=None, contrast_cluster_to_index=None, blur_cluster_to_index=None, spatial_cluster_to_index=None, hsv_magnitude_table=None, contrast_magnitude_table=None, blur_magnitude_table=None, spatial_magnitude_table=None, mixup=None, cutmix=None, lsr=None, synthetic_proportion=None, unlabeled_switch=None, multiplier=None)

Subclass of masterful.FitPolicy, for use in ensemble training. Adds a multiplier attribute.

Parameters

  • loss_types (Sequence[type]) –

  • loss_configs (Sequence[Dict]) –

  • loss_pure_functions (Sequence[Callable[[tensorflow.python.framework.ops.Tensor, tensorflow.python.framework.ops.Tensor], tensorflow.python.framework.ops.Tensor]]) –

  • loss_weights (Union[Sequence[float], Dict[str, float]]) –

  • metrics_types (Sequence[type]) –

  • metrics_configs (Sequence[Dict]) –

  • metrics_pure_functions (Sequence[Callable[[tensorflow.python.framework.ops.Tensor, tensorflow.python.framework.ops.Tensor], tensorflow.python.framework.ops.Tensor]]) –

  • batch_size (int) –

  • optimizer_type (type) –

  • optimizer_config (Dict) –

  • learning_rate_callback_type (type) –

  • learning_rate_callback_config (Union[dataclasses.dataclass, Dict]) –

  • learning_rate_schedule (Callable) –

  • epochs_callback_type (type) –

  • epochs_callback_config (Union[dataclasses.dataclass, Dict]) –

  • epochs (int) –

  • callback_types (Sequence[type]) –

  • callback_configs (Sequence[Dict]) –

  • warmup_initial_lr (float) –

  • warmup_final_lr (float) –

  • warmup_steps (int) –

  • mirror (float) –

  • rot90 (float) –

  • rotate (int) –

  • hsv_cluster (int) –

  • contrast_cluster (int) –

  • blur_cluster (int) –

  • spatial_cluster (int) –

  • hsv_cluster_to_index (numpy.ndarray) –

  • contrast_cluster_to_index (numpy.ndarray) –

  • blur_cluster_to_index (numpy.ndarray) –

  • spatial_cluster_to_index (numpy.ndarray) –

  • hsv_magnitude_table (numpy.ndarray) –

  • contrast_magnitude_table (numpy.ndarray) –

  • blur_magnitude_table (numpy.ndarray) –

  • spatial_magnitude_table (numpy.ndarray) –

  • mixup (float) –

  • cutmix (float) –

  • lsr (float) –

  • synthetic_proportion (Sequence[float]) –

  • unlabeled_switch (Sequence[int]) –

  • multiplier (int) –

Return type

None

multiplier

The number of ensembles to train.

Type

int

masterful.PretrainPolicy

class masterful.PretrainPolicy(batch_size=None, epochs=None, warmup_steps=None)

Defines a policy to use for pretraining a model.

Parameters

  • batch_size (int) –

  • epochs (int) –

  • warmup_steps (int) –

Return type

None

batch_size

The batch size to use in training.

Type

int

epochs

The number of epochs to train for.

Type

int

warmup_steps

The number of steps to warm the model up.

Type

int

masterful.AdaptationPolicy

class masterful.AdaptationPolicy(batch_size=None, epochs=None)

Defines a policy to use for adapting a model to multiple domains.

Parameters

  • batch_size (int) –

  • epochs (int) –

Return type

None

batch_size

The batch size to use in training.

Type

int

epochs

The number of epochs to train for.

Type

int