Teradata Package for Python Function Reference - Histogram - Teradata Package for Python - Look here for syntax, methods and examples for the functions included in the Teradata Package for Python.

Teradata® Package for Python Function Reference
Product
Teradata Package for Python
Release Number
17.00
Published
November 2021
Language
English (United States)
Last Update
2021-11-19
lifecycle
previous
Product Category
Teradata Vantage
 
 
Histogram

 
Functions
       
Histogram(data, columns=None, bins=10, bins_with_boundaries=None, boundaries=None, quantiles=10, widths=None, exclude_columns=None, overlay_columns=None, stats_columns=None, hist_style='basic', filter=None)
DESCRIPTION:
    Histogram analysis reveals the distribution of continuous numeric or date values
    in a column. Histogram analysis is also referred to as binning because it counts the
    occurrence of values in a series of numeric ranges called bins. The histogram
    analysis provides a number of ways to define bins, allowing multidimensional binning,
    overlaying of categorical data, and the calculation of numeric statistics within
    bins. If you set the desired number of equal sized data bins, the desired number of
    bins with a nearly equal number of values, a desired width, or the specific boundaries,
    the Histogram analysis separates the data to show its distributional properties.
    It does this by separating the data by bin number and gives counts and percentages
    over the requested rows. Percentages always sum to 100%. Separate options are available
    to specify a number of equal sized data bins in which the analysis determines the
    minimum and maximum value, as well as a user-specified minimum and maximum value.
    If the minimum and maximum are specified, all values less than the minimum are put in
    bin 0, while all values greater than the maximum are put in bin N+1. The same is
    true when the boundary option is specified.
 
    The Histogram analysis optionally provides subtotals within each bin of the count,
    percentage within the bin and percentage overall for each value or combination of
    values of one or more overlaid columns. Another option is provided to collect simple
    statistics for a binned column or another column of numeric or date type within the
    table, providing the minimum, maximum, mean, and standard deviation. When statistics
    are collected for a date type column, the standard deviation is given in units of days.
    Histogram analysis can be performed on columns of numeric or date data type.
 
PARAMETERS:
    data:
        Required Argument.
        Specifies the input data to perform Histogram analysis.
        Types: teradataml DataFrame
 
    columns:
        Required Argument.
        Specifies the name(s) of the column(s) to analyze. Occasionally, it can also
        accept permitted strings to specify all columns, or all numeric columns, or
        all numeric and date columns.
        Permitted Values:
            * Name(s) of the column(s) in "data".
            * Pre-defined strings:
                * 'all' - all columns
                * 'allnumeric' - all numeric columns
                * 'allnumericanddate' - all numeric and date columns
        Types: str OR list of Strings (str)
 
    bins:
        Optional Argument.
        Specifies the number of equal width bins to create.
        If multiple columns are requested, multiple bin sizes may be specified, such
        as bins = [5, 10]. If fewer sizes are specified than columns, left-over columns
        are associated with the default size of 10 bins.
        Default Value: 10
        Types: int OR list of Integers (int)
 
    bins_with_boundaries:
        Optional Argument.
        Specifies the number of bins spanning a range specified by the minimum and
        maximum values.
        For example,
            bins_with_boundaries = [5,0,200]
            creates 5 bins ranging from 0 to 200.
        If multiple columns are requested, multiple sets of parameters must be
        specified, such as bins_with_boundaries = ["{10, 0, 200000}", "{5, 0, 100}"].
        Note that multiple values are provided as string with numbers enclosed in curly
        braces '{}'. Each such value corresponds to the value in "columns" argument.
        Types: int, str OR list of Integers (int) or Strings (str)
 
    boundaries:
        Optional Argument.
        Specifies the boundaries that define the bins.
        For example,
            boundaries = [0,50,100,150]
            provides 3 bins between 0 and 150 (0 to 50, 50 to 100, and 100 to 150).
        If multiple columns are requested, multiple sets of parameters must be
        specified, such as boundaries = ["{0, 50000, 100000, 150000}", "{0, 50, 100}"].
        Note that multiple values are provided as string with numbers enclosed in curly
        braces '{}'. Each such value corresponds to the value in "columns" argument.
        Types: int, str OR list of Integers (int) or Strings (str)
 
    quantiles:
        Optional Argument.
        Specifies the number of approximately equally populated bins to create.
        If multiple columns are requested, multiple quantile sizes may be specified,
        such as quantiles=5, 10. If fewer sizes are specified than columns, left-over
        columns are associated with the default size of 10 quantiles.
        Default Value: 10
        Types: int OR list of Integers (int)
 
    widths:
        Optional Argument.
        Specifies the width of the bins to create.
        If multiple columns are requested, multiple widths must be specified, such
        as widths = [5, 10]. If fewer sizes are specified than columns, an error
        message displays.
        Types: int OR list of Integers (int)
 
    exclude_columns:
        Optional Argument.
        Specifies the name(s) of the column(s) to exclude from the analysis, if a
        column specifier such as 'all', 'allnumeric', 'allnumericanddate' is used
        in the "columns" argument.
        Types: str OR list of Strings (str)
 
    overlay_columns:
        Optional Argument.
        Specifies a categorical variable with only a few values. If an overlay column
        is specified, frequencies within each bin are calculated for each value of
        that overlay column (frequencies for crosstabs of values are given if more
        than one overlay column is requested).
        Note:
            Use a specific column in either "overlay_columns" or "stats_columns",
            but not both.
        Types: str OR list of Strings (str)
 
    stats_columns:
        Optional Argument.
        Specifies a list of numeric columns/aliases for which simple statistics are
        calculated (minimum, maximum, mean and standard deviation) in each bin. This
        argument is not available for DATE columns.
        Note:
            Use a specific column in either "overlay_columns" or "stats_columns",
            but not both.
        Types: str OR list of Strings (str)
 
    hist_style:
        Optional Argument.
        Specifies the histogram style to use for analysis.
        Permitted Values:
            * 'basic' - Creates a histogram for individual columns.
            * 'crosstab' - Creates a multidimensional histogram by combining columns.
        Default Value: 'basic'
        Types: str
 
    filter:
        Optional Argument.
        Specifies the clause to filter rows selected for analysis within Histogram.
        For example,
            filter = "cust_id > 0"
        Types: str
 
RETURNS:
    An instance of Histogram.
    Output teradataml DataFrames can be accessed using attribute references, such as
    HistogramObj.<attribute_name>.
    Output teradataml DataFrame attribute name is: result.
 
RAISES:
    TeradataMlException, TypeError, ValueError
 
EXAMPLES:
    # Notes:
    #   1. To execute Vantage Analytic Library functions,
    #       a. import "valib" object from teradataml.
    #       b. set 'configure.val_install_location' to the database name where Vantage
    #          analytic library functions are installed.
    #   2. Datasets used in these examples can be loaded using Vantage Analytic Library
    #      installer.
    # Import valib object from teradataml to execute this function.
    from teradataml import valib
 
    # Set the 'configure.val_install_location' variable.
    from teradataml import configure
    configure.val_install_location = "SYSLIB"
 
    # Create required teradataml DataFrame.
    df = DataFrame("customer")
    print(df)
 
    # Example 1: Perform Histogram analysis using default values.
    obj = valib.Histogram(data=df,
                          columns=["income", "age"])
 
    # Print the results.
    print(obj.result)
 
    # Example 2: Perform Histogram analysis using "overlay_columns".
    obj = valib.Histogram(data=df,
                          columns=["income", "age"],
                          overlay_columns="gender")
 
    # Print the results.
    print(obj.result)
 
    # Example 3: Perform Histogram analysis using "stats_columns".
    obj = valib.Histogram(data=df,
                          columns=["income", "age"],
                          stats_columns="years_with_bank")
 
    # Print the results.
    print(obj.result)
 
    # Example 4: Perform Histogram analysis using "crosstab" style, with filter.
    obj = valib.Histogram(data=df,
                          columns=["income", "age"],
                          hist_style="crosstab",
                          filter="income > 0")
 
    # Print the results.
    print(obj.result)
 
    # Example 5: Perform Histogram analysis by specifying number of "bins".
    obj = valib.Histogram(data=df,
                          columns="income",
                          bins=5)
 
    # Print the results.
    print(obj.result)
 
    # Example 6: Perform Histogram analysis by specifying bin width.
    obj = valib.Histogram(data=df,
                          columns="income",
                          widths=25000)
 
    # Print the results.
    print(obj.result)
 
    # Example 7: Perform Histogram analysis by specifying number of quantiles.
    obj = valib.Histogram(data=df,
                          columns="income",
                          quantiles=4)
 
    # Print the results.
    print(obj.result)
 
    # Example 8: Perform Histogram analysis by specifying boundaries on single column.
    obj = valib.Histogram(data=df,
                          columns="income",
                          boundaries=[0, 50000, 100000, 150000])
 
    # Print the results.
    print(obj.result)
 
    # Example 9: Perform Histogram analysis by specifying boundaries on multiple columns.
    obj = valib.Histogram(data=df,
                          columns=["income", "age"],
                          boundaries=["{0, 50000, 100000, 150000}", "{0,25,50,75}"])
 
    # Print the results.
    print(obj.result)
 
    # Example 10: Perform Histogram analysis by specifying bins with boundaries
    #             on single column.
    obj = valib.Histogram(data=df,
                          columns="income",
                          bins_with_boundaries=[10, 0, 200000])
 
    # Print the results.
    print(obj.result)
 
    # Example 11: Perform Histogram analysis by specifying boundaries on multiple columns.
    obj = valib.Histogram(data=df,
                          columns=["income", "age"],
                          bins_with_boundaries=["{10, 0, 200000}", "{5, 0, 75}"])
 
    # Print the results.
    print(obj.result)