Update field descriptions for ludwig-docs (#3123)

ludwig/config_validation/checks.py

@@ -1,7 +1,7 @@
 """Checks that are not easily covered by marshmallow JSON schema validation like parameter interdependencies."""
 
 from abc import ABC, abstractmethod
-from typing import Callable
+from typing import Callable, TYPE_CHECKING
 
 from ludwig.api_annotations import DeveloperAPI
 from ludwig.constants import (
@@ -36,6 +36,9 @@
 from ludwig.types import ModelConfigDict
 from ludwig.utils.metric_utils import get_feature_to_metric_names_map_from_feature_collection
 
+if TYPE_CHECKING:
+    from ludwig.schema.model_config import ModelConfig
+
 # Set of all sequence feature types.
 SEQUENCE_OUTPUT_FEATURE_TYPES = {SEQUENCE, TEXT, SET, VECTOR}
 

ludwig/modules/tabnet_modules.py

@@ -261,7 +261,7 @@ def forward(self, inputs, prior_scales):
         # removing the mean to try to avoid numerical instability
         # https://github.com/tensorflow/addons/issues/2314
         # https://github.com/tensorflow/tensorflow/pull/21183/files
-        # In the paper, they call the logits z.
+        # In (Arik and Pfister, 2019), they call the logits z.
         # The mean(logits) can be substracted from logits to make the algorithm
         # more numerically stable. the instability in this algorithm comes mostly
         # from the z_cumsum. Substacting the mean will cause z_cumsum to be close

ludwig/schema/combiners/common_transformer_options.py

@@ -1,6 +1,7 @@
 from typing import Any, Dict, List, Optional, Union
 
 from ludwig.api_annotations import DeveloperAPI
+from ludwig.schema import common_fields
 from ludwig.schema import utils as schema_utils
 from ludwig.schema.metadata import COMBINER_METADATA
 from ludwig.schema.utils import ludwig_dataclass
@@ -35,7 +36,7 @@ class CommonTransformerConfig:
 
     num_layers: int = schema_utils.PositiveInteger(
         default=1,
-        description="The number of transformer layers",
+        description="The number of transformer layers.",
         parameter_metadata=COMBINER_METADATA["TransformerCombiner"]["num_layers"],
     )
 
@@ -51,17 +52,9 @@ class CommonTransformerConfig:
         parameter_metadata=COMBINER_METADATA["TransformerCombiner"]["use_bias"],
     )
 
-    bias_initializer: Union[str, Dict] = schema_utils.InitializerOrDict(
-        default="zeros",
-        description="",
-        parameter_metadata=COMBINER_METADATA["TransformerCombiner"]["bias_initializer"],
-    )
+    bias_initializer: Union[str, Dict] = common_fields.BiasInitializerField()
 
-    weights_initializer: Union[str, Dict] = schema_utils.InitializerOrDict(
-        default="xavier_uniform",
-        description="",
-        parameter_metadata=COMBINER_METADATA["TransformerCombiner"]["weights_initializer"],
-    )
+    weights_initializer: Union[str, Dict] = common_fields.WeightsInitializerField()
 
     # TODO(#1673): Add conditional logic for fields like this one:
     num_fc_layers: int = schema_utils.NonNegativeInteger(
@@ -76,40 +69,17 @@ class CommonTransformerConfig:
         parameter_metadata=COMBINER_METADATA["TransformerCombiner"]["output_size"],
     )
 
-    norm: Optional[str] = schema_utils.StringOptions(
-        ["batch", "layer"],
-        default=None,
-        allow_none=True,
-        description="",
-        parameter_metadata=COMBINER_METADATA["TransformerCombiner"]["norm"],
-    )
+    norm: Optional[str] = common_fields.NormField()
 
-    norm_params: Optional[dict] = schema_utils.Dict(
-        description="",
-        parameter_metadata=COMBINER_METADATA["TransformerCombiner"]["norm_params"],
-    )
+    norm_params: Optional[dict] = common_fields.NormParamsField()
 
-    fc_layers: Optional[List[Dict[str, Any]]] = schema_utils.DictList(
-        description="",
-        parameter_metadata=COMBINER_METADATA["TransformerCombiner"]["fc_layers"],
-    )
+    fc_layers: Optional[List[Dict[str, Any]]] = common_fields.FCLayersField()
 
-    fc_dropout: float = schema_utils.FloatRange(
-        default=0.0,
-        min=0,
-        max=1,
-        description="",
-        parameter_metadata=COMBINER_METADATA["TransformerCombiner"]["fc_dropout"],
-    )
+    fc_dropout: float = common_fields.DropoutField()
 
     fc_activation: str = schema_utils.ActivationOptions(
         default="relu",
-        description="",
         parameter_metadata=COMBINER_METADATA["TransformerCombiner"]["fc_activation"],
     )
 
-    fc_residual: bool = schema_utils.Boolean(
-        default=False,
-        description="",
-        parameter_metadata=COMBINER_METADATA["TransformerCombiner"]["fc_residual"],
-    )
+    fc_residual: bool = common_fields.ResidualField()

ludwig/schema/combiners/comparator.py

@@ -1,6 +1,8 @@
 from typing import Any, Dict, List, Optional, Union
 
 from ludwig.api_annotations import DeveloperAPI
+from ludwig.error import ConfigValidationError
+from ludwig.schema import common_fields
 from ludwig.schema import utils as schema_utils
 from ludwig.schema.combiners.base import BaseCombinerConfig
 from ludwig.schema.metadata import COMBINER_METADATA
@@ -12,6 +14,13 @@
 class ComparatorCombinerConfig(BaseCombinerConfig):
     """Parameters for comparator combiner."""
 
+    def __post_init__(self):
+        if self.num_fc_layers == 0 and self.fc_layers is None:
+            raise ConfigValidationError(
+                "`combiner.type=comparator` requires at least one fully connected layer. "
+                "Set `num_fc_layers > 0` or `fc_layers`."
+            )
+
     @staticmethod
     def module_name():
         return "ComparatorCombiner"
@@ -23,74 +32,46 @@ def module_name():
 
     entity_1: List[str] = schema_utils.List(
         default=None,
-        description="The list of input features composing the first entity to compare.",
+        description=(
+            "The list of input feature names `[feature_1, feature_2, ...]` constituting the first entity to compare. "
+            "*Required*."
+        ),
         parameter_metadata=COMBINER_METADATA["ComparatorCombiner"]["entity_1"],
     )
 
     entity_2: List[str] = schema_utils.List(
         default=None,
-        description="The list of input features composing the second entity to compare.",
+        description=(
+            "The list of input feature names `[feature_1, feature_2, ...]` constituting the second entity to compare. "
+            "*Required*."
+        ),
         parameter_metadata=COMBINER_METADATA["ComparatorCombiner"]["entity_2"],
     )
 
-    dropout: float = schema_utils.FloatRange(
-        default=0.0,
-        min=0,
-        max=1,
-        description="Dropout rate for the transformer block.",
-        parameter_metadata=COMBINER_METADATA["ComparatorCombiner"]["dropout"],
-    )
+    dropout: float = common_fields.DropoutField()
 
-    activation: str = schema_utils.ActivationOptions(
-        default="relu",
-        description="",
-        parameter_metadata=COMBINER_METADATA["ComparatorCombiner"]["activation"],
-    )
+    activation: str = schema_utils.ActivationOptions(default="relu")
 
     use_bias: bool = schema_utils.Boolean(
         default=True,
         description="Whether the layer uses a bias vector.",
         parameter_metadata=COMBINER_METADATA["ComparatorCombiner"]["use_bias"],
     )
 
-    bias_initializer: Union[str, Dict] = schema_utils.InitializerOrDict(
-        default="zeros",
-        description="",
-        parameter_metadata=COMBINER_METADATA["ComparatorCombiner"]["bias_initializer"],
-    )
+    bias_initializer: Union[str, Dict] = common_fields.BiasInitializerField()
 
-    weights_initializer: Union[str, Dict] = schema_utils.InitializerOrDict(
-        default="xavier_uniform",
-        description="",
-        parameter_metadata=COMBINER_METADATA["ComparatorCombiner"]["weights_initializer"],
-    )
+    weights_initializer: Union[str, Dict] = common_fields.WeightsInitializerField()
 
-    num_fc_layers: int = schema_utils.NonNegativeInteger(
-        default=1,
-        description="",
-        parameter_metadata=COMBINER_METADATA["ComparatorCombiner"]["num_fc_layers"],
-    )
+    num_fc_layers: int = common_fields.NumFCLayersField(default=1)
 
     output_size: int = schema_utils.PositiveInteger(
         default=256,
-        description="Output size of a fully connected layer",
+        description="Output size of a fully connected layer.",
         parameter_metadata=COMBINER_METADATA["ComparatorCombiner"]["output_size"],
     )
 
-    norm: Optional[str] = schema_utils.StringOptions(
-        ["batch", "layer"],
-        default=None,
-        allow_none=True,
-        description="",
-        parameter_metadata=COMBINER_METADATA["ComparatorCombiner"]["norm"],
-    )
+    norm: Optional[str] = common_fields.NormField()
 
-    norm_params: Optional[dict] = schema_utils.Dict(
-        description="",
-        parameter_metadata=COMBINER_METADATA["ComparatorCombiner"]["norm_params"],
-    )
+    norm_params: Optional[dict] = common_fields.NormParamsField()
 
-    fc_layers: Optional[List[Dict[str, Any]]] = schema_utils.DictList(
-        description="",
-        parameter_metadata=COMBINER_METADATA["ComparatorCombiner"]["fc_layers"],
-    )
+    fc_layers: Optional[List[Dict[str, Any]]] = common_fields.FCLayersField()

ludwig/schema/combiners/concat.py

@@ -1,6 +1,7 @@
 from typing import Any, Dict, List, Optional, Union
 
 from ludwig.api_annotations import DeveloperAPI
+from ludwig.schema import common_fields
 from ludwig.schema import utils as schema_utils
 from ludwig.schema.combiners.base import BaseCombinerConfig
 from ludwig.schema.metadata import COMBINER_METADATA
@@ -21,78 +22,38 @@ def module_name():
         description=COMBINER_METADATA["ConcatCombiner"]["type"].long_description,
     )
 
-    dropout: float = schema_utils.FloatRange(
-        default=0.0,
-        min=0,
-        max=1,
-        description="",
-        parameter_metadata=COMBINER_METADATA["ConcatCombiner"]["dropout"],
-    )
+    dropout: float = common_fields.DropoutField()
 
-    activation: str = schema_utils.ActivationOptions(
-        default="relu",
-        description="",
-        parameter_metadata=COMBINER_METADATA["ConcatCombiner"]["activation"],
-    )
+    activation: str = schema_utils.ActivationOptions(default="relu")
 
     flatten_inputs: bool = schema_utils.Boolean(
         default=False,
         description="Whether to flatten input tensors to a vector.",
         parameter_metadata=COMBINER_METADATA["ConcatCombiner"]["flatten_inputs"],
     )
 
-    residual: bool = schema_utils.Boolean(
-        default=False,
-        description="Whether to add a residual connection to each fully connected layer block. All fully connected "
-        "layers must have the same size ",
-        parameter_metadata=COMBINER_METADATA["ConcatCombiner"]["residual"],
-    )
+    residual: bool = common_fields.ResidualField()
 
     use_bias: bool = schema_utils.Boolean(
         default=True,
         description="Whether the layer uses a bias vector.",
         parameter_metadata=COMBINER_METADATA["ConcatCombiner"]["use_bias"],
     )
 
-    bias_initializer: Union[str, Dict] = schema_utils.InitializerOrDict(
-        default="zeros",
-        description="",
-        parameter_metadata=COMBINER_METADATA["ConcatCombiner"]["bias_initializer"],
-    )
+    bias_initializer: Union[str, Dict] = common_fields.BiasInitializerField()
 
-    weights_initializer: Union[str, Dict] = schema_utils.InitializerOrDict(
-        default="xavier_uniform",
-        description="",
-        parameter_metadata=COMBINER_METADATA["ConcatCombiner"]["weights_initializer"],
-    )
+    weights_initializer: Union[str, Dict] = common_fields.WeightsInitializerField()
 
-    num_fc_layers: int = schema_utils.NonNegativeInteger(
-        default=0,
-        allow_none=False,
-        description="",
-        parameter_metadata=COMBINER_METADATA["ConcatCombiner"]["num_fc_layers"],
-    )
+    num_fc_layers: int = common_fields.NumFCLayersField()
 
     output_size: int = schema_utils.PositiveInteger(
         default=256,
         description="Output size of a fully connected layer.",
         parameter_metadata=COMBINER_METADATA["ConcatCombiner"]["output_size"],
     )
 
-    norm: Optional[str] = schema_utils.StringOptions(
-        ["batch", "layer", "ghost"],
-        default=None,
-        allow_none=True,
-        description="",
-        parameter_metadata=COMBINER_METADATA["ConcatCombiner"]["norm"],
-    )
+    norm: Optional[str] = common_fields.NormField()
 
-    norm_params: Optional[dict] = schema_utils.Dict(
-        description="",
-        parameter_metadata=COMBINER_METADATA["ConcatCombiner"]["norm_params"],
-    )
+    norm_params: Optional[dict] = common_fields.NormParamsField()
 
-    fc_layers: Optional[List[Dict[str, Any]]] = schema_utils.DictList(
-        description="",
-        parameter_metadata=COMBINER_METADATA["ConcatCombiner"]["fc_layers"],
-    )
+    fc_layers: Optional[List[Dict[str, Any]]] = common_fields.FCLayersField()

ludwig/schema/combiners/sequence.py

@@ -4,6 +4,7 @@
 from ludwig.constants import MODEL_ECD, SEQUENCE
 from ludwig.schema import utils as schema_utils
 from ludwig.schema.combiners.base import BaseCombinerConfig
+from ludwig.schema.combiners.sequence_concat import MAIN_SEQUENCE_FEATURE_DESCRIPTION
 from ludwig.schema.encoders.base import BaseEncoderConfig
 from ludwig.schema.encoders.utils import EncoderDataclassField
 from ludwig.schema.metadata import COMBINER_METADATA
@@ -27,18 +28,19 @@ def module_name():
     main_sequence_feature: Optional[str] = schema_utils.String(
         default=None,
         allow_none=True,
-        description="",
+        description=MAIN_SEQUENCE_FEATURE_DESCRIPTION,
         parameter_metadata=COMBINER_METADATA["SequenceCombiner"]["main_sequence_feature"],
     )
 
     encoder: BaseEncoderConfig = EncoderDataclassField(
         MODEL_ECD,
         feature_type=SEQUENCE,
         default="parallel_cnn",
+        description="Encoder to apply to `main_sequence_feature`.",
     )
 
     reduce_output: Optional[str] = schema_utils.ReductionOptions(
         default=None,
-        description="",
+        description="Strategy to use to aggregate the embeddings of the items of the set.",
         parameter_metadata=COMBINER_METADATA["SequenceCombiner"]["reduce_output"],
     )

ludwig/schema/combiners/sequence_concat.py

@@ -6,6 +6,16 @@
 from ludwig.schema.metadata import COMBINER_METADATA
 from ludwig.schema.utils import ludwig_dataclass
 
+MAIN_SEQUENCE_FEATURE_DESCRIPTION = """
+Name of a sequence, text, or time series feature to concatenate the outputs
+of the other features to. If no `main_sequence_feature` is specified, the combiner will look through all the features in
+the order they are defined in the configuration and will look for a feature with a rank 3 tensor output (sequence, text
+or time series). If it cannot find one it will raise an exception, otherwise the output of that feature will be used for
+concatenating the other features along the sequence `s` dimension. If there are other input features with a rank 3
+output tensor, the combiner will concatenate them alongside the `s` dimension. All sequence-like input features must
+have identical `s` dimension, otherwise an error will be thrown.
+"""
+
 
 @DeveloperAPI
 @ludwig_dataclass
@@ -24,12 +34,12 @@ def module_name():
     main_sequence_feature: Optional[str] = schema_utils.String(
         default=None,
         allow_none=True,
-        description="",
+        description=MAIN_SEQUENCE_FEATURE_DESCRIPTION,
         parameter_metadata=COMBINER_METADATA["SequenceConcatCombiner"]["main_sequence_feature"],
     )
 
     reduce_output: Optional[str] = schema_utils.ReductionOptions(
         default=None,
-        description="",
+        description="Strategy to use to aggregate the embeddings of the items of the set.",
         parameter_metadata=COMBINER_METADATA["SequenceConcatCombiner"]["reduce_output"],
     )

ludwig/schema/combiners/tab_transformer.py

@@ -31,6 +31,6 @@ def module_name():
 
     reduce_output: str = schema_utils.ReductionOptions(
         default="concat",
-        description="",
+        description="Strategy to use to aggregate the output of the transformer.",
         parameter_metadata=COMBINER_METADATA["TabTransformerCombiner"]["reduce_output"],
     )