src package

src.app module

application

src.app.add_graphs(data, footer, lang, value)

add_graphs returns the charts div in the dashboard page

Parameters:

• data – the cached data of the charts as returned by download_data

• footer – the footer div generated by download_data

• lang – the language selected in the dropdown

• value – anyvalue that controls the behaviour of the spinner

Returns:

html.Div with the charts loaded in the cache

src.app.create_chart_item(data: dict, chart_id: str, df_metadata: list, df: pandas.DataFrame, valuelist: list)

create_chart_item returns the HTML div for the info and table buttons

Parameters:

• data – dict: the settings of the chart as specified in the YAML

• chart_id – str: the unique chart ID which correspond to the row and the sequential number (int) of the chart as specified in the YAML

• df_metadata – list: the list of metadata associated with the chart

• df – pd.DataFrame: the DataFrame associated with the chart ID

Returns:

html.Div with the info and table buttons

src.app.create_download(chart_id)

Create the download section of the offcanvas

Parameters:

chart_id – reference chart

Returns:

dashboard component with download section

src.app.create_download_button(chart_id)

Create chart download button

Parameters:

chart_id – reference chart

Returns:

html element with the download button

src.app.create_filter_dropdown(df: pandas.DataFrame, concept: str, chart_id: str, valuelist)

update_filter_output updates the filter dropdown for the data

Args:

n_clicks: the clicks on the filter dropdown data: a pd.DataFrame with the data without any fikter applied

Returns:

data: a dictionary with the data filtered

src.app.create_info_button(chart_id)

Create chart info button

Parameters:

chart_id – reference chart

Returns:

html element with the info button

src.app.create_offcanvas(data, chart_id, df_metadata)

Create an off-canvas user interface component for displaying dataflow metadata

Parameters:

• data – the chart datastructure

• chart_id – reference chart

• df_metadata – metadata for the chart

Returns:

the offcanvas element shown on info button click

src.app.create_offcanvas_table(data, chart_id, df, valuelist)

Create the table offcanvas element of the dashboard. The structure depends on whether the data can be downloaded or not.

Parameters:

• data – the chart data structure

• chart_id – reference chart

• df – the chart data

• valuelist – values for filtering

Returns:

the offcanvas element shown when the table button is clicked

src.app.create_table(chart_id: str, df: pandas.DataFrame)

create_table returns the Dash DataTable to be displayed in the offcanvas and exported.

Parameters:

• chart_id – str: the unique chart ID which correspond to the row and the sequential number (int) of the chart as specified in the YAML

• df – pd.DataFrame: the pd.DataFrame associated with the chart ID

Returns:

Dash DataTable

src.app.create_table_button(chart_id)

Create chart table button

Parameters:

chart_id – reference chart

Returns:

html element with the table button

src.app.create_toast(data, header: str, href=False)

create_toast returns the dbc.Toast with the statistic metadata set in the YAML

Parameters:

• data – the corresponding value of the chart as specified in the YAML

• header – str: the corresponding key associated to each chart in the YAML file

• href – bool: whether the text shall be encoded as link

Returns:

dbc.Toast with the statistic metadata, Unit and source (DATA) set in the YAML

async src.app.download_charts(chart_per_rows)

Download chart data asyncronously

Parameters:

chart_per_rows – output of get_rows()

Returns:

chart data and metadata, split in row lists

src.app.download_data(settings, value)

download_data returns the cached data and the footer required to build the charts_div and footer_div

Parameters:

• settings – the settings of the chart as specified in the YAML

• value – any value that controls the behaviour of the spinner

Returns:

a dictionary with the cached data required to build the charts_div, the footer, the spinners 1 and 2

async src.app.download_single_chart(data_chart, row: int, pos: int)

Download data and metadata for a single chart

Parameters:

• data_chart – the settings of the single chart

• z – int: Row number

• y – int: Position in row

Returns:

dict with chart settings and data

async src.app.download_single_data_chart(chart_id, data, concept)

Download data for a single chart

Parameters:

• chart_id – the chart ID corresponding to row number and position in row

• data – the DATA link specified in the YAML file

• concept – the concept specified in the YAML file

Returns:

list of couroutines with downloaded data as pd.DataFrame

src.app.download_table(n_clicks, data)

download_table returns the export table in CSV.

Parameters:

• n_clicks – int: the number of times that the list-download chart-id has been clicked on

• data – the DataTable returned by create_table()

Returns:

triggers dcc.send_data_frame to download the table as CSV

src.app.draw_chart(df, chart)

Generate the chart element

Parameters:

• df – the pandas.DataFrame containing data

• chart – the chart settings loaded from the yaml file

Raises:

ValueError – in case x or y axis is not specified.

Returns:

the html element containing the graph

src.app.generate_footer(data, key: str)

Generate the footer from the YAML file

Parameters:

• data – a dictionary with settings from the YAML file

• key – str: the key (FOOTER) from settings from the YAML file

Returns:

a html.Span with the footer of the dashboard as specified in the YAML file

src.app.generate_title(data, key: str)

Generate the title from the YAML file

Parameters:

• data – a dictionary with settings from the YAML file

• key – str: the key (TITLE) from settings from the YAML file

Returns:

a html.Span with the title of the dashboard as specified in the YAML file

src.app.get_dash_id(i)

Apply snake case to the DashID from the YAML file settings

Parameters:

i – a dictionary with settings from the YAML file

Returns:

a string with the snaked cased DashId

src.app.get_dashboard_title(data)

Return the title to the dashboard and control the behaviour of the loading spinner

Parameters:

data – a dictionary with settings from the YAML file

Returns:

a html.Span with the title of the dashboard and an integer that controls the behaviour of the loading spinner

src.app.get_dataflow_metadata(data, meta)

Create metadata element and fall back on data title

Parameters:

• data – the chart data structure

• meta – the metadata

Returns:

html element with metadata or title

src.app.get_icon_kpi(kpi, code, chart)

Build the icon for KPI card

Parameters:

• kpi – The ChartGenerator kpi object

• code – the code of the element used as subtitle in the KPI card

• chart – The chart settings

Returns:

The html element containing the kpi icon

src.app.get_language(*args)

Get the language code as returned by the callback

Parameters:

*args –

the language code clicked in the dropdown

Returns:

string with the language code requested which is cached

src.app.get_rows(data: dict, max_charts_per_row: int = 3)

get_rows returns the distribution of the charts per row in the dashboard

Parameters:

• data – dict: the settings of the chart as specified in the YAML

• max_charts_per_row – int: the maximum charts per row (Default value = 3)

Returns:

list with the distribution of the charts per row

src.app.get_static_metatada(chart, chart_id, df_metadata, df, valuelist)

get_static_metatada returns the HTML div for the info and table buttons

Parameters:

• chart – the settings of the chart as specified in the YAML

• chart_id – the unique chart ID which correspond to the row and the sequential number (int) of the chart as specified in the YAML

• df_metadata – the list of metadata associated with the chart

• df – the pd.DataFrame associated with the chart ID

Returns:

html.Div with the dbc.CardBody containing the title, subtitle and the buttons (table and info)

src.app.get_text_kpi(kpi, code, chart)

Build the text for KPI card

Parameters:

• kpi – the ChartGenerator kpi object

• code – the code of the element used as subtitle in the KPI card

• chart – the chart settings

Returns:

the html element with the kpi text

src.app.get_title_footer(data)

Get a dictionary with entries with Row == 0 specified in the YAML file

Parameters:

data – a dictionary with settings from the YAML file

Returns:

a dictionary with the title and footer, or any other entry with Row == 0 in the YAML file

src.app.load_content(yaml_file)

Load a dictionary with the settings from the YAML file and a boolean on whether the settings are loaded

Parameters:

yaml_file – the relative path of the YAML file

Returns:

a dictionary with the settings and a boolean when the loading is completed

src.app.load_content_uploaded(uploaded_file, filename)

update_output returns a dictionary with the settings from the uploaded YAML file and a boolean on whether the settings are loaded :param uploaded_file: the path of the YAML file :returns: a dictionary with the settings and a boolean when the loading is completed

src.app.load_yaml(href: str)

Get the location of the YAML file whose dashID matches the string provided in the href of the URL

Parameters:

href – str: the dashID

Returns:

a string with the location of the requested YAML file

src.app.load_yamlfile(filename: str, folder: str = None) → dict

Load the settings from the YAML file

Parameters:

• filename – str: the YAML file

• folder – str, optional: the YAML file folder location

Returns:

a dictionary with loaded settings from the YAML file

src.app.open_metadata_offcanvas(click)

Open metadata offcanvas on click if closed

src.app.open_table_offcanvas(click)

Open table offcanvas on click

Parameters:

click – a boolean that controls the behabiour of the off-canvas

Returns:

the offcanvas element shown on button click

src.app.toggle_collapse(n: int, is_open: bool, is_loaded: bool)

Control the behaviour of the toggle menu of the settings

Parameters:

• n – int: the cumulative number of clicks since the start of the session

• is_open – bool: whether the toggle menu is open

• is_loaded – bool: whether the settings are loaded

Returns:

a boolean to control the behaviour of the toggle menu of the settings

src.app.toggle_modal(open_clicks: int, close_clicks: int, is_open: bool)

Control the behaviour of the modal (Info)

Parameters:

• open_clicks – int: the cumulative number of clicks to open the modal

• close_clicks – int: the cumulative number of clicks to close the modal

• is_open – bool: whether the modal is open

Returns:

a boolean that contol the behaviour of the modal (Info)

src.app.update_output(n_clicks, data, values)

create_filter_dropdown creates the filter dropdown for the data

Args:

df: pd.DataFrame containg the data concept: the legendConcept as specified in the YAML file chart_id: the chart ID valuelist: the valuelist containing the unique values of the legendConcept

Returns:

html.Div: a dcc.Dropdown and a dbc.Button containing the values to filter

src.draw module

Module providing graphing utilities

class src.draw.ChartGenerator

Bases: object

Initialize a ChartGenerator instance with an empty Plotly figure.

This constructor initializes a ChartGenerator instance with an empty Plotly figure, which can be used to create various types of charts.

bar_chart(df, xAxisConcept, yAxisConcept, color=None, group_by=None, aggregation=None)

Create a bar chart.

Parameters:

• df – pd.DataFrame: the input containing bar chart data.

• xAxisConcept – str: the concept for the x-axis data.

• yAxisConcept – str: the concept for the y-axis data.

• group_by – str, optional: the column to group by for grouped bar charts.

Returns:

self: the ChartGenerator instance.

calculate_kpi(df, yAxisConcept, xAxisConcept, legendConcept, decimals=2, aggregation=None, group_by=None)

Calculate Key Performance Indicators (KPIs) based on the provided DataFrame.

Parameters:

• df – pd.DataFrame: the DataFrame containing the data.

• xAxisConcept – str: the concept for the x-axis data.

• yAxisConcept – str: the concept for the y-axis data.

• legendConcept – str: the column name representing the legend

• group_by – str, optional: the column to group data by.

• decimals – int, optional: the number of decimals for rounding Y-axis (Default value = 2)

• aggregation – str, optional: the aggregation to apply to Y-axis data.

Returns:

dict: a dictionary containing legend values as keys

Raises:

ValueError – If any of the specified columns are not found, if ‘legendConcept’ is None, or if invalid aggregation options are provided.

pie_chart(df, xAxisConcept, yAxisConcept, group_by=None, LabelsYN=None, aggregation=None)

Create a pie chart.

Parameters:

• df – pd.DataFrame: the input DataFrame containing pie chart data.

• xAxisConcept – str: the concept for the x-axis data.

• yAxisConcept – str: the concept for the y-axis data.

• group_by – str, optional: the column to group by for multiple pie charts.

Returns:

self: the ChartGenerator instance.

time_series_chart(df, xAxisConcept, yAxisConcept, color=None, group_by=None)

Create a time series chart.

Parameters:

• df – DataFrame: the input DataFrame containing time series data.

• xAxisConcept – str: the concept for the x-axis data.

• yAxisConcept – str: the concept for the y-axis data.

• group_by – str, optional: the column to group by for multiline charts.

Returns:

self: the ChartGenerator instance.

src.draw.chart_style_decorator(func)

A decorator for applying chart styling and legend positioning to Plotly figures.

Parameters:

func – function: the original function that generates a Plotly figure.

Returns:

function: a wrapped function that modifies the figure’s style and legend positioning.

This decorator is used to enhance the appearance of Plotly figures generated by other functions. It allows you to specify the positioning of the legend and applies various style modifications to the figure.

Example:

@chart_style_decorator def generate_plot(data, legendLoc=”BOTTOM”):

# Create a Plotly figure based on the input data fig = create_figure(data) return fig

# Apply the decorator to the generate_plot function styled_fig = generate_plot(data, legendLoc=”BOTTOM”)

src.sdmx module

Module providing sdmx utilities

class src.sdmx.SDMXData(data)

Bases: object

A class to get the data from SDMX API in SDMX format

Parameters:

url_data – the API URL from which to pull the data

get_data(yAxisConcept: str = None) → pandas.DataFrame

Returns a Pandas DataFrame with the data requested and optionally set the yAxisConcept as float.

Parameters:

yAxisConcept – str, optional: the y-axis to convert to numeric.

Returns:

pd.DataFrame: the requested data.

async get_data_async(yAxisConcept: str) → pandas.DataFrame

Asynchronously returns a Pandas DataFrame with the data requested and optionally set the yAxisConcept as float.

Parameters:

yAxisConcept – str, optional: the y-axis to convert to numeric.

Returns:

pd.DataFrame: the requested data.

class src.sdmx.SDMXMetadata(components, concept: str = None)

Bases: object

A class to get the metadata from SDMX API in SDMX format

Parameters:

• component – any object compatible with the Component object

• concept – a string that denotes the concept to translate

dataflow_metadata()

Returns a dictionary with the name and description of the dataflow

datastructure_metadata()

Returns a dictionary with the id, dimensions, attributes and measures of the queried DSD

get_cl()

Returns a Tuple with the name (str), description (str) and model.itemScheme.Code

get_codelist_name(*args, **kwargs)

Returns a string with the Agency, ID and version of of the codelist or a model.itemScheme.Codelist if all descendants are included in the SDMX URL call

get_codelists()

Returns a model.itemScheme.Codelist

parse_message(component_type)

Parses the appropriate component and returns children artefacts.

Parameters:

component_type – a string that can only take the following values: Dataflows, Codelists, DataStructures, Concepts

Returns:

a dictionary with the children artefacts associated to a component type.

src.sdmx.get_cl_item_name(items, item)

get_cl_item_name returns a string with code name

Parameters:

• items – a dictionary with the codes of the codelist

• item – a string with the code name

Returns:

the code name

src.sdmx.get_components(url: str, descendants: bool = True)

Retrieve a dictionary with the SDMX data

Parameters:

• url – str: the API URL from which to pull the data

• descendants – bool: whether to include all descendants in the call to the API (Default = True)

Returns:

dict: a dictionary in JSON format with the data/metadata requested.

async src.sdmx.get_components_async(url: str, descendants: bool = True)

Asynchronously retrieve a dictionary with the SDMX data

Parameters:

• url – str: the API URL from which to pull the data

• descendants – bool: whether to include all descendants in the call to the API (Default = True)

Returns:

dict: a dictionary in JSON format with the data/metadata requested

src.sdmx.get_translation(content, locale: str = 'en')

get_translation returns a translated string, if any language other than is available. Only fr, es, de are currently supported but this list can be easily expanded. If no language is

detected, it defaults back to English

Parameters:

• content – a dictionary of dictionaries to translate

• locale – str: the language code (en, es, de, fr); defaults to “en”.

Returns:

the string translated if any language is available

src.sdmx.get_url_cl(url_dsd, cl_name)

get_url_cl returns a string with the URL of the codelist

Parameters:

• url_dsd – the API URL of the DSD

• cl_name – the Agency, ID and version of the codelist (eg ESTAT:CL_AREA(1.0))

Returns:

a string with the URL to query against the API

src.sdmx.retreive_codes_from_data(df, concept, cl_id)

Retrieves metadata codelists from data

src.sdmx.translate_df(df, concept, items_translated)

translate_df returns a translated Pandas DataFrame

Parameters:

• df – a Pandas DataFrame

• concept – a string with the column to translate

• items_translated – a dictionary with the codes translated

Returns:

pd.DataFrame: the translated DataFrame

src.utils module

Module providing generic utilities

src.utils.cleanhtml(raw_html)

Clean raw html

Parameters:

raw_html – str: the input to clean

Returns:

str: the cleaned text

src.utils.error_box(error: str, e: str = None)

error_box returns a html component with the error box

Args:

error (str): the error message e (str, optional): the KeyError. Defaults to None.

Returns:

_type_: a html component with the error box

src.utils.get_label(names: list, data: list)

get label returns the label for the value in a list of dictionaries

Args:

names (list): _description_ data (list): _description_

Returns:

list: a list with the matched pairs

src.utils.snake_case(string: str) → str

snake_case returns snake cased string

Parameters:

string – str: input to be snake cased

Returns:

the input string snake cased

src.utils.validate_yamlfile(file)

validate_yamlfile raises a SchemaError if the YAML is not valid

Args:

file (_type_): the YAML file

Raises:

se_ft: title or footer are not valid se: generic element is not valid

Module contents