Source code for vivainsights.export

# --------------------------------------------------------------------------------------------
# Copyright (c) Microsoft Corporation. All rights reserved.
# Licensed under the MIT License. See LICENSE.txt in the project root for license information.
# --------------------------------------------------------------------------------------------
"""
This module provides functions for displaying and exporting data frames and plot objects.

Functions:
- display_plot: Universal function to display plots regardless of type (matplotlib.Figure or seaborn.FacetGrid)
- export: Exports data frames or plot objects using the specified method/format

By default, export() copies a data frame to the clipboard, and matplotlib objects are saved as PNG files.
"""

import pandas as pd
import matplotlib.pyplot as plt
from datetime import datetime
import seaborn as sns

[docs] def display_plot(plot_obj): """ Universal function to display plots regardless of type. Handles both matplotlib.figure.Figure objects (from create_bar, create_trend, etc.) and seaborn.axisgrid.FacetGrid objects (from create_line with >4 groups). Parameters ---------- plot_obj : matplotlib.figure.Figure or seaborn.axisgrid.FacetGrid The plot object to display Returns ------- None Displays the plot using the appropriate method Example ------- >>> import vivainsights as vi >>> plot = vi.create_line(data=vi.load_pq_data(), metric='Email_hours', hrvar='Organization') >>> vi.display_plot(plot) """ if hasattr(plot_obj, 'show'): # For matplotlib Figure objects plot_obj.show() elif isinstance(plot_obj, sns.axisgrid.FacetGrid) or hasattr(plot_obj, 'figure'): # For seaborn FacetGrid objects - use matplotlib's show plt.show() else: # Fallback - just use plt.show() print(f"Unknown plot type: {type(plot_obj)}, using plt.show() as fallback") plt.show()
[docs] def export(x, file_format='auto', path='insights export', dpi=300, timestamp=True): """ Name ---- Description ----------- Exports the data to the specified file format and saves it to the specified filename. A general use function to export 'vivainsights' outputs to CSV, clipboard, or save as images. By default, `export()` copies a data frame to the clipboard and displays plot objects. Parameters --------- x : dataframe or matplotlib figure object The object to export, which can be a data frame or a matplotlib figure object. file_format : str, optional Character string specifying the method of export. Defaults to 'auto' which: - For DataFrames: copies to clipboard - For plot objects: displays the plot Other options: 'csv', 'png', 'svg', 'jpeg', 'pdf', 'clipboard', 'display' path : str or optional If exporting a file, enter the path and the desired file name. Defaults to "insights export". dpi : int or optional Integer specifying the dots per inch for the image. Defaults to 300. timestamp : bool or optional Logical vector specifying whether to include a timestamp in the file name. Defaults to True. Returns ------- A different output is returned depending on the value passed to the `file_format` Argument: - `"auto"`: DataFrame -> clipboard, plot objects -> display - `"clipboard"`: data frame is saved to clipboard. - `"csv"`: CSV file containing data frame is saved to specified path. - `"png"`: PNG file containing plot object is saved to specified path. - `"svg"`: SVG file containing plot object is saved to specified path. - `"jpeg"`: JPEG file containing plot object is saved to specified path. - `"pdf"`: PDF file containing plot object is saved to specified path. - `"display"`: plot object is displayed using display_plot() Example ------- >>> import vivainsights as vi >>> # Auto behavior - plot will be displayed >>> km_plot = vi.keymetrics_scan(data = vi.load_pq_data(), hrvar='Organization', return_type = "plot") >>> vi.export(km_plot) # Displays the plot >>> >>> # Auto behavior - DataFrame will be copied to clipboard >>> data = vi.load_pq_data() >>> vi.export(data) # Copies to clipboard >>> >>> # Explicit file export >>> vi.export(km_plot, file_format = 'png', path = 'keymetrics_scan', timestamp = False) """ # Determine object type for auto behavior is_plot = (isinstance(x, plt.Figure) or isinstance(x, sns.axisgrid.FacetGrid) or hasattr(x, 'savefig')) is_dataframe = isinstance(x, pd.DataFrame) # Handle auto file format if file_format == "auto": if is_plot: file_format = "display" elif is_dataframe: file_format = "clipboard" else: raise ValueError(f"Unknown object type: {type(x)}. Cannot determine auto behavior.") # Create timestamped path (if applicable) if timestamp == True: newpath = f"{path} {datetime.now().strftime('%Y-%m-%d %H-%M-%S')}" else: newpath = path # Export option: CSV if file_format == "csv": if not is_dataframe: raise ValueError("CSV export is only supported for DataFrames.") newpath = f"{newpath}.csv" print(f"Exporting to {newpath}...") x.to_csv(newpath, index=False) # Export option: png,svg,jpeg,pdf elif file_format in ["png", "svg", "jpeg", "pdf"]: if not is_plot: raise ValueError(f"{file_format.upper()} export is only supported for plot objects.") newpath = f"{newpath}.{ file_format}" print(f"Exporting to {newpath}...") x.savefig( # matplotlib.savefig newpath, dpi = dpi, # Set dots per inch bbox_inches="tight", # Remove extra whitespace around plot facecolor='white' # Set background color to white ) # clipboard export elif file_format == "clipboard": if not is_dataframe: raise ValueError("Clipboard export is only supported for DataFrames.") x.to_clipboard() print("Data frame copied to clipboard.\nYou may paste the contents directly to Excel.") # display plot elif file_format == "display": if not is_plot: raise ValueError("Display is only supported for plot objects.") display_plot(x) else: raise ValueError(f"Invalid file_format: {file_format}. Supported formats: 'auto', 'csv', 'png', 'svg', 'jpeg', 'pdf', 'clipboard', 'display'") return()