:orphan:

.. _chart_gallery.density:

=======
Density
=======

.. Necessary Code Elements

.. ipython:: python
    :suppress:

    import vastorbit as vo
    import numpy as np

    N = 100

    data = vo.VastFrame({
      "category": [np.random.choice(['A','B','C']) for _ in range(N)],
      "score1": np.random.normal(5, 1, N),
      "score2": np.random.normal(8, 1.5, N),
      "score3": np.random.normal(10, 2, N),
    })


General
-------

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

.. ipython:: python

    import vastorbit as vo

Let's also import ``numpy`` to create a random dataset.

.. ipython:: python

    import numpy as np

Let's generate a dataset using the following data.

.. code-block:: python
        
    N = 100
    data = vo.VastFrame({
      "category": [np.random.choice(['A','B','C']) for _ in range(N)],
      "score1": np.random.normal(5, 1, N),
      "score2": np.random.normal(8, 1.5, N),
      "score3": np.random.normal(10, 2, 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")

    In vastorbit, you have the flexibility to generate either a single density plot or multiple density plots within a single graphical representation.
    
    .. tab:: Single

      .. code-block:: python
          
          data["score1"].density()

      .. ipython:: python
          :suppress:
        
          fig = data["score1"].density(width = 600)
          fig.write_html("figures/plotting_plotly_density_single.html")

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

    .. tab:: Multi

      .. code-block:: python
          
          data.density(columns = ["score1", "score2", "score3"])

      .. ipython:: python
          :suppress:

          fig = data.density(columns = ["score1", "score2", "score3"], width = 600)
          fig.write_html("figures/plotting_plotly_density_multi.html")

      .. raw:: html
          :file: /Users/badr.ouali/Documents/VastOrbit-master/docs/figures/plotting_plotly_density_multi.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")

    In vastorbit, you have the flexibility to generate either a single density plot or multiple density plots within a single graphical representation.

    .. tab:: Single

      .. ipython:: python
          :okwarning:

          @savefig plotting_matplotlib_density_single.png
          data["score1"].density()

    .. tab:: Multi

      .. ipython:: python
          :okwarning:

          @savefig plotting_matplotlib_density_multi.png
          data.density(columns = ["score1", "score2", "score3"])

___________________

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

In vastorbit, you can tune the resolution of a density plot with the ``nbins`` parameter. ``nbins`` sets how many points are used to evaluate the estimated density curve: a lower value yields a coarser, smoother-looking curve that emphasizes the overall shape, while a higher value captures finer detail in the distribution.

.. tab:: Plotly

    .. ipython:: python
        :suppress:

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

    **Smoother (fewer bins)**

    .. code-block:: python
        
        data["score1"].density(nbins = 50)

    .. ipython:: python
        :suppress:

        fig = data["score1"].density(nbins = 50, width = 600)
        fig.write_html("figures/plotting_plotly_density_custom_bandwidth.html")

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

    .. note:: Lowering ``nbins`` smooths the curve and reduces granularity, which is useful for emphasizing the overall shape of the distribution.

    **More detail (more bins)**

    .. note:: Raising ``nbins`` increases the resolution of the estimate, letting the curve follow finer features of your data distribution.

    .. code-block:: python
        
        data["score1"].density(nbins = 200)

    .. ipython:: python
        :suppress:

        fig = data["score1"].density(nbins = 200, width = 600)
        fig.write_html("figures/plotting_plotly_density_custom_kernel.html")

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

.. tab:: Matplolib

    .. ipython:: python
        :suppress:

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

    **Smoother (fewer bins)**

    .. ipython:: python
        :okwarning:

        @savefig plotting_matplotlib_density_custom_bandwidth.png
        data["score1"].density(nbins=50)

    .. note:: Lowering ``nbins`` smooths the curve and reduces granularity, which is useful for emphasizing the overall shape of the distribution.

    **More detail (more bins)**

    .. note:: Raising ``nbins`` increases the resolution of the estimate, letting the curve follow finer features of your data distribution.

    .. ipython:: python
        :okwarning:

        @savefig plotting_matplotlib_density_custom_kernel.png
        data["score1"].density(nbins=200)



________

Grouping
--------


.. tab:: Plotly

    .. ipython:: python
        :suppress:

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

    Group by categories.

    .. code-block:: python
        
        data["score1"].density(by = "category")

    .. ipython:: python
        :suppress:

        fig = data["score1"].density(by = "category", width = 600)
        fig.write_html("figures/plotting_plotly_density_groupby.html")

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

.. tab:: Matplolib

    .. ipython:: python
        :suppress:

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

    Group by categories.

    .. ipython:: python

        @savefig plotting_matplotlib_density_1D_groupby.png
        data["score1"].density(by = "category")

___________________


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.

.. 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 for 1D**

    .. code-block:: python
        
        fig = data["score1"].density()
        fig.update_traces(marker = dict(color="red"))

    .. ipython:: python
        :suppress:

        fig = data["score1"].density(width = 600)
        fig.update_traces(marker = dict(color = "red"))
        fig.write_html("figures/plotting_plotly_density_custom_color_1.html")

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

    **Custom colors mapping for categories**

    .. note:: You can leverage all the capabilities of the Plotly object, including functions like `update_trace`.

    .. code-block:: python
        
        fig = data.density(columns = ["score1", "score2", "score3"])
        new_colors = ["red", "orange","green"]
        for trace_index, new_color in enumerate(new_colors):
            if trace_index < len(fig.data):
                fig.data[trace_index].marker.color = new_color

    .. ipython:: python
        :suppress:

        fig = data.density(columns = ["score1", "score2", "score3"])
        new_colors = ["red", "orange","green"]
        for trace_index, new_color in enumerate(new_colors):
            if trace_index < len(fig.data):
                fig.data[trace_index].marker.color = new_color                                           
        fig.write_html("figures/plotting_plotly_density_custom_color_2.html")

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

.. tab:: Matplolib

    .. ipython:: python
        :suppress:

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

    **Custom colors for 1D**

    .. ipython:: python
        :okwarning:

        @savefig plotting_matplotlib_density_custom_color_1.png
        data["score1"].density(color = ["red"])

    **Custom colors mapping for categories**

    .. ipython:: python
        :okwarning:

        @savefig plotting_matplotlib_density_custom_color_2.png
        data.density(columns = ["score1", "score2", "score3"], color = ["red", "orange", "green"])

____

Size
~~~~

.. tab:: Plotly

    .. ipython:: python
        :suppress:

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

    Custom Width and Height.

    .. code-block:: python
        
        data.density(columns = ["score1", "score2", "score3"], width = 300, height = 300)

    .. ipython:: python
        :suppress:

        fig = data.density(columns = ["score1", "score2", "score3"], width = 300, height = 300)
        fig.write_html("figures/plotting_plotly_density_custom_size.html")

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

.. tab:: Matplolib

    .. ipython:: python
        :suppress:

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

    Custom Width and Height.

    .. ipython:: python
        :okwarning:

        @savefig plotting_matplotlib_density_1D_custom_size.png
        data["score1"].density(width = 6, height = 3)

____________


Text
~~~~

.. tab:: Plotly

    .. ipython:: python
        :suppress:

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

    **Custom Title**

    .. code-block:: python
        
        data["score1"].density(title_text = "Custom Title")

    .. ipython:: python
        :suppress:

        fig = data["score1"].density(title_text = "Custom Title", width = 600)
        fig.write_html("figures/plotting_plotly_density_custom_main_title.html")

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

    **Custom Legend Title Text**

    .. code-block:: python
        
        data.density(columns = ["score1", "score2", "score3"], legend_title_text = "Custom Legend")

    .. ipython:: python
        :suppress:

        fig = data.density(columns = ["score1", "score2", "score3"], legend_title_text = "Custom Legend", width = 600)
        fig.write_html("figures/plotting_plotly_density_custom_title.html")

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

    **Custom Axis Titles**

    .. code-block:: python
        
        data.density(columns = ["score1", "score2", "score3"], yaxis_title = "Custom Y-Axis Title")

    .. ipython:: python
        :suppress:

        fig = data.density(columns = ["score1", "score2", "score3"], yaxis_title = "Custom Y-Axis Title", width = 600)
        fig.write_html("figures/plotting_plotly_density_custom_y_title.html")

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

.. tab:: Matplolib

    .. ipython:: python
        :suppress:

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

    **Custom Title Text**

    .. ipython:: python
        :okwarning:

        @savefig plotting_matplotlib_density_custom_title_label.png
        data["score1"].density().set_title("Custom Title")

    **Custom Axis Titles**

    .. ipython:: python
        :okwarning:

        @savefig plotting_matplotlib_density_custom_yaxis_label.png
        data["score1"].density().set_ylabel("Custom Y Axis")

.. ipython:: python
   :suppress:

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