.. _contribution_guidelines.code.example: ============ Example ============ The vDataFrame a powerful Python object that lies at the heart of VerticaPy. :py:mod:`~verticapy.vDataFrame` consist of :py:mod:`~verticapy.vDataColumn` objects that represent columns in the dataset. You can find all :py:mod:`~verticapy.vDataFrame` methods inside the folder ``verticapy/core/vdataframe`` . Note that similar methods have been clubbed together inside one module/file. For examples, all methods pertaining to aggregates are in the ``_aggregate.py`` file. You can define any new :py:mod:`~verticapy.vDataFrame` method inside these modules depending on the nature of the method. The same applies to :py:mod:`~verticapy.vDataColumn` . You can use any of the developed classes to inherit properties. When defining a function, you should specify the ``type`` hints for every variable: - For variables of multiple types, use the Union operator. - For variables that are optional, use the Optional operator. - For variables that require literal input, use the Literal operator. There are examples of such hints throughout the code. .. code-block:: python @save_verticapy_logs def pie( self, columns: SQLColumns, max_cardinality: Union[None, int, tuple] = None, h: Union[None, int, tuple] = None, chart: Optional[PlottingObject] = None, **style_kwargs, ) -> PlottingObject: Be sure to write a detailed description for each function that explains how it works. .. code-block:: python """ Draws the nested density pie chart of the input vDataColumns. Parameters ---------- columns: SQLColumns List of the vDataColumns names. max_cardinality: int | tuple, optional Maximum number of distinct elements for vDataColumns 1 and 2 to be used as categorical. For these elements, no h is picked or computed. If of type tuple, represents the 'max_cardinality' of each column. h: int | tuple, optional Interval width of the bar. If empty, an optimized h will be computed. If of type tuple, it must represent each column's 'h'. chart: PlottingObject, optional The chart object to plot on. **style_kwargs Any optional parameter to pass to the plotting functions. """ .. important:: For a detailed explanation of how to write doc-strings, please refer to :ref:`contribution_guidelines.code.auto_doc` Important: the vDataFrame.get_columns() and vDataFrame.format_colnames() functions are essential for correctly formatting input column names. .. ipython:: python from verticapy.datasets import load_titanic titanic = load_titanic() titanic.get_columns() Use the :py:func:`~verticapy.vDataFrame.current_relation` method to get the current :py:mod:`~verticapy.vDataFrame` relation. .. ipython:: python titanic.current_relation() And the ``_executeSQL`` function to execute a SQL query. .. ipython:: python from verticapy._utils._sql._sys import _executeSQL _executeSQL(f"SELECT * FROM {titanic._genSQL()} LIMIT 2") The result of the query is accessible using one of the methods of the ``_executeSQL`` parameter. .. ipython:: python _executeSQL(f"SELECT * FROM {titanic._genSQL()} LIMIT 2",method="fetchall") The ``@save_verticapy_logs`` decorator saves information about a specified VerticaPy method to the ``QUERY_PROFILES`` table in the Vertica database. You can use this to collect usage statistics on methods and their parameters. For example, to create a method to compute the correlations between two :py:mod:`~verticapy.vDataFrame` columns: .. code-block:: python # Example correlation method for a vDataFrame # Add type hints + @save_verticapy_logs decorator @save_verticapy_logs def pearson(self, column1: str, column2: str): # Describe the function """ --------------------------------------------------------------------------- Computes the Pearson Correlation Coefficient of the two input vDataColumns. Parameters ---------- column1: str Input vDataColumn. column2: str Input vDataColumn. Returns ------- Float Pearson Correlation Coefficient See Also -------- vDataFrame.corr : Computes the Correlation Matrix of the vDataFrame. """ # Check data types # Format the columns column1, column2 = self.format_colnames([column1, column2]) # Get the current vDataFrame relation table = self._genSQL() # Create the SQL statement - Label the query when possible query = f"SELECT /*+LABEL(vDataFrame.pearson)*/ CORR({column1}, {column2}) FROM {table};" # Execute the SQL query and get the result result = _executeSQL(query, title = "Computing Pearson coefficient", method="fetchfirstelem") # Return the result return result Same can be done with :py:mod:`~verticapy.vDataColumn` methods. .. code-block:: python # Example Method for a vDataColumn # Add types hints + @save_verticapy_logs decorator @save_verticapy_logs def pearson(self, column: str,): # Describe the function """ --------------------------------------------------------------------------- Computes the Pearson Correlation Coefficient of the vDataColumn and the input vDataColumn. Parameters ---------- column: str Input vDataColumn. Returns ------- Float Pearson Correlation Coefficient See Also -------- vDataFrame.corr : Computes the Correlation Matrix of the vDataFrame. """ # Format the column column1 = self.parent.format_colnames([column])[0] # Get the current vDataColumn name column2 = self.alias # Get the current vDataFrame relation table = self.parent._genSQL() # Create the SQL statement - Label the query when possible query = f"SELECT /*+LABEL(vDataColumn.pearson)*/ CORR({column1}, {column2}) FROM {table};" # Execute the SQL query and get the result result = executeSQL(query, title = "Computing Pearson coefficient", method="fetchfirstelem") # Return the result return result Functions will work exactly the same.