doc: update 1p estimators class description (#1820)

* doc: update 1p estimators class description

* follow pep-0257

* add doctrings to args of model classes

Co-authored-by: Chuyang Deng <[email protected]>

Author: chuyang-deng

src/sagemaker/amazon/factorization_machines.py

@@ -25,7 +25,12 @@
 
 
 class FactorizationMachines(AmazonAlgorithmEstimatorBase):
-    """Placeholder docstring"""
+    """A supervised learning algorithm used in classification and regression.
+
+    Factorization Machines combine the advantages of Support Vector Machines
+    with factorization models. It is an extension of a linear model that is
+    designed to capture interactions between features within high dimensional
+    sparse datasets economically."""
 
     repo_name = "factorization-machines"
     repo_version = 1
@@ -304,10 +309,19 @@ class FactorizationMachinesModel(Model):
     def __init__(self, model_data, role, sagemaker_session=None, **kwargs):
         """
         Args:
-            model_data:
-            role:
-            sagemaker_session:
-            **kwargs:
+            model_data (str): The S3 location of a SageMaker model data
+                ``.tar.gz`` file.
+            role (str): An AWS IAM role (either name or full ARN). The Amazon
+                SageMaker training jobs and APIs that create Amazon SageMaker
+                endpoints use this role to access training data and model
+                artifacts. After the endpoint is created, the inference code
+                might use the IAM role, if it needs to access an AWS resource.
+            sagemaker_session (sagemaker.session.Session): Session object which
+                manages interactions with Amazon SageMaker APIs and any other
+                AWS services needed. If not specified, the estimator creates one
+                using the default AWS configuration chain.
+            **kwargs: Keyword arguments passed to the ``FrameworkModel``
+                initializer.
         """
         sagemaker_session = sagemaker_session or Session()
         image_uri = image_uris.retrieve(

src/sagemaker/amazon/hyperparameter.py

@@ -17,8 +17,9 @@
 
 
 class Hyperparameter(object):
-    """An algorithm hyperparameter with optional validation. Implemented as a
-    python descriptor object.
+    """An algorithm hyperparameter with optional validation.
+
+    Implemented as a python descriptor object.
     """
 
     def __init__(self, name, validate=lambda _: True, validation_message="", data_type=str):

src/sagemaker/amazon/ipinsights.py

@@ -26,7 +26,10 @@
 
 
 class IPInsights(AmazonAlgorithmEstimatorBase):
-    """Placeholder docstring"""
+    """An unsupervised learning algorithm that learns the usage patterns for IPv4 addresses.
+
+    It is designed to capture associations between IPv4 addresses and various entities, such
+    as user IDs or account numbers."""
 
     repo_name = "ipinsights"
     repo_version = 1
@@ -214,10 +217,19 @@ class IPInsightsModel(Model):
     def __init__(self, model_data, role, sagemaker_session=None, **kwargs):
         """
         Args:
-            model_data:
-            role:
-            sagemaker_session:
-            **kwargs:
+            model_data (str): The S3 location of a SageMaker model data
+                ``.tar.gz`` file.
+            role (str): An AWS IAM role (either name or full ARN). The Amazon
+                SageMaker training jobs and APIs that create Amazon SageMaker
+                endpoints use this role to access training data and model
+                artifacts. After the endpoint is created, the inference code
+                might use the IAM role, if it needs to access an AWS resource.
+            sagemaker_session (sagemaker.session.Session): Session object which
+                manages interactions with Amazon SageMaker APIs and any other
+                AWS services needed. If not specified, the estimator creates one
+                using the default AWS configuration chain.
+            **kwargs: Keyword arguments passed to the ``FrameworkModel``
+                initializer.
         """
         sagemaker_session = sagemaker_session or Session()
         image_uri = image_uris.retrieve(

src/sagemaker/amazon/kmeans.py

@@ -25,7 +25,11 @@
 
 
 class KMeans(AmazonAlgorithmEstimatorBase):
-    """Placeholder docstring"""
+    """An unsupervised learning algorithm that attempts to find discrete groupings within data.
+
+    As the result of KMeans, members of a group are as similar as possible to one another and as
+    different as possible from members of other groups. You define the attributes that you want
+    the algorithm to use to determine similarity. """
 
     repo_name = "kmeans"
     repo_version = 1
@@ -237,10 +241,19 @@ class KMeansModel(Model):
     def __init__(self, model_data, role, sagemaker_session=None, **kwargs):
         """
         Args:
-            model_data:
-            role:
-            sagemaker_session:
-            **kwargs:
+            model_data (str): The S3 location of a SageMaker model data
+                ``.tar.gz`` file.
+            role (str): An AWS IAM role (either name or full ARN). The Amazon
+                SageMaker training jobs and APIs that create Amazon SageMaker
+                endpoints use this role to access training data and model
+                artifacts. After the endpoint is created, the inference code
+                might use the IAM role, if it needs to access an AWS resource.
+            sagemaker_session (sagemaker.session.Session): Session object which
+                manages interactions with Amazon SageMaker APIs and any other
+                AWS services needed. If not specified, the estimator creates one
+                using the default AWS configuration chain.
+            **kwargs: Keyword arguments passed to the ``FrameworkModel``
+                initializer.
         """
         sagemaker_session = sagemaker_session or Session()
         image_uri = image_uris.retrieve(

src/sagemaker/amazon/knn.py

@@ -25,7 +25,12 @@
 
 
 class KNN(AmazonAlgorithmEstimatorBase):
-    """Placeholder docstring"""
+    """An index-based algorithm. It uses a non-parametric method for classification or regression.
+
+    For classification problems, the algorithm queries the k points that are closest to the sample
+    point and returns the most frequently used label of their class as the predicted label. For
+    regression problems, the algorithm queries the k closest points to the sample point and returns
+    the average of their feature values as the predicted value."""
 
     repo_name = "knn"
     repo_version = 1
@@ -225,10 +230,19 @@ class KNNModel(Model):
     def __init__(self, model_data, role, sagemaker_session=None, **kwargs):
         """
         Args:
-            model_data:
-            role:
-            sagemaker_session:
-            **kwargs:
+            model_data (str): The S3 location of a SageMaker model data
+                ``.tar.gz`` file.
+            role (str): An AWS IAM role (either name or full ARN). The Amazon
+                SageMaker training jobs and APIs that create Amazon SageMaker
+                endpoints use this role to access training data and model
+                artifacts. After the endpoint is created, the inference code
+                might use the IAM role, if it needs to access an AWS resource.
+            sagemaker_session (sagemaker.session.Session): Session object which
+                manages interactions with Amazon SageMaker APIs and any other
+                AWS services needed. If not specified, the estimator creates one
+                using the default AWS configuration chain.
+            **kwargs: Keyword arguments passed to the ``FrameworkModel``
+                initializer.
         """
         sagemaker_session = sagemaker_session or Session()
         image_uri = image_uris.retrieve(

src/sagemaker/amazon/lda.py

@@ -25,7 +25,12 @@
 
 
 class LDA(AmazonAlgorithmEstimatorBase):
-    """Placeholder docstring"""
+    """An unsupervised learning algorithm attempting to describe data as distinct categories.
+
+     LDA is most commonly used to discover a
+     user-specified number of topics shared by documents within a text corpus. Here each
+     observation is a document, the features are the presence (or occurrence count) of each
+     word, and the categories are the topics."""
 
     repo_name = "lda"
     repo_version = 1
@@ -209,10 +214,19 @@ class LDAModel(Model):
     def __init__(self, model_data, role, sagemaker_session=None, **kwargs):
         """
         Args:
-            model_data:
-            role:
-            sagemaker_session:
-            **kwargs:
+            model_data (str): The S3 location of a SageMaker model data
+                ``.tar.gz`` file.
+            role (str): An AWS IAM role (either name or full ARN). The Amazon
+                SageMaker training jobs and APIs that create Amazon SageMaker
+                endpoints use this role to access training data and model
+                artifacts. After the endpoint is created, the inference code
+                might use the IAM role, if it needs to access an AWS resource.
+            sagemaker_session (sagemaker.session.Session): Session object which
+                manages interactions with Amazon SageMaker APIs and any other
+                AWS services needed. If not specified, the estimator creates one
+                using the default AWS configuration chain.
+            **kwargs: Keyword arguments passed to the ``FrameworkModel``
+                initializer.
         """
         sagemaker_session = sagemaker_session or Session()
         image_uri = image_uris.retrieve(

src/sagemaker/amazon/linear_learner.py

@@ -25,7 +25,14 @@
 
 
 class LinearLearner(AmazonAlgorithmEstimatorBase):
-    """Placeholder docstring"""
+    """A supervised learning algorithms used for solving classification or regression problems.
+
+    For input, you give the model labeled examples (x, y). x is a high-dimensional vector and
+    y is a numeric label. For binary classification problems, the label must be either 0 or 1.
+    For multiclass classification problems, the labels must be from 0 to num_classes - 1. For
+    regression problems, y is a real number. The algorithm learns a linear function, or, for
+    classification problems, a linear threshold function, and maps a vector x to an approximation
+    of the label y."""
 
     repo_name = "linear-learner"
     repo_version = 1
@@ -468,10 +475,19 @@ class LinearLearnerModel(Model):
     def __init__(self, model_data, role, sagemaker_session=None, **kwargs):
         """
         Args:
-            model_data:
-            role:
-            sagemaker_session:
-            **kwargs:
+            model_data (str): The S3 location of a SageMaker model data
+                ``.tar.gz`` file.
+            role (str): An AWS IAM role (either name or full ARN). The Amazon
+                SageMaker training jobs and APIs that create Amazon SageMaker
+                endpoints use this role to access training data and model
+                artifacts. After the endpoint is created, the inference code
+                might use the IAM role, if it needs to access an AWS resource.
+            sagemaker_session (sagemaker.session.Session): Session object which
+                manages interactions with Amazon SageMaker APIs and any other
+                AWS services needed. If not specified, the estimator creates one
+                using the default AWS configuration chain.
+            **kwargs: Keyword arguments passed to the ``FrameworkModel``
+                initializer.
         """
         sagemaker_session = sagemaker_session or Session()
         image_uri = image_uris.retrieve(

src/sagemaker/amazon/ntm.py

@@ -25,7 +25,11 @@
 
 
 class NTM(AmazonAlgorithmEstimatorBase):
-    """Placeholder docstring"""
+    """An unsupervised learning algorithm used to organize a corpus of documents into topics
+
+    The resulting topics contain word groupings based on their statistical distribution.
+    Documents that contain frequent occurrences of words such as "bike", "car", "train",
+    "mileage", and "speed" are likely to share a topic on "transportation" for example."""
 
     repo_name = "ntm"
     repo_version = 1
@@ -239,10 +243,19 @@ class NTMModel(Model):
     def __init__(self, model_data, role, sagemaker_session=None, **kwargs):
         """
         Args:
-            model_data:
-            role:
-            sagemaker_session:
-            **kwargs:
+            model_data (str): The S3 location of a SageMaker model data
+                ``.tar.gz`` file.
+            role (str): An AWS IAM role (either name or full ARN). The Amazon
+                SageMaker training jobs and APIs that create Amazon SageMaker
+                endpoints use this role to access training data and model
+                artifacts. After the endpoint is created, the inference code
+                might use the IAM role, if it needs to access an AWS resource.
+            sagemaker_session (sagemaker.session.Session): Session object which
+                manages interactions with Amazon SageMaker APIs and any other
+                AWS services needed. If not specified, the estimator creates one
+                using the default AWS configuration chain.
+            **kwargs: Keyword arguments passed to the ``FrameworkModel``
+                initializer.
         """
         sagemaker_session = sagemaker_session or Session()
         image_uri = image_uris.retrieve(

src/sagemaker/amazon/object2vec.py

@@ -41,7 +41,11 @@ def validate(value):
 
 
 class Object2Vec(AmazonAlgorithmEstimatorBase):
-    """Placeholder docstring"""
+    """A general-purpose neural embedding algorithm that is highly customizable.
+
+    It can learn low-dimensional dense embeddings of high-dimensional objects. The embeddings
+    are learned in a way that preserves the semantics of the relationship between pairs of
+    objects in the original space in the embedding space."""
 
     repo_name = "object2vec"
     repo_version = 1
@@ -345,10 +349,19 @@ class Object2VecModel(Model):
     def __init__(self, model_data, role, sagemaker_session=None, **kwargs):
         """
         Args:
-            model_data:
-            role:
-            sagemaker_session:
-            **kwargs:
+            model_data (str): The S3 location of a SageMaker model data
+                ``.tar.gz`` file.
+            role (str): An AWS IAM role (either name or full ARN). The Amazon
+                SageMaker training jobs and APIs that create Amazon SageMaker
+                endpoints use this role to access training data and model
+                artifacts. After the endpoint is created, the inference code
+                might use the IAM role, if it needs to access an AWS resource.
+            sagemaker_session (sagemaker.session.Session): Session object which
+                manages interactions with Amazon SageMaker APIs and any other
+                AWS services needed. If not specified, the estimator creates one
+                using the default AWS configuration chain.
+            **kwargs: Keyword arguments passed to the ``FrameworkModel``
+                initializer.
         """
         sagemaker_session = sagemaker_session or Session()
         image_uri = image_uris.retrieve(

src/sagemaker/amazon/pca.py

@@ -25,7 +25,10 @@
 
 
 class PCA(AmazonAlgorithmEstimatorBase):
-    """Placeholder docstring"""
+    """An unsupervised machine learning algorithm to reduce feature dimensionality.
+
+    As a result, number of features within a dataset is reduced but the dataset still
+    retain as much information as possible."""
 
     repo_name = "pca"
     repo_version = 1
@@ -221,10 +224,19 @@ class PCAModel(Model):
     def __init__(self, model_data, role, sagemaker_session=None, **kwargs):
         """
         Args:
-            model_data:
-            role:
-            sagemaker_session:
-            **kwargs:
+            model_data (str): The S3 location of a SageMaker model data
+                ``.tar.gz`` file.
+            role (str): An AWS IAM role (either name or full ARN). The Amazon
+                SageMaker training jobs and APIs that create Amazon SageMaker
+                endpoints use this role to access training data and model
+                artifacts. After the endpoint is created, the inference code
+                might use the IAM role, if it needs to access an AWS resource.
+            sagemaker_session (sagemaker.session.Session): Session object which
+                manages interactions with Amazon SageMaker APIs and any other
+                AWS services needed. If not specified, the estimator creates one
+                using the default AWS configuration chain.
+            **kwargs: Keyword arguments passed to the ``FrameworkModel``
+                initializer.
         """
         sagemaker_session = sagemaker_session or Session()
         image_uri = image_uris.retrieve(