tesorotools-python 0.0.21__tar.gz → 0.0.22__tar.gz

{tesorotools_python-0.0.21 → tesorotools_python-0.0.22}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tesorotools-python
-Version: 0.0.21
+Version: 0.0.22
 Requires-Python: >=3.13
 Requires-Dist: babel
 Requires-Dist: eikon

{tesorotools_python-0.0.21 → tesorotools_python-0.0.22}/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "tesorotools-python"
 requires-python = ">=3.13"
-version = "0.0.21"
+version = "0.0.22"
 dependencies = [
     "psycopg2",
     "SQLAlchemy",

tesorotools_python-0.0.22/tesorotools/artists/__init__.py

@@ -0,0 +1,9 @@
+import matplotlib.style
+
+from tesorotools.artists.barh_plot import HorizontalBarChart
+from tesorotools.utils.config import TemplateLoader
+
+from ..utils.globals import STYLE_SHEET
+
+matplotlib.style.use(STYLE_SHEET)
+TemplateLoader.add_constructor("!barh", HorizontalBarChart.from_yaml)

tesorotools_python-0.0.22/tesorotools/artists/barh.md

@@ -0,0 +1,109 @@
+# Especificación de gráficos de barras horizontales
+
+En un archivo `.yaml` los gráficos de barras horizontales se especifican con el constructor `!barh`.
+
+## Series y bloques de series
+
+Pueden especificarse, o bien *series*, con la entrada `series` o bien *bloques de series* con la entrada `blocks`, pero no ambas a la vez.
+
+- Cada serie en la entrada `series` representará una barra en el gráfico final.
+- Los *bloques de series* utilizan para controlar los colores de las barras. Las series dentro de un mismo bloque tendrán el mismo color en el gráfico final.
+
+```yaml
+test_plot1: !barh
+  blocks:
+    block1:
+      label: name_to_be_displayed_1
+      series:
+        series_name_1: series_name_to_be_displayed_1
+        series_name_2: series_name_to_be_displayed_2*
+    block2:
+      label: name_to_be_displayed_2
+      series:
+        series_name_3: series_name_to_be_displayed_3
+        series_name_4: series_name_to_be_displayed_4
+
+test_plot2: !barh
+  series:
+    series_name_5: series_name_to_be_displayed_5
+    series_name_6: series_name_to_be_displayed_6
+```
+
+### Cómo destacar una serie
+Si añadimos un `*` al nombre de una serie, esta será marcada como destacada en el gráfico. Concretamente, se le añadirá cierta transparencia.
+
+## Qué muestra un gráfico de barras horizontales
+
+Un gráfico de barras horizontales puede mostrar hasta dos conjuntos de valores asociados de forma simultánea.
+
+- Si $(x_1,...,x_n)$ es un conjunto de valores, un gráfico de barras horizontales presenta estos valores de forma que cada uno de ellos queda asociado a una barra de longitud proporcional a su valor.
+  - Este conjunto de valores está representado por una *serie* de *pandas* y suele recibir, internamente, el nombre de `value_series`.
+- Opcionalmente, podemos querer acompañar cada valor (o solo algunos) $x_i$ con otro valor auxiliar $y_i$ para añadir contexto.
+  - Estos valores auxiliares $y_i$ se monstrarán con el formato que decidamos, entre paréntesis, al lado del nombre asociado al valor $x_i$, en el eje de ordenadas.
+  - Este conjunto de valores está respresentado por una *serie* de *pandas* y suele recibir, internamente, el nombre de `axis_series`.
+
+### Formato del eje *x*
+Para especificar el número de decimales, la escala y las unidades que queremos que se muestren para los valores presentados en forma de barras (nótese que esta configración afectará al aspecto del eje *x*) podemos usar la entrada `format`.
+
+```yaml
+nombre_del_grafico: !barh
+    # other stuff
+    format:
+        decimals: 0
+        units: "%"
+        scale: 100
+
+```
+
+### Formato de los valores representados en el eje *y*
+Para especificar el número de decimales, la escala y las unidades que queremos que se muestren para los valores auxiliares presentados numéricamente en el eje *y*, podemos usar la entrada `axis_format`.
+
+```yaml
+nombre_del_grafico: !barh
+    # other stuff
+    axis_format:
+        decimals: 2
+        units: €
+        scale: 1
+```
+
+### Formato de las anotaciones sobre las barras
+En ocasiones es dificil ver el valor exacto asociado a cada barra, sobre todo cuando no hay muchas marcas en el eje $x$, la rejilla es demasiado clara, o la barra queda muy lejos del eje.
+
+Para solventar este problema, podemos, opcionalmente, añadir una anotación al lado de cada una de las barras que indique numéricamente, y con el formato que queramos, el valor asociado a cada una de ellas. Para ello, podemos usar la entrada `annot_format`.
+
+```yaml
+nombre_del_grafico: !barh
+    # other stuff
+    annot_format:
+        decimals: 2
+        units: €
+        scale: 1
+```
+
+## Ordenar las barras por longitud
+
+Usualmente querremos que las barras del gráfico se muestren ordenadas, para ellos podemos usar la entrada `sorted`, que se tomará como `True` por defecto.
+
+- *TO DO*: Quizá aquí sería interesante añadir una entrada `ascending` que indique cómo ordenar las barras en caso de que la entrada `sorted` esté a `True`, y que será ignorada en caso de que `sorted` esté a `False`.
+
+```yaml
+nombre_del_grafico: !barh
+    # other stuff
+    sorted: True # default
+
+```
+
+## Gráficos de series a partir de *dataframes* con formato *flash*
+
+### Entrada *flash*
+
+```yaml
+nombre_del_gráfico: !barh
+    # other stuff
+    flash:
+        date: # if None takes last date
+        deviations: True
+        offset: ftd # friday to date
+        difference: relative # relative/absolute difference
+```

{tesorotools_python-0.0.21 → tesorotools_python-0.0.22}/tesorotools/artists/barh_plot.py

@@ -1,15 +1,19 @@
+# Añadir anotaciones de tipos, el objetivo sería eliminar todos los diccionarios con anotaciones del tipo dict[str, Any] que dicen más bien poco
+# Tener cuidado para que nada de lo que está hecho con esta librería deje de funcionar
+
 from enum import Enum
 from pathlib import Path
-from typing import Any
+from typing import Any, Self
 
 import matplotlib.pyplot as plt
 import pandas as pd
 from matplotlib.container import BarContainer
 from matplotlib.ticker import FuncFormatter
+from yaml import MappingNode
 
 from tesorotools.offsets.offsets import Difference, FloatingOffset, Stat
 from tesorotools.offsets.outliers import flag_outliers
-from tesorotools.utils.globals import DEBUG
+from tesorotools.utils.config import TemplateLoader
 from tesorotools.utils.matplotlib import (
     PLOT_CONFIG,
     format_annotation,
@@ -24,6 +28,8 @@ load_fonts()
 
 
 class Column(Enum):
+    """Enumerado usado para dar nombres normalizados a las series que se utilizan internamente en este módulo."""
+
     VALUE = "value"
     AXIS = "axis"
     DEVIATION = "deviation"
@@ -39,6 +45,16 @@ def _style_spines(
     color: str,
     linewidth: str,
 ):
+    """Estiliza los ejes acorde con la configuración
+
+    Parameters
+    ----------
+    ax : plt.Axes
+    decimals : int
+    units : str
+    color : str
+    linewidth : str
+    """
     ax.grid(visible=True, axis="x")
     for spine in ax.spines.values():
         spine.set_color(color)
@@ -69,6 +85,25 @@ def _style_baseline(ax: plt.Axes, **baseline_config):
 def _collect_series(
     blocks: dict[str, Any] | None, series: dict[str, str] | None
 ) -> dict[str, str]:
+    """Devuelve la unión de los diccionarios de series contenidos en los bloques. Si el gráfico no contiene bloques de series, simplemente devuelve su diccionario de series. Si contiene series y bloques (cosa que no debería ocurrir), simplemente ignora los bloques de series y devuelve las series.
+
+    Parameters
+    ----------
+    blocks : dict[str, Any] | None
+        Diccionario de bloques del gráfico
+    series : dict[str, str] | None
+        Diccionario de series del gráfico
+
+    Returns
+    -------
+    dict[str, str]
+        Diccionario de series unificado
+
+    Raises
+    ------
+    ValueError
+        Si en el gráfico no se especifican ni series ni bloques de series, se lanza una excepción.
+    """
     if series is None and blocks is None:
         raise ValueError("blocks and series cannot be both missing")
     if series is None and blocks is not None:
@@ -78,6 +113,18 @@ def _collect_series(
 
 
 def _collect_block_series(blocks: dict[str, Any]) -> dict[str, str]:
+    """Devuelve la unión de los diccionarios de series contenidos en los bloques
+
+    Parameters
+    ----------
+    blocks : dict[str, Any]
+        Diccionario de bloques del gráfico
+
+    Returns
+    -------
+    dict[str, str]
+        Diccionario de series unificado
+    """
     series = {}
     for _, block_cfg in blocks.items():
         series = series | block_cfg["series"]
@@ -87,6 +134,24 @@ def _collect_block_series(blocks: dict[str, Any]) -> dict[str, str]:
 def _infer_colors(
     value_series: pd.Series, blocks: dict[str, Any] | None
 ) -> pd.Series:
+    """Si en el gráfico no se especifican bloques de series, se asignará el primer color del tema a los valores positivos y el segundo a los colores negativos.
+
+    Si, por el contrario, se especifican bloques de series, se asignará un color a cada bloque, con independencia del signo de los valores.
+
+    Parameters
+    ----------
+    value_series : pd.Series
+        Serie a representar en forma de barras
+    blocks : dict[str, Any] | None
+        Especificación de los bloques de series del gráfico, o None, en caso de no existir.
+
+    Returns
+    -------
+    pd.Series
+        Serie de strings del mismo tamaño de la serie a representar, representando cada string un color del tema "C0", "C1", etc
+    """
+
+    # create a series with the same index as the value series and a normalized name
     color_series: pd.Series = pd.Series(
         index=value_series.index, name=Column.COLOR.value, dtype=str
     )
@@ -103,6 +168,21 @@ def _infer_colors(
 def _highlight_series(
     alias: dict[str, str], value_series: pd.Series
 ) -> pd.Series:
+    """Asignación de la transparencia de cada una de las barras a representar. Si los nombres de las series no contienen un `*` final se le asigna una opacidad de 1, en caso contrario, se asigna una opacidad específica definida en la variable `BARH_CONFIG["highlight_factor"]`
+
+    Parameters
+    ----------
+    alias : dict[str, str]
+        Diccionario de renombrado de la serie
+    value_series : pd.Series
+        Serie de valores a representar como barras
+
+    Returns
+    -------
+    pd.Series
+        Serie con el mismo tamaño que la serie de valores a representar. Contiene las transparencias asociadas a las barras de cada uno de los valores.
+    """
+    # create a series with the same index as the value series and a normalized name
     alpha_series: pd.Series = pd.Series(
         index=value_series.index, name=Column.ALPHA.value
     )
@@ -118,15 +198,38 @@ def _format_yaxis(
     value_series: pd.Series,
     axis_series: pd.Series | None,
 ) -> pd.Series:
-    # format y axis ticker labels
+    """Formatea el conjunto de valores auxiliares a ser representado, entre paréntesis, en el eje y.
+
+    Parameters
+    ----------
+    alias : dict[str, str]
+        Diccionario de renombrado del índice de la serie de valores
+    axis_format : dict[str, Any]
+        Especificación del formateo a ser aplicado
+    value_series : pd.Series
+        Serie de valores a ser representados como barras (realmente no estoy muy seguro de que la necesitemos)
+    axis_series : pd.Series | None
+        Serie de valores a ser representados numéricamente en el eje y
+
+    Returns
+    -------
+    pd.Series
+        Serie de valores a ser representados como barras, con el índice renombrado de tal forma que incluya en sí mismo los valores a ser representados numéricamente en el eje y
+    """
+
+    # remove the `*` from the series display names (this behabiour may change in the future sin may be interesting to be able to display names with the `*` character)
     renamer = {_: label.replace("*", "") for _, label in alias.items()}
     value_series = value_series.rename(renamer)
     if axis_format is not None:
         decimals: int = axis_format["decimals"]
         units: str = axis_format["units"]
+
+        # rename the index and format the values as specified as strings
         axis_series: pd.Series = axis_series.rename(renamer).apply(
             lambda x: format_annotation(x, decimals, units)
         )
+
+        # add the formatted value next to the series name, parenthesized
         value_series = value_series.rename(
             lambda x: f"{x} ({axis_series.loc[x]})"
         )
@@ -141,14 +244,30 @@ def _annotate(
     decimals: int,
     units: str,
 ):
-    # annotate
+    """Añade las etiquetas a las barras
+
+    Parameters
+    ----------
+    fig : plt.Figure
+        Fugura de matplotlib
+    ax : plt.Axes
+        Axes asociado a la figura de matplotlib
+    bar_container : BarContainer
+        Contenedor de barras
+    decimals : int
+        Decimales a mostrar en las anotaciones
+    units : str
+        Unidades a mostrar en las anotaciones
+    """
+
+    # annotate (just use the default matplotlib capabilities)
     labels = ax.bar_label(
         container=bar_container,
         fmt=lambda x: format_annotation(x, decimals, units),
         padding=BARH_CONFIG["padding"],
     )
 
-    # rescale
+    # rescale (kind of hacky, explanation pending)
     fig.canvas.draw_idle()
     for label in labels:
         bbox = label.get_window_extent()
@@ -176,18 +295,21 @@ def _plot_barh_chart(
     # format y axis ticker labels
     axis_series = standard_dict[Column.AXIS]
     value_series = _format_yaxis(alias, axis_format, value_series, axis_series)
+
+    # change the index of the other auxiliary series accordingly
     color_series.index = value_series.index
     alpha_series.index = value_series.index
 
+    # pack all the necessary data in a single dataframe for convenience
     data: pd.DataFrame = pd.concat(
         [value_series, color_series, alpha_series], axis=1
     )
 
-    # sort if required
+    # sort if required (here should be added the ascending/descending feature)
     if sorted:
         data = data.sort_values(by=Column.VALUE.value)
 
-    # plot
+    ### actually plot code
     fig = plt.figure(**FIG_CONFIG)
     ax = fig.add_subplot()
 
@@ -308,3 +430,43 @@ def plot_barh_charts_from_flash(
         )
         out_file = out_path / f"{name}.png"
         _plot_barh_chart(out_file, standard_dict, alias, **config)
+
+
+# estaría bien crear un tipo específico para las entradas en el yaml de tipo formato
+
+
+class HorizontalBarChart:
+
+    def __init__(self, alias: dict[str, str], **kwargs):
+        # el producto de esto deben ser dos series indexadas con el mismo índice
+        self._alias = alias
+
+    @classmethod
+    def from_yaml(cls, loader: TemplateLoader, node: MappingNode) -> Self:
+        plot_cfg: dict[str, Any] = loader.construct_mapping(node, deep=True)
+        plot_name: str = plot_cfg.pop("id")
+        blocks: dict[str, Any] | None = plot_cfg.get("blocks", None)
+        series: dict[str, str] | None = plot_cfg.get("series", None)
+        axis_format: dict[str, Any] | None = plot_cfg.get("axis_format", None)
+
+        # maybe here it's not the place to get the aliases, maybe the constructor is a better place
+        alias: dict[str, str] = _collect_series(blocks, series)
+
+        return cls(
+            alias,
+            **plot_cfg,
+        )
+
+    # this may be an "instance" of a protocol, just check what we did in the render package
+    def render(self, out: Path | None = None):
+        """Export the plot as an image to the path specified in the argument, or, if missing, to the path specified in the template
+
+        Parameters
+        ----------
+        out : Path | None, optional
+            Path in which the image will be saved, by default None. If None, the image will be saved in the previously specified path in the yaml template.
+        """
+        pass
+
+    def __repr__(self):
+        return str(self._alias)

{tesorotools_python-0.0.21 → tesorotools_python-0.0.22}/tesorotools/render/content/table.py

@@ -115,7 +115,7 @@ def _style_index_names(cell: TableCell):
 
 
 def _fill_index_names(
-    index: pd.Index | pd.MultiIndex, table_docx: TableDocx, horizontal: bool
+    index: pd.Index | pd.MultiIndex, table_docx: TableDocx, horizontal: bool, index_name: bool
 ):
     start_row: int = 2 if horizontal else 1
 
@@ -125,6 +125,11 @@ def _fill_index_names(
         else index.get_level_values(level=1)
     )
 
+    if index_name:
+        cell: TableCell = table_docx.cell(start_row-1, 0)
+        cell.text = index.name
+
+
     for idx, name in enumerate(index_names, start=start_row):
         cell: TableCell = table_docx.cell(idx, 0)
         cell.text = name
@@ -232,7 +237,7 @@ def render_table(
     _style_table(table_docx)
     _fill_column_names(table, table_docx, horizontal)
     _fill_index_names(
-        index=table.index, table_docx=table_docx, horizontal=horizontal
+        index=table.index, table_docx=table_docx, horizontal=horizontal, **kwargs
     )
     if block_sep:
         _separate_blocks(table.index, table_docx)
@@ -252,6 +257,7 @@ class Table:
         block_sep: bool = False,
         title: str | None = None,
         columns: list[str] | None = None,
+        index_name: bool = False
     ):
         if (
             (data_file is None)
@@ -276,6 +282,7 @@ class Table:
 
         self._title: str | None = title
         self._block_sep: bool = block_sep
+        self._index_name: bool = index_name
 
     @classmethod
     def from_yaml(cls, loader: TemplateLoader, node: MappingNode) -> Self:
@@ -303,7 +310,9 @@ class Table:
     def render(self, document: Document) -> Document:
         heading = document.add_heading(self._title, level=2)
         heading.alignment = CENTER
-        heading.runs[0].font.size = Pt(10)
+        
+        if len(heading.runs) > 0:
+            heading.runs[0].font.size = Pt(10)
 
         render_table(
             self._data,
@@ -311,5 +320,6 @@ class Table:
             self._shade,
             document,
             block_sep=self._block_sep,
+            index_name=self._index_name
         )
         return document

tesorotools_python-0.0.21/tesorotools/artists/__init__.py

@@ -1,5 +0,0 @@
-import matplotlib.style
-
-from ..utils.globals import STYLE_SHEET
-
-matplotlib.style.use(STYLE_SHEET)