piel.visual =========== .. py:module:: piel.visual Submodules ---------- .. toctree:: :maxdepth: 1 /autoapi/piel/visual/data_conversion/index /autoapi/piel/visual/experimental/index /autoapi/piel/visual/json_to_markdown/index /autoapi/piel/visual/plot/index /autoapi/piel/visual/signals/index /autoapi/piel/visual/style/index /autoapi/piel/visual/table/index /autoapi/piel/visual/types/index Attributes ---------- .. autoapisummary:: piel.visual.primary_cycler piel.visual.secondary_cycler piel.visual.primary_color_palette piel.visual.secondary_color_palette piel.visual.MultiTimeSignalData piel.visual.AxesPlottingTypes piel.visual.ExtensiblePlotsDirectionPerElement piel.visual.measurement_data_to_plot_map piel.visual.measurement_data_collection_to_plot_map piel.visual.measurement_data_collection_to_plot_suffix_map Functions --------- .. autoapisummary:: piel.visual.save piel.visual.plot_simple piel.visual.plot_simple_multi_row piel.visual.plot_simple_multi_row_list piel.visual.create_axes_per_figure piel.visual.create_plot_containers piel.visual.list_to_overlayed_plots piel.visual.list_to_separate_plots piel.visual.create_axes_parameters_table_overlay piel.visual.create_axes_parameters_tables_separate piel.visual.append_row_to_dict piel.visual.points_to_lines_fixed_transient piel.visual.activate_piel_styles piel.visual.plot_time_signals piel.visual.dictionary_to_markdown_str piel.visual.auto_function_name_list_from_module piel.visual.auto_function_list_from_module piel.visual.auto_plot_from_measurement_data_collection piel.visual.auto_plot_from_measurement_data piel.visual.auto_plot_from_experiment_data Package Contents ---------------- .. py:function:: save(fig, **kwargs) This function is a generic implementation of the savefig functionality in matplotlib, and is used as a wrapper on all :return: .. py:function:: plot_simple(x_data: numpy.ndarray, y_data: numpy.ndarray, label: Optional[str] = None, ylabel: str | piel.types.Unit | None = None, xlabel: str | piel.types.Unit | None = None, fig: Optional[Any] = None, axs: Optional[List[Any]] = None, title: Optional[str] = None, plot_args: list = None, plot_kwargs: dict = None, figure_kwargs: dict = None, legend_kwargs: dict = None, title_kwargs: dict = None, xlabel_kwargs: dict = None, ylabel_kwargs: dict = None, *args, **kwargs) -> tuple Plot a simple line graph. This function abstracts the basic plotting functionality while keeping the flexibility of the matplotlib library, allowing customization of labels, titles, and figure properties. :param x_data: Data for the X-axis. :type x_data: np.ndarray :param y_data: Data for the Y-axis. :type y_data: np.ndarray :param label: Label for the plot line, useful for legends. Defaults to None. :type label: Optional[str], optional :param ylabel: Label for the Y-axis, or a Unit object with a `label` and `base` attribute. Defaults to None. :type ylabel: str | Unit | None, optional :param xlabel: Label for the X-axis, or a Unit object with a `label` and `base` attribute. Defaults to None. :type xlabel: str | Unit | None, optional :param fig: Matplotlib Figure object to be used. Defaults to None. :type fig: Optional[Any], optional :param axs: List of Matplotlib Axes objects. Defaults to None. :type axs: Optional[List[Any]], optional :param title: Title of the plot. Defaults to None. :type title: Optional[str], optional :param plot_args: Positional arguments passed to plt.plot(). Defaults to None. :type plot_args: list, optional :param plot_kwargs: Keyword arguments passed to plt.plot(). Defaults to None. :type plot_kwargs: dict, optional :param figure_kwargs: Keyword arguments for figure creation. Defaults to None. :type figure_kwargs: dict, optional :param legend_kwargs: Keyword arguments for legend customization. Defaults to None. :type legend_kwargs: dict, optional :param title_kwargs: Keyword arguments for title customization. Defaults to None. :type title_kwargs: dict, optional :param xlabel_kwargs: Keyword arguments for X-axis label customization. If 'show' is set to False, the X-axis label will not be displayed. Defaults to None. :type xlabel_kwargs: dict, optional :param ylabel_kwargs: Keyword arguments for Y-axis label customization. If 'show' is set to False, the Y-axis label will not be displayed. Defaults to None. :type ylabel_kwargs: dict, optional :param \*args: Additional positional arguments for plt.plot(). :param \*\*kwargs: Additional keyword arguments for plt.plot(). :returns: The figure and axes of the plot. :rtype: Tuple[plt.Figure, plt.Axes] .. py:function:: plot_simple_multi_row(data: pandas.DataFrame, x_axis_column_name: str = 't', row_list: Optional[List[str]] = None, y_label: Optional[List[str]] = None, x_label: Optional[str] = None, titles: Optional[List[str]] = None, subplot_spacing: float = 0.15) -> Any Plot multiple rows of files on separate subplots, sharing the same x-axis. :param data: Data to plot. :type data: pd.DataFrame :param x_axis_column_name: Column name of the x-axis. Defaults to "t". :type x_axis_column_name: str, optional :param row_list: List of column names to plot. Defaults to None. :type row_list: Optional[List[str]], optional :param y_label: List of Y-axis titles for each subplot. Defaults to None. :type y_label: Optional[List[str]], optional :param x_label: Title of the x-axis. Defaults to None. :type x_label: Optional[str], optional :param titles: Titles for each subplot. Defaults to None. :type titles: Optional[List[str]], optional :param subplot_spacing: Spacing between subplots. Defaults to 0.3. :type subplot_spacing: float, optional :returns: The matplotlib figure containing the subplots. :rtype: plt.Figure .. py:function:: plot_simple_multi_row_list(data: list[tuple[numpy.ndarray, numpy.ndarray]], labels: Optional[List[Optional[str]]] = None, y_labels: Optional[List[Optional[str]]] = None, x_label: Optional[str] = None, titles: Optional[List[Optional[str]]] = None, fig: Optional[Any] = None, axs: Optional[List[Any]] = None, plot_args: Optional[List[List[Any]]] = None, plot_kwargs: Optional[List[dict[str, Any]]] = None, figure_kwargs: Optional[dict[str, Any]] = None, legend_kwargs: Optional[dict[str, Any]] = None, title_kwargs: Optional[dict[str, Any]] = None, subplot_spacing: float = 0.15, *args, **kwargs) -> tuple[Any, List[Any]] Plot multiple (x_data, y_data) pairs on separate subplots, similar to plot_simple. :param data: List of tuples containing x and y data. :type data: List[Tuple[np.ndarray, np.ndarray]] :param labels: List of labels for each plot. Defaults to None. :type labels: Optional[List[Optional[str]]], optional :param y_labels: List of Y-axis labels for each subplot. Defaults to None. :type y_labels: Optional[List[Optional[str]]], optional :param x_label: Common X-axis label for all subplots. Defaults to None. :type x_label: Optional[str], optional :param titles: List of titles for each subplot. Defaults to None. :type titles: Optional[List[Optional[str]]], optional :param fig: Matplotlib figure. If None, a new figure is created. Defaults to None. :type fig: Optional[plt.Figure], optional :param axs: List of Matplotlib axes. If None, new axes are created. Defaults to None. :type axs: Optional[List[plt.Axes]], optional :param plot_args: List of positional arguments for each plot. Defaults to None. :type plot_args: Optional[List[List[Any]]], optional :param plot_kwargs: List of keyword arguments for each plot. Defaults to None. :type plot_kwargs: Optional[List[dict[str, Any]]], optional :param figure_kwargs: Keyword arguments for figure creation. Defaults to None. :type figure_kwargs: Optional[dict[str, Any]]], optional :param legend_kwargs: Keyword arguments for legends. Defaults to None. :type legend_kwargs: Optional[dict[str, Any]]], optional :param title_kwargs: Keyword arguments for titles. Defaults to None. :type title_kwargs: Optional[dict[str, Any]]], optional :param subplot_spacing: Spacing between subplots. Defaults to 0.15. :type subplot_spacing: float, optional :param \*args: Additional positional arguments passed to plt.plot(). :param \*\*kwargs: Additional keyword arguments passed to plt.plot(). :returns: The figure and list of axes of the plot. :rtype: Tuple[plt.Figure, List[plt.Axes]] .. py:function:: create_axes_per_figure(rows: int = 1, columns: int = 1, **kwargs) -> tuple This function creates a figure and a set of axes in this figure according to the number of rows or columns defined. .. py:function:: create_plot_containers(container_list: list, axes_structure: piel.visual.types.AxesPlottingTypes = 'separate', **kwargs) -> tuple .. py:function:: list_to_overlayed_plots(container_list: list, **kwargs) -> tuple .. py:function:: list_to_separate_plots(container_list: list, axes_per_element: int = 1, multi_axes_extension_direction: piel.visual.types.ExtensiblePlotsDirectionPerElement = 'x', **kwargs) -> tuple This function creates a list of plots that are separate from each other. .. py:function:: create_axes_parameters_table_overlay(fig, axs: list, parameters_list: list, font_family='Roboto', header_font_weight='bold', cell_font_size=10, cell_font_weight='normal') This function takes in the parameter_list and a figure, axes list, to return a figure and axes with an attached parameter table and relevant colors and line styles. The figure must already have the axes plotted and ready to extract the relevant colors, line styles, and parameters from it accordingly. This function is particularly useful if the parametric sweep is overlaid in multiple lines of the same axes. .. py:function:: create_axes_parameters_tables_separate(fig, axs: list, parameter_tables_list: list, table_height=0.15, spacing=0.01) -> tuple Inserts tables between vertical subplots in an existing figure. Adjusts the subplot positions to create space for the tables. Parameters: - fig: The figure object containing the subplots. - axs: A list of axes objects corresponding to the subplots. - parameter_tables_list: A list containing the data to display in the tables. Each element can be a DataFrame, Series, or list of lists. - table_height: The height of the tables relative to the figure (default is 0.2). - spacing: Space between the subplots and the tables (default is 0.05). Returns: - fig: The updated figure object. - axs: The updated list of axes objects, including the tables. .. py:function:: append_row_to_dict(data: dict, copy_index: int, set_value: dict) Get all the rows of the dictionary. We want to copy and append a row at a particular index of the dictionary values. Operates on existing files :param data: Dictionary of files to be appended. :param copy_index: Index of the row to be copied. :param set_value: Dictionary of values to be set at the copied index. :returns: None .. py:function:: points_to_lines_fixed_transient(data: pandas.DataFrame, time_index_name: str, fixed_transient_time=1, return_dict: bool = False, ignore_rows: list = None) This function converts specific steady-state point files into steady-state lines with a defined transient time in order to plot digital-style files. For example, VCD files tends to be structured in this form: .. code-block:: text #2001 b1001 " b10010 # b1001 ! #4001 b1011 " b1011 # b0 ! #6001 b101 " This means that even when tokenizing the files, when visualising it in a wave plotter such as GTKWave, the signals get converted from token specific times to transient signals by a corresponding transient rise time. If we want to plot the files correspondingly in Python, it is necessary to add some form of transient signal translation. Note that this operates on a dataframe where the electrical time signals are clearly defined. It copies the corresponding steady-state files points whilst adding files points for the time-index accordingly. It starts by creating a copy of the initial dataframe as to not overwrite the existing files. We have an initial time files point that tends to start at time 0. This means we need to add a point just before the next steady state point transition. So what we want to do is copy the existing row and just change the time to be the `fixed_transient_time` before the next transition. Doesn't append on penultimate row. :param dataframe: Dataframe or dictionary of files to be converted. :param time_index_name: Name of the time index column. :param fixed_transient_time: Time of the transient signal. :param return_dict: Return a dictionary instead of a dataframe. :param ignore_rows: Rows to ignore when converting to steady-state lines. :returns: Dataframe or dictionary of files with steady-state lines. .. py:function:: activate_piel_styles() Activates the piel fast rc params. :returns: None .. py:data:: primary_cycler :value: None .. py:data:: secondary_cycler :value: None .. py:data:: primary_color_palette :value: ['#1982C4', '#B79174', '#6B4C93', '#C6B7DA', '#A17500', '#8C564B', '#32490E', '#6A5541',... .. py:data:: secondary_color_palette :value: ['#145B93', '#8D7059', '#50356A', '#978BAA', '#754F00', '#693E36', '#24360A', '#4D3D31',... .. py:data:: MultiTimeSignalData .. py:function:: plot_time_signals(multi_data_time_signal: piel.types.MultiTimeSignalData) TODO signals .. py:data:: AxesPlottingTypes .. py:data:: ExtensiblePlotsDirectionPerElement .. py:function:: dictionary_to_markdown_str(dictionary: piel.types.PathTypes) -> str .. py:data:: measurement_data_to_plot_map This mapping creates an automatic relationship between the data collection and the plotting required. .. py:data:: measurement_data_collection_to_plot_map .. py:data:: measurement_data_collection_to_plot_suffix_map .. py:function:: auto_function_name_list_from_module(module) -> list[str] .. py:function:: auto_function_list_from_module(module) -> list[callable] .. py:function:: auto_plot_from_measurement_data_collection(measurement_data_collection: piel.types.experimental.MeasurementDataCollectionTypes, plot_output_directory: piel.types.PathTypes = None, extra_plot_output_directories: list[piel.types.PathTypes] = None, measurement_data_collection_to_plot_map: dict = measurement_data_collection_to_plot_map, measurement_data_collection_to_plot_prefix_map: dict = measurement_data_collection_to_plot_suffix_map, **kwargs) -> tuple[list[tuple], list[piel.types.PathTypes]] This function will automatically plot the data from the `MeasurementDataCollection` provided. If there are more than one set of relevant plots for a given `MeasurementData`, it will generate a list of figures accordingly. .. py:function:: auto_plot_from_measurement_data(measurement_data: piel.types.experimental.MeasurementDataTypes, **kwargs) -> list[tuple, piel.types.PathTypes] This function will automatically plot the data from the `MeasurementData` object provided. If there are more than one set of relevant plots for a given `MeasurementData`, it will generate a list of figures accordingly. .. py:function:: auto_plot_from_experiment_data(experiment_data: piel.types.experimental.ExperimentData, plot_output_directory: piel.types.PathTypes = None, parametric: bool = False, **kwargs) -> tuple[list[tuple], list[piel.types.PathTypes]] This function will automatically plot the data from the `ExperimentData` object provided.