tdfs4ds.utils.visualization¶

tdfs4ds.utils.visualization ¶

analyze_sql_query ¶

analyze_sql_query(sql_query, df=None, target=None, root_name='ml__', node_info=None)

Analyzes a SQL query and its relationships to target tables/views.

This function takes a SQL query as input and extracts source tables/views mentioned in the query. It also allows for recursively analyzing TeradataML (tdml) views to identify relationships and dependencies between the source tables/views and target tables/views. The analysis results are accumulated in a TeradataML DataFrame (df) and a list of node information (node_info) to capture target, columns, and query details.

Parameters:

Name	Type	Description	Default
`sql_query`	`str`	The SQL query to be analyzed.	required
`df`	`DataFrame`	An existing TeradataML DataFrame to append the analysis results to. Default is None.	`None`
`target`	`str`	The target table/view where the query is directed. Default is None.	`None`
`root_name`	`str`	A root name identifier for filtering TeradataML views. Default is 'ml__'.	`'ml__'`
`node_info`	`list`	A list of dictionaries containing node information. Default is None.	`None`

Returns:

Name	Type	Description
`tuple`		A tuple containing the analysis results - a TeradataML DataFrame (df) containing source and target
		table/view relationships, and a list of node information (node_info) capturing details about each node
		in the analysis.

Note

The 'target' parameter should be specified when analyzing queries directed at a specific table/view.
When analyzing TeradataML views, the function recursively extracts and analyzes the view's definition.

Example

To analyze a SQL query:

result_df, result_node_info = analyze_sql_query(sql_query)

To analyze a SQL query with a specific target table/view:

result_df, result_node_info = analyze_sql_query(sql_query, target='my_target_table')

To analyze a SQL query and append results to an existing TeradataML DataFrame:

existing_df = teradataml.DataFrame() result_df, result_node_info = analyze_sql_query(sql_query, df=existing_df)

display_table ¶

display_table(df, max_widths=[25, 55, 10], header=['Feature Database', 'Feature Table', '# rows'])

Display a TeradataML DataFrame as a formatted table in the console.

This function formats each row of the TeradataML DataFrame according to specified maximum column widths. It prints out the DataFrame in a tabular format with a header.

Parameters:

Name	Type	Description	Default
`df`	`DataFrame`	The TeradataML DataFrame to be displayed.	required
`max_widths`	`list of int`	Maximum width of each column in characters. Defaults to [25, 55, 10].	`[25, 55, 10]`
`header`	`list of str`	Column headers to be displayed. Defaults to ["Feature Database", "Feature Table", "# rows"].	`['Feature Database', 'Feature Table', '# rows']`

Returns:

Name	Type	Description
`None`		This function only prints the table and does not return anything.

Example

To display a TeradataML DataFrame with custom column widths and headers:

display_table(my_teradataml_dataframe, max_widths=[30, 60, 12], header=["DB Name", "Table Name", "Row Count"])

Note

The 'max_widths' list specifies the maximum width of each column in characters.
The 'header' list defines the column headers to be displayed.
The function formats each row of the TeradataML DataFrame to fit within the specified column widths and prints the table.

plot_graph ¶

plot_graph(tddf, root_name='ml__')

Plot a Sankey diagram to visualize hierarchical data relationships based on a TeradataML DataFrame.

This function generates a Sankey diagram to represent hierarchical data relationships within a TeradataML DataFrame. It analyzes the SQL query of the DataFrame and extracts the relationships between source and target tables or views. The resulting Sankey diagram provides an intuitive visualization of these relationships.

Parameters:

Name	Type	Description	Default
`tddf`	`DataFrame`	The TeradataML DataFrame to analyze and visualize.	required
`root_name`	`str`	The root node name to filter the visualization. Defaults to 'ml__'.	`'ml__'`

Returns:

Type	Description
	pandas.DataFrame: A DataFrame containing information about the relationships between source and target tables or views.

Example

To visualize hierarchical data relationships within a TeradataML DataFrame:

plot_graph(my_teradataml_dataframe, root_name='root_node')

Note

The function analyzes the SQL query of the TeradataML DataFrame to identify source and target relationships.
The resulting Sankey diagram is displayed, providing a visual representation of the data hierarchy.
The returned DataFrame contains details about the relationships, including source and target names and column information.

visualize_graph ¶

visualize_graph(df, layout_choice='linear_depth_layout')

Visualize a directed graph based on a DataFrame containing source and target relationships.

This function generates an interactive visualization of a directed graph based on a DataFrame that represents source and target relationships. Users can choose from different layout options to customize the appearance of the graph.

Parameters:

Name	Type	Description	Default
`df`	`DataFrame`	A DataFrame containing source and target relationships.	required
`layout_choice`	`str`	The choice of layout for graph visualization. - 'linear_depth_layout': Linear depth layout - 'segmented_linear_layout': Segmented linear layout - 'radial_layout': Radial layout Defaults to 'linear_depth_layout'.	`'linear_depth_layout'`

Returns:

Name	Type	Description
`None`		This function generates an interactive graph visualization and displays it in the current environment.

Example

To visualize a directed graph based on a DataFrame:

visualize_graph(my_dataframe, layout_choice='segmented_linear_layout')

Note

The function uses the NetworkX library to create a directed graph from the DataFrame.
Users can choose different layout options to customize the graph's appearance.
The resulting graph is interactive and can be explored in the display environment.

linear_depth_layout ¶

linear_depth_layout(G, sources, leaves, multi_leaf_connections)

Compute positions for nodes in a linear depth layout of a directed graph.

This function calculates positions for nodes in a linear depth layout of a directed graph, where nodes at the same depth are aligned horizontally, and sources are on the left side while leaves are on the right side.

Parameters:

Name	Type	Description	Default
`G`	`DiGraph`	A directed graph.	required
`sources`	`set`	A set of source nodes.	required
`leaves`	`set`	A set of leaf nodes.	required
`multi_leaf_connections`	`set`	A set of nodes with multiple leaf connections.	required

Returns:

Name	Type	Description
`dict`		A dictionary of node positions, where keys are nodes and values are (x, y) positions.

Example

To compute positions for a linear depth layout:

positions = linear_depth_layout(my_graph, source_nodes, leaf_nodes, multi_leaf_nodes)

Note

This layout is suitable for visualizing directed graphs with a clear depth hierarchy.
Sources are aligned on the left side, leaves on the right side, and nodes in between are positioned based on their depth.
Nodes with multiple leaf connections are positioned at the same depth level.

segmented_linear_layout ¶

segmented_linear_layout(G, sources, leaves, multi_leaf_connections)

Compute positions for nodes in a segmented linear layout of a directed graph.

This function calculates positions for nodes in a segmented linear layout of a directed graph, where nodes are segmented into different groups based on their connectivity. Sources are on the left, regular nodes in the middle-left, nodes connected to more than one leaf in the middle-right, and leaves on the right side.

Parameters:

Name	Type	Description	Default
`G`	`DiGraph`	A directed graph.	required
`sources`	`set`	A set of source nodes.	required
`leaves`	`set`	A set of leaf nodes.	required
`multi_leaf_connections`	`set`	A set of nodes with multiple leaf connections.	required

Returns:

Name	Type	Description
`dict`		A dictionary of node positions, where keys are nodes and values are (x, y) positions.

Example

To compute positions for a segmented linear layout:

positions = segmented_linear_layout(my_graph, source_nodes, leaf_nodes, multi_leaf_nodes)

Note

This layout is suitable for visualizing directed graphs with different node connectivity patterns.
Sources are aligned on the left side, regular nodes in the middle-left, nodes connected to more than one leaf in the middle-right, and leaves on the right side.
Nodes within the same group are aligned horizontally.

radial_layout ¶

radial_layout(G, sources, leaves, multi_leaf_connections)

Compute positions for nodes in a radial layout of a directed graph.

This function calculates positions for nodes in a radial layout of a directed graph, where nodes are placed in concentric circles with sources at the center and leaves at the outermost circle. The layout ensures that nodes with similar depths are positioned at the same radial distance from the center.

Parameters:

Name	Type	Description	Default
`G`	`DiGraph`	A directed graph.	required
`sources`	`set`	A set of source nodes.	required
`leaves`	`set`	A set of leaf nodes.	required
`multi_leaf_connections`	`set`	A set of nodes with multiple leaf connections.	required

Returns:

Name	Type	Description
`dict`		A dictionary of node positions, where keys are nodes and values are (x, y) positions.

Example

To compute positions for a radial layout:

positions = radial_layout(my_graph, source_nodes, leaf_nodes, multi_leaf_nodes)

Note

This layout is suitable for visualizing directed graphs with a radial hierarchy.
Sources are positioned at the center, regular nodes in concentric circles based on their depth, and leaves at the outermost circle.
Nodes within the same circle have similar depths.

prepare_plotly_traces ¶

prepare_plotly_traces(G, pos, sources, leaves, multi_leaf_connections)

Prepare Plotly traces for edges and nodes in a directed graph visualization.

This function prepares Plotly traces for rendering edges and nodes in a directed graph visualization. It calculates the positions of edges and nodes based on a given layout and assigns colors and markers to different types of nodes. The resulting traces can be used to create interactive graph visualizations.

Parameters:

Name	Type	Description	Default
`G`	`DiGraph`	A directed graph.	required
`pos`	`dict`	A dictionary of node positions, where keys are nodes and values are (x, y) positions.	required
`sources`	`set`	A set of source nodes.	required
`leaves`	`set`	A set of leaf nodes.	required
`multi_leaf_connections`	`set`	A set of nodes with multiple leaf connections.	required

Returns:

Name	Type	Description
`tuple`		A tuple of two Plotly traces: edge_trace and node_trace.

Example

To prepare Plotly traces for edges and nodes:

edge_trace, node_trace = prepare_plotly_traces(my_graph, node_positions, source_nodes, leaf_nodes, multi_leaf_nodes)

Note

This function is used to create Plotly traces for visualizing directed graphs with custom node colors and markers.