Teradata Package for Python Function Reference - 17.00 - Sampling - Teradata Package for Python

Teradata® Package for Python Function Reference

Product
Teradata Package for Python
Release Number
17.00
Release Date
April 2021
Content Type
Programming Reference
Publication ID
B700-4008-070K
Language
English (United States)

 
teradataml.analytics.mle.Sampling = class Sampling(builtins.object)
     Methods defined here:
__init__(self, data=None, summary_data=None, stratum_column=None, strata=None, sample_fraction=None, approx_sample_size=None, seed=0, data_sequence_column=None, summary_data_sequence_column=None, data_partition_column='ANY', data_order_column=None, summary_data_order_column=None)
DESCRIPTION:
    The Sample function draws rows randomly from the teradataml DataFrame.
    The function offers two sampling schemes:
        • A simple Bernoulli (Binomial) sampling on a row-by-row basis
          with given sample rates
        • Sampling without replacement that selects a given number of
          rows.
    Sampling can be either unconditional or conditional. Unconditional
    sampling applies to all input data and always uses the same random
    number generator. Conditional sampling applies only to input data
    that meets specified conditions and uses a diƒerent random number
    generator for each condition.
 
    Note: The Sampling function does not guarantee the exact sizes of
          samples. If each sample must have an exact number of rows, use the
          RandomSample function.
 
PARAMETERS:
    data:
        Required Argument.
        Specifies the teradataml DataFrame containing the data to be
        sampled.
 
    data_partition_column:
        Optional Argument.
        Specifies Partition By columns for data.
        Values to this argument can be provided as list, if multiple
        columns are used for partition.
        Default Value: ANY
        Types: str OR list of Strings (str)
 
    data_order_column:
        Optional Argument.
        Specifies Order By columns for data.
        Values to this argument can be provided as list, if multiple columns
        are used for ordering.
        Types: str OR list of Strings (str)
 
    summary_data:
        Optional Argument.
        Specifies the teradataml DataFrame containing the stratum count
        information.
        Note: summary_data argument is only available when teradataml is
              connected to Vantage 1.1 or later versions.
 
    summary_data_order_column:
        Optional Argument.
        Specifies Order By columns for summary_data.
        Values to this argument can be provided as list, if multiple columns
        are used for ordering.
        Types: str OR list of Strings (str)
 
    stratum_column:
        Optional Argument.
        Specifies the name of the column that contains the sample conditions.
        If the function has only one input teradataml DataFrame (data),
        then condition column is in the data teradataml DataFrame. If the function
        has two input teradataml DataFrames, data and summary_data, then
        condition column is in the summary_data teradataml DataFrame.
        Types: str
 
    strata:
        Optional Argument.
        Specifies the sample conditions that appear in the stratum_column.
        If strata specifies a condition that does not appear in
        stratum_column, then the function issues an error message.
        Types: str or list of Strings (str)
 
    sample_fraction:
        Optional Argument.
        Specifies one or more fractions to use in sampling the data .
        (Syntax options that do not use sample_fraction require
        approx_sample_size.)
        If you specify only one fraction, then the function uses fraction
        for all strata defined by the sample conditions. If you specify
        more than one fraction, then the function uses each fraction for
        sampling a particular stratum defined by the condition arguments.
        Note: For conditional sampling with variable sample sizes,
              specify one fraction for each condition that you specify with
              the strata argument.
        Types: float or list of Floats (float)
 
    approx_sample_size:
        Optional Argument.
        Specifies one or more approximate sample sizes to use in sampling the
        data (syntax options that do not use approx_sample_size require
        sample_fraction). Each sample size is approximate because the
        function maps the size to the sample fractions and then generates the
        sample data. If you specify only one size, then it represents the
        total sample size for the entire population. If you also specify the
        strata argument, then the function proportionally generates sample
        units for each stratum. If you specify more than one size, then each
        size corresponds to a stratum, and the function uses each size to
        generate sample units for the corresponding stratum.
        Note: For conditional sampling with variable approximate sample
              sizes, specify one size for each condition that you specify with
              the strata argument.
        Types: int or list of Integers (int)
 
    seed:
        Optional Argument.
        Specifies the random seed used to initialize the algorithm.
        Default Value: 0
        Types: int
 
    data_sequence_column:
        Optional Argument.
        Specifies the list of column(s) that uniquely identifies each row of
        the input argument "data". The argument is used to ensure
        deterministic results for functions which produce results that vary
        from run to run.
        Types: str OR list of Strings (str)
 
    summary_data_sequence_column:
        Optional Argument.
        Specifies the list of column(s) that uniquely identifies each row of
        the input argument "summary_data". The argument is used to ensure
        deterministic results for functions which produce results that vary
        from run to run.
        Types: str OR list of Strings (str)
 
RETURNS:
    Instance of Sampling.
    Output teradataml DataFrames can be accessed using attribute
    references, such as SamplingObj.<attribute_name>.
    Output teradataml DataFrame attribute name is:
        result
 
 
RAISES:
    TeradataMlException
 
 
EXAMPLES:
    # Load example data.
    load_example_data("Sampling", ["students","score_category","score_summary"])
 
    # Create teradataml DataFrame objects.
    # The input table "score_category" is obtained by categorizing the
    # students in the "students" table based on their score in a given
    # subject. There are 100 students grouped into three categories -
    # excellent (score > 90), very good (80 < score < 90) and fair
    # (score < 80). The table "score_summary" groups the score_category
    # table based on the stratum column and also has their corresponding
    # count.
 
    students = DataFrame.from_table("students")
    score_category = DataFrame.from_table("score_category")
    score_summary = DataFrame.from_table("score_summary")
 
    # Example 1 - This example selects a sample of approximately 20%
    # of the rows in the student table.
    sampling_out1 = Sampling(data = students,
                             sample_fraction = 0.2,
                             seed = 2
                             )
 
    # Print the result teradataml DataFrame
    print(sampling_out1)
 
    # Example 2 - This example applies sampling rates 20%, 30%, and 40%
    # to categories fair, very good, and excellent, respectively, and
    # rounds the number sampled to the nearest integer.
    sampling_out2 = Sampling(data = score_category,
                              data_partition_column = "stratum",
                              stratum_column = "stratum",
                              strata = ["fair", "very good", "excellent"],
                              sample_fraction = [0.2, 0.3, 0.4],
                              seed = 2
                              )
 
    # Print the result teradataml DataFrame
    print(sampling_out2.result)
 
    # Example 3 - This examples demonstrates conditional sampling with
    # Approximate Sample Size.
    sampling_out3 = Sampling(data=score_category,
                           summary_data=score_summary,
                           stratum_column='stratum',
                           strata=['excellent','fair','very good'],
                           approx_sample_size=[5,10,5],
                           seed=2
                          )
    # Print the result teradataml DataFrame
    print(sampling_out3.result)
__repr__(self)
Returns the string representation for a Sampling class instance.
get_build_time(self)
Function to return the build time of the algorithm in seconds.
When model object is created using retrieve_model(), then the value returned is 
as saved in the Model Catalog.
get_prediction_type(self)
Function to return the Prediction type of the algorithm.
When model object is created using retrieve_model(), then the value returned is 
as saved in the Model Catalog.
get_target_column(self)
Function to return the Target Column of the algorithm.
When model object is created using retrieve_model(), then the value returned is 
as saved in the Model Catalog.
show_query(self)
Function to return the underlying SQL query.
When model object is created using retrieve_model(), then None is returned.