:orphan:

.. _chart_gallery.candlestick:

===========
Candlestick
===========

.. Necessary Code Elements

.. ipython:: python
    :suppress:

    import vastorbit as vo

    N = 20 # Number of records

    data = vo.VastFrame({
        "date": [1990 + i for i in range(N)] * 5,
        "population": [100 + i for i in range(N)] + [300 + i * 2 for i in range(N)] + [200 + i ** 2 - 3 * i for i in range(N)] + [50 + i ** 2 - 6 * i for i in range(N)] + [700 + i ** 2 - 10 * i for i in range(N)],
    })


General
-------

Let's begin by importing ``vastorbit``.

.. ipython:: python

    import vastorbit as vo

Let's generate a dataset using the following data.

.. code-block:: python
        
    N = 20 # Number of records

    data = vo.VastFrame({
        "date": [1990 + i for i in range(N)] * 5,
        "population": [100 + i for i in range(N)] + [300 + i * 2 for i in range(N)] + [200 + i ** 2 - 3 * i for i in range(N)] + [50 + i ** 2 - 6 * i for i in range(N)] + [700 + i ** 2 - 10 * i for i in range(N)],
    })

In the context of data visualization, we have the flexibility to harness multiple plotting libraries to craft a wide range of graphical representations. vastorbit, as a versatile tool, provides support for several graphic libraries, such as Matplotlib and Plotly. Each of these libraries offers unique features and capabilities, allowing us to choose the most suitable one for our specific data visualization needs.

.. image:: ../../docs/source/_static/plotting_libs.png
   :width: 80%
   :align: center

.. note::
    
    To select the desired plotting library, we simply need to use the :py:func:`~vastorbit.set_option` function. vastorbit offers the flexibility to smoothly transition between different plotting libraries. In instances where a particular graphic is not supported by the chosen library or is not supported within the vastorbit framework, the tool will automatically generate a warning and then switch to an alternative library where the graphic can be created.

Please click on the tabs to view the various graphics generated by the different plotting libraries.

.. ipython:: python
    :suppress:

    import vastorbit as vo

.. tab:: Plotly

    .. ipython:: python
        :suppress:

        vo.set_option("plotting_lib", "plotly")

    We can switch to using the ``plotly`` module.

    .. code-block:: python
        
        vo.set_option("plotting_lib", "plotly")

    vastorbit's candlestick visualization feature empowers data analysts and financial professionals to gain valuable insights from time-series data. By representing open, close, high, and low price values for a specific period, candlestick charts offer a clear and intuitive view of price movements, helping users identify trends, reversals, and patterns in financial data. This tool enhances decision-making in areas such as stock trading, investment analysis, and financial forecasting, making it an indispensable asset for those working with time-series financial data.

    .. tab:: Python

      .. code-block:: python
          
          data["population"].candlestick(ts = "date")

    .. tab:: SQL

      We load the vastorbit `chart` extension.

        .. code-block:: python

            %load_ext vastorbit.chart

        We write the SQL query using Jupyter magic cells.

        .. code-block:: sql
            
            %%chart -k candlestick
            SELECT 
                date,
                MIN(population) AS min,
                APPROX_PERCENTILE(population 
                                      , 0.25) AS q1,
                APPROX_PERCENTILE(population 
                                      , 0.50) AS q2,
                APPROX_PERCENTILE(population 
                                      , 0.75) AS q3,
                MAX(population) AS max,
                SUM(population) AS sum
            FROM
            :data
            GROUP BY 1
            ORDER BY 1

    .. ipython:: python
        :suppress:
        :okwarning:
        
        fig = data["population"].candlestick(ts = "date")
        fig.write_html("figures/plotting_plotly_candlestick.html")

    .. raw:: html
        :file: /Users/badr.ouali/Documents/VastOrbit-master/docs/figures/plotting_plotly_candlestick.html
        
.. tab:: Matplotlib

    .. ipython:: python
        :suppress:

        vo.set_option("plotting_lib", "matplotlib")

    We can switch to using the ``matplotlib`` module.

    .. code-block:: python
        
        vo.set_option("plotting_lib", "matplotlib")

    vastorbit's candlestick visualization feature empowers data analysts and financial professionals to gain valuable insights from time-series data. By representing open, close, high, and low price values for a specific period, candlestick charts offer a clear and intuitive view of price movements, helping users identify trends, reversals, and patterns in financial data. This tool enhances decision-making in areas such as stock trading, investment analysis, and financial forecasting, making it an indispensable asset for those working with time-series financial data.

    .. tab:: Python

      .. ipython:: python
        :okwarning:

        @savefig plotting_matplotlib_candlestick.png
        data["population"].candlestick(ts = "date")

    .. tab:: SQL

      We load the vastorbit `chart` extension.

        .. code-block:: python

            %load_ext vastorbit.chart

        We write the SQL query using Jupyter magic cells.

        .. code-block:: sql
            
            %%chart -k candlestick
            SELECT 
                date,
                MIN(population) AS min,
                APPROX_PERCENTILE(population 
                                      , 0.25) AS q1,
                APPROX_PERCENTILE(population 
                                      , 0.50) AS q2,
                APPROX_PERCENTILE(population 
                                      , 0.75) AS q3,
                MAX(population) AS max,
                SUM(population) AS sum
            FROM
            :data
            GROUP BY 1
            ORDER BY 1;

        .. image:: ../../docs/source/savefig/plotting_matplotlib_candlestick.png
            :width: 100%
            :align: center
        
_________________

Custom Parameters
-----------------

.. hint:: In vastorbit, when working with candlestick visualizations, you have the flexibility to select the quantiles and the primary aggregation method that best suits your data analysis needs. This capability allows you to tailor your candlestick charts to precisely represent the data distribution and trends, providing a customized and insightful view of your financial data.

.. note::

    In SQL, aggregations can be computed directly within the input SQL statement, but in Python, the process is a bit different.

.. tab:: Plotly

    .. ipython:: python
        :suppress:

        vo.set_option("plotting_lib", "plotly")

    **Quantiles**

    .. code-block:: python
        
        data["population"].candlestick(ts = "date", q = (0.1, 0.9))

    .. ipython:: python
        :suppress:
        :okwarning:

        fig = data["population"].candlestick(ts = "date", q = (0.1, 0.9))
        fig.write_html("figures/plotting_plotly_candlestick_custom_q.html")

    .. raw:: html
        :file: /Users/badr.ouali/Documents/VastOrbit-master/docs/figures/plotting_plotly_candlestick_custom_q.html

    .. note:: By selecting the tuple (0.1, 0.9), we are effectively utilizing the values corresponding to the first and ninth deciles of the data distribution.

.. tab:: Matplolib

    .. ipython:: python
        :suppress:

        vo.set_option("plotting_lib", "matplotlib")

    **Quantiles**

    .. ipython:: python
        :okwarning:

        @savefig plotting_matplotlib_candlestick_custom_q.png
        data["population"].candlestick(ts = "date", q = (0.1, 0.9))

    .. note:: By selecting the tuple (0.1, 0.9), we are effectively utilizing the values corresponding to the first and ninth deciles of the data distribution.
        
___________________


Chart Customization
-------------------

vastorbit empowers users with a high degree of flexibility when it comes to tailoring the visual aspects of their plots. 
This customization extends to essential elements such as **color schemes**, **text labels**, and **plot sizes**, as well as a wide range of other attributes that can be fine-tuned to align with specific design preferences and analytical requirements. Whether you want to make your visualizations more visually appealing or need to convey specific insights with precision, vastorbit's customization options enable you to craft graphics that suit your exact needs.

.. hint::

    For SQL users who use Jupyter Magic cells, chart customization must be done in Python. They can then export the graphic using the last magic cell result.

    .. code-block:: python

        chart = _

    Now, the chart variable includes the graphic. Depending on the library you are using, you will obtain a different object.

.. Important:: Different customization parameters are available for Plotly and Matplotlib. 
    For a comprehensive list of customization features, please consult the documentation of the respective 
    libraries: `plotly <https://plotly.com/python-api-reference/>`__, `matplotlib <https://matplotlib.org/stable/api/matplotlib_configuration_api.html>`__.

Colors
~~~~~~

.. tab:: Plotly

    .. ipython:: python
        :suppress:

        vo.set_option("plotting_lib", "plotly")

    **Custom colors**

    .. code-block:: python
        
        fig = data["population"].candlestick(ts = "date", colors = ["blue","pink"])

    .. ipython:: python
        :suppress:
        :okwarning:

        fig = data["population"].candlestick(ts = "date", colors = ["blue","pink"])
        fig.write_html("figures/plotting_plotly_candlestick_custom_color_1.html")

    .. raw:: html
        :file: /Users/badr.ouali/Documents/VastOrbit-master/docs/figures/plotting_plotly_candlestick_custom_color_1.html

    .. note::

        The first color in the list is for increasing values, while the second color is for decreasing values.

.. tab:: Matplolib

    .. ipython:: python
        :suppress:

        vo.set_option("plotting_lib", "matplotlib")

    **Custom colors**

    .. ipython:: python
        :okwarning:

        @savefig plotting_matplotlib_candlestick_custom_color_1.png
        data["population"].candlestick(ts = "date", colors = ["blue","pink"])

    .. note::

        The first color in the list is for increasing values, while the second color is for decreasing values.

____

Size
~~~~

.. tab:: Plotly

    .. ipython:: python
        :suppress:

        vo.set_option("plotting_lib", "plotly")

    **Custom Width and Height**

    .. code-block:: python
        
        data["population"].candlestick(ts = "date", width = 300, height = 300)

    .. ipython:: python
        :suppress:
        :okwarning:

        fig = data["population"].candlestick(ts = "date", width = 300, height = 300)
        fig.write_html("figures/plotting_plotly_candlestick_custom_size.html")

    .. raw:: html
        :file: /Users/badr.ouali/Documents/VastOrbit-master/docs/figures/plotting_plotly_candlestick_custom_size.html

.. tab:: Matplolib

    .. ipython:: python
        :suppress:

        vo.set_option("plotting_lib", "matplotlib")

    **Custom Width and Height**

    .. ipython:: python
        :okwarning:

        @savefig plotting_matplotlib_candlestick_custom_size.png
        data["population"].candlestick(ts = "date", width = 6, height = 3)

_____


Text
~~~~

.. tab:: Plotly

    .. ipython:: python
        :suppress:

        vo.set_option("plotting_lib", "plotly")

    **Custom Title**

    .. code-block:: python
        
        data["population"].candlestick(ts = "date").update_layout(title_text = "Custom Title")

    .. ipython:: python
        :suppress:
        :okwarning:

        fig = data["population"].candlestick(ts = "date").update_layout(title_text = "Custom Title")
        fig.write_html("figures/plotting_plotly_candlestick_custom_main_title.html")

    .. raw:: html
        :file: /Users/badr.ouali/Documents/VastOrbit-master/docs/figures/plotting_plotly_candlestick_custom_main_title.html

    **Custom Axis Titles**

    .. code-block:: python
        
        data["population"].candlestick(ts = "date", yaxis_title = "Custom Y-Axis Title")

    .. ipython:: python
        :suppress:
        :okwarning:

        fig = data["population"].candlestick(ts = "date", yaxis_title = "Custom Y-Axis Title")
        fig.write_html("figures/plotting_plotly_candlestick_custom_y_title.html")

    .. raw:: html
        :file: /Users/badr.ouali/Documents/VastOrbit-master/docs/figures/plotting_plotly_candlestick_custom_y_title.html

.. tab:: Matplolib

    .. ipython:: python
        :suppress:

        vo.set_option("plotting_lib", "matplotlib")

    **Custom Title Text**

    .. ipython:: python
        :okwarning:

        @savefig plotting_matplotlib_candlestick_custom_title_label.png
        data["population"].candlestick(ts = "date").set_title("Custom Title")

    **Custom Axis Titles**

    .. ipython:: python
        :okwarning:

        @savefig plotting_matplotlib_candlestick_custom_yaxis_label.png
        data["population"].candlestick(ts = "date").set_ylabel("Custom Y Axis")

.. ipython:: python
   :suppress:

   from vastorbit._utils._sql._sys import purge_memory
   purge_memory()