Jupyter-Notebook

class DataFrameDisplay:
    """Class for displaying a dataframe in different ways."""

    def df_display(self, df: pd.DataFrame, mode: Optional[str] = None) -> Optional[Any]:
        """Call the DataframeDisplay class.

        !!! info "About `df_display`"

            This function is used to display a dataframe in two different ways.

            1. Regular display mode:
                1. Via `IPython.display` for regular sliced displaying of the dataframe
                   in the notebook.
                2. Via `IPython.display` as Markdown for regular displaying of the
                    complete dataframe in the notebook.
            2. Interactive display mode:
                1. Via `itables` for interactive displaying of the dataframe in the
                    notebook, which allows for sorting, filtering, and jumping. For
                    more information see [itables](https://github.com/mwouts/itables).
                2. Via `dtale` for interactive displaying of the dataframe in the
                    notebook, which allows advanced data analysis of the dataframe in
                    an external window. For more information see
                    [dtale](https://github.com/man-group/dtale).

        Args:
            df (pd.DataFrame): Dataframe to display.
            mode (str, Optional): Display mode. Defaults to None.

        Raises:
            ValueError: Raises ValueError if mode of displaying is not supported.

        Returns:
            Optional[Any]: Returns the dtale object for plotting in the Jupyter
                 notebook, if mode is `dtale`.
        """
        if mode == "regular":
            self.regular_display(df=df)
        elif mode == "markdown":
            self.markdown_display(df=df)
        elif mode == "interactive":
            self.interactive_display(df=df)
        elif mode == "dtale":
            return self.dtale_display(df=df)
        elif mode is not None:
            raise ValueError(
                f"Invalid mode: {mode}. "
                "Valid modes are: regular, interactive, dtale, markdown."
            )
        return None

    @staticmethod
    def regular_display(df: pd.DataFrame) -> None:
        """Display the dataframe in a regular way.

        Args:
            df (pd.DataFrame): Dataframe to display.
        """
        display(df)

    @staticmethod
    def interactive_display(df: pd.DataFrame) -> None:
        """Display the dataframe in an interactive way.

        Args:
            df (pd.DataFrame): Dataframe to display.
        """
        itables_show(df)

    @staticmethod
    def dtale_display(df: pd.DataFrame) -> Any:
        """Display the dataframe in a dtale way.

        Args:
            df (pd.DataFrame): Dataframe to display.

        Returns:
            Any: Returns the dtale object for plotting in the Jupyter notebook.
        """
        return dtale_show(df)

    @staticmethod
    def markdown_display(df: pd.DataFrame) -> None:
        """Display the dataframe in a markdown way.

        Args:
            df (pd.DataFrame): Dataframe to display.
        """
        display_markdown(df.to_markdown(), raw=True)

class DataFramePlot:
    """Class to plot a dataframe."""

    def plot_2dataframes(
        self,
        args_plot: PlotAPI,
        df_1: pd.DataFrame,
        df_2: Optional[pd.DataFrame] = None,
    ) -> None:
        """Plot two dataframes.

        !!! info "About the plot"

            The plot is a combination of two plots. The first plot can be the
            residual plot of a fit or the _modified_ data. The second plot can be the
            fit or the original data.

        !!! missing "`line_dash_map`"

            Currently, the `line_dash_map` is not working, and the dash is not
            plotted. This is likely due to the columns not being labeled in the
            dataframe.

        Args:
            args_plot (PlotAPI): PlotAPI object for the settings of the plot.
            df_1 (pd.DataFrame): First dataframe to plot, which will generate
                a fit plot with residual plot. The ratio is 70% to 20% with
                10% space in between.
            df_2 (Optional[pd.DataFrame], optional): Second optional dataframe to
                plot for comparison. In this case, the ratio between the first
                and second plot will be the same. Defaults to None.
        """
        if df_2 is None:
            fig = self._plot_single_dataframe(args_plot, df_1)
        else:
            fig = self._plot_two_dataframes(args_plot, df_1, df_2)

        fig.show(
            config={
                "toImageButtonOptions": {
                    "format": "png",
                    "filename": "plot_of_2_dataframes",
                    "scale": 4,
                }
            }
        )

    def _plot_single_dataframe(self, args_plot: PlotAPI, df: pd.DataFrame) -> Figure:
        """Plot a single dataframe with residuals."""
        fig = make_subplots(
            rows=2, cols=1, shared_xaxes=True, shared_yaxes=True, vertical_spacing=0.05
        )

        residual_fig = self._create_residual_plot(df, args_plot)
        fit_fig = self._create_fit_plot(df, args_plot)

        for trace in residual_fig["data"]:
            fig.add_trace(trace, row=1, col=1)
        for trace in fit_fig["data"]:
            fig.add_trace(trace, row=2, col=1)

        self._update_plot_layout(fig, args_plot, df_2_provided=False)
        return fig

    def _plot_two_dataframes(
        self, args_plot: PlotAPI, df_1: pd.DataFrame, df_2: pd.DataFrame
    ) -> Figure:
        """Plot two dataframes for comparison."""
        fig = make_subplots(
            rows=2, cols=1, shared_xaxes=True, shared_yaxes=True, vertical_spacing=0.05
        )

        fig1 = px.line(df_1, x=args_plot.x, y=args_plot.y)
        fig2 = px.line(df_2, x=args_plot.x, y=args_plot.y)

        for trace in fig1["data"]:
            fig.add_trace(trace, row=1, col=1)
        for trace in fig2["data"]:
            fig.add_trace(trace, row=2, col=1)

        self._update_plot_layout(fig, args_plot, df_2_provided=True)
        return fig

    def _create_residual_plot(self, df: pd.DataFrame, args_plot: PlotAPI) -> Figure:
        """Create the residual plot."""
        return px.line(
            df,
            x=ColumnNamesAPI().energy,
            y=ColumnNamesAPI().residual,
            color_discrete_sequence=[args_plot.color.residual],
        )

    def _create_fit_plot(self, df: pd.DataFrame, args_plot: PlotAPI) -> Figure:
        """Create the fit plot."""
        y_columns = df.columns.drop(
            [ColumnNamesAPI().energy, ColumnNamesAPI().residual]
        )
        color_map = {
            ColumnNamesAPI().intensity: args_plot.color.intensity,
            ColumnNamesAPI().fit: args_plot.color.fit,
            **{
                key: args_plot.color.components
                for key in y_columns.drop(
                    [ColumnNamesAPI().intensity, ColumnNamesAPI().fit]
                )
            },
        }
        line_dash_map = {
            ColumnNamesAPI().intensity: "solid",
            ColumnNamesAPI().fit: "longdash",
            **{
                key: "dash"
                for key in y_columns.drop(
                    [ColumnNamesAPI().intensity, ColumnNamesAPI().fit]
                )
            },
        }
        return px.line(
            df,
            x=ColumnNamesAPI().energy,
            y=y_columns,
            color_discrete_map=color_map,
            line_dash_map=line_dash_map,
        )

    def _update_plot_layout(
        self, fig: Figure, args_plot: PlotAPI, df_2_provided: bool
    ) -> None:
        """Update the plot layout."""
        height = args_plot.size[1][0]
        self.update_layout_axes(fig, args_plot, height)

        xaxis_title = self.title_text(
            name=args_plot.xaxis_title.name, unit=args_plot.xaxis_title.unit
        )
        yaxis_title = self.title_text(
            name=args_plot.yaxis_title.name, unit=args_plot.yaxis_title.unit
        )

        fig.update_xaxes(title_text=xaxis_title, row=1, col=1)
        fig.update_xaxes(title_text=xaxis_title, row=2, col=1)

        if not df_2_provided:
            residual_title = self.title_text(
                name=args_plot.residual_title.name, unit=args_plot.residual_title.unit
            )
            fig["layout"]["yaxis1"].update(domain=[0.8, 1])
            fig["layout"]["yaxis2"].update(domain=[0, 0.7])
            fig.update_yaxes(title_text=residual_title, row=1, col=1)
        else:
            fig.update_yaxes(title_text=yaxis_title, row=1, col=1)

        fig.update_yaxes(title_text=yaxis_title, row=2, col=1)

    def plot_dataframe(self, args_plot: PlotAPI, df: pd.DataFrame) -> None:
        """Plot the dataframe according to the PlotAPI arguments.

        Args:
            args_plot (PlotAPI): PlotAPI object for the settings of the plot.
            df (pd.DataFrame): Dataframe to plot.
        """
        fig = px.line(df, x=args_plot.x, y=args_plot.y)
        height = args_plot.size[1][0]
        self.update_layout_axes(fig, args_plot, height)

        fig.update_xaxes(
            title_text=self.title_text(
                name=args_plot.xaxis_title.name, unit=args_plot.xaxis_title.unit
            )
        )
        fig.update_yaxes(
            title_text=self.title_text(
                name=args_plot.yaxis_title.name, unit=args_plot.yaxis_title.unit
            )
        )
        fig.show(
            config={
                "toImageButtonOptions": {
                    "format": "png",
                    "filename": "plot_dataframe",
                    "scale": 4,
                }
            }
        )

    def plot_global_fit(self, args_plot: PlotAPI, df: pd.DataFrame) -> None:
        """Plot the global dataframe according to the PlotAPI arguments.

        Args:
            args_plot (PlotAPI): PlotAPI object for the settings of the plot.
            df (pd.DataFrame): Dataframe to plot.
        """
        num_fits = df.columns.str.startswith(ColumnNamesAPI().fit).sum()
        for i in range(1, num_fits + 1):
            cols = [col for col in df.columns if col.endswith(f"_{i}")]
            cols.append(ColumnNamesAPI().energy)
            df_subset = df[cols].rename(
                columns={
                    f"{ColumnNamesAPI().intensity}_{i}": ColumnNamesAPI().intensity,
                    f"{ColumnNamesAPI().fit}_{i}": ColumnNamesAPI().fit,
                    f"{ColumnNamesAPI().residual}_{i}": ColumnNamesAPI().residual,
                }
            )
            self.plot_2dataframes(args_plot, df_subset)

    def plot_metric(
        self,
        args_plot: PlotAPI,
        df_metric: pd.DataFrame,
        bar_criteria: Union[str, List[str]],
        line_criteria: Union[str, List[str]],
    ) -> None:
        """Plot the metric according to the PlotAPI arguments.

        Args:
            args_plot (PlotAPI): PlotAPI object for the settings of the plot.
            df_metric (pd.DataFrame): Metric dataframe to plot.
            bar_criteria (Union[str, List[str]]): Criteria to plot as bars.
            line_criteria (Union[str, List[str]]): Criteria to plot as lines.
        """
        fig = make_subplots(specs=[[{"secondary_y": True}]])
        fig_bar = px.bar(
            df_metric,
            y=bar_criteria,
            color_discrete_sequence=args_plot.color.bars,
        )
        fig_line = px.line(
            df_metric,
            y=line_criteria,
            color_discrete_sequence=args_plot.color.lines,
        )
        fig_line.update_traces(mode="lines+markers", yaxis="y2")

        for trace in fig_bar.data:
            fig.add_trace(trace)
        for trace in fig_line.data:
            fig.add_trace(trace)

        fig.update_layout(xaxis_type="category")
        height = args_plot.size[1][1]
        self.update_layout_axes(fig, args_plot, height)

        fig.update_xaxes(
            title_text=self.title_text(
                name=args_plot.run_title.name, unit=args_plot.run_title.unit
            )
        )
        fig.update_yaxes(
            title_text=self.title_text(
                name=args_plot.metric_title.name_0, unit=args_plot.metric_title.unit_0
            ),
            secondary_y=False,
        )
        fig.update_yaxes(
            title_text=self.title_text(
                name=args_plot.metric_title.name_1, unit=args_plot.metric_title.unit_1
            ),
            secondary_y=True,
        )
        fig.show(
            config={
                "toImageButtonOptions": {
                    "format": "png",
                    "filename": "plot_metric",
                    "scale": 4,
                }
            }
        )

    def update_layout_axes(
        self, fig: Figure, args_plot: PlotAPI, height: int
    ) -> Figure:
        """Update the layout of the plot.

        Args:
            fig (Figure): Figure to update.
            args_plot (PlotAPI): PlotAPI object for the settings of the plot.
            height (int): Height of the plot.

        Returns:
            Figure: Updated figure.
        """
        fig.update_layout(
            title=args_plot.title,
            legend_title=args_plot.legend_title,
            legend=args_plot.legend.model_dump(),
            font=args_plot.font.model_dump(),
            showlegend=args_plot.show_legend,
            width=args_plot.size[0],
            height=height,
            paper_bgcolor=args_plot.color.paper,
            plot_bgcolor=args_plot.color.plot,
        )

        minor_ticks = self.get_minor(args_plot)

        fig.update_xaxes(
            minor=minor_ticks,
            gridcolor=args_plot.color.grid,
            linecolor=args_plot.color.line,
            zerolinecolor=args_plot.color.zero_line,
            color=args_plot.color.color,
        )
        fig.update_yaxes(
            minor=minor_ticks,
            gridcolor=args_plot.color.grid,
            linecolor=args_plot.color.line,
            zerolinecolor=args_plot.color.zero_line,
            color=args_plot.color.color,
        )
        return fig

    @staticmethod
    def title_text(name: str, unit: Optional[str] = None) -> str:
        """Return the title text.

        Args:
            name (str): Name of the variable.
            unit (Optional[str], optional): Unit of the variable. Defaults to None.

        Returns:
            str: Title text.
        """
        return f"{name} [{unit}]" if unit else name

    def get_minor(self, args_plot: PlotAPI) -> Dict[str, Union[str, bool]]:
        """Get the minor axis arguments.

        Args:
            args_plot (PlotAPI): PlotAPI object for the settings of the plot.

        Returns:
            Dict[str, Union[str, bool]]: Dictionary with the minor axis arguments.
        """
        return {
            "tickcolor": args_plot.color.ticks,
            "showgrid": args_plot.grid.show,
            "ticks": args_plot.grid.ticks,
            "griddash": args_plot.grid.dash,
        }

class ExportReport(SolverResults):
    """Class for exporting results as toml."""

    def __init__(
        self,
        description: DescriptionAPI,
        initial_model: List[Dict[str, Dict[str, Dict[str, Any]]]],
        pre_processing: DataPreProcessingAPI,
        settings_solver_models: SolverModelsAPI,
        fname: FnameAPI,
        args_out: Dict[str, Any],
        df_org: pd.DataFrame,
        df_fit: pd.DataFrame,
        df_pre: pd.DataFrame = pd.DataFrame(),
    ) -> None:
        """Initialize the ExportReport class.

        Args:
            description (DescriptionAPI): Description of the fit project.
            initial_model (List[Dict[str, Dict[str, Dict[str, Any]]]]): Initial model
                 for the fit.
            pre_processing (DataPreProcessingAPI): Data pre-processing settings.
            settings_solver_models (SolverModelsAPI): Solver models settings.
            fname (FnameAPI): Filename of the fit project including the path, prefix,
                 and suffix.
            args_out (Dict[str, Any]): Dictionary of SpectraFit settings and results.
            df_org (pd.DataFrame): Dataframe of the original data for performing
                 the fit.
            df_fit (pd.DataFrame): Dataframe of the final fit data.
            df_pre (Optional[pd.DataFrame], optional): Dataframe of the pre-processed.
                 Defaults to pd.DataFrame().
        """
        super().__init__(args_out=args_out)
        self.description = description
        self.initial_model = initial_model
        self.pre_processing = pre_processing
        self.settings_solver_models = settings_solver_models
        self.fname = fname

        self.df_org = df_org.to_dict(orient="list")
        self.df_fit = df_fit.to_dict(orient="list")
        self.df_pre = df_pre.to_dict(orient="list")

    @property
    def make_input_contribution(self) -> InputAPI:
        """Make input contribution of the report.

        Returns:
            InputAPI: Input contribution of the report as class.
        """
        return InputAPI(
            description=self.description,
            initial_model=self.initial_model,
            pre_processing=self.pre_processing,
            method=FitMethodAPI(
                global_fitting=self.settings_global_fitting,
                confidence_interval=self.settings_conf_interval,
                configurations=self.settings_configurations,
                settings_solver_models=self.settings_solver_models.model_dump(
                    exclude_none=True
                ),
            ),
        )

    @property
    def make_solver_contribution(self) -> SolverAPI:
        """Make solver contribution of the report.

        Returns:
            SolverAPI: Solver contribution of the report as class.
        """
        return SolverAPI(
            goodness_of_fit=self.get_gof,
            regression_metrics=self.get_regression_metrics,
            descriptive_statistic=self.get_descriptive_statistic,
            linear_correlation=self.get_linear_correlation,
            component_correlation=self.get_component_correlation,
            confidence_interval=self.get_confidence_interval,
            covariance_matrix=self.get_covariance_matrix,
            variables=self.get_variables,
            errorbars=self.get_errorbars,
            computational=self.get_computational,
        )

    @property
    def make_output_contribution(self) -> OutputAPI:
        """Make output contribution of the report.

        Returns:
            OutputAPI: Output contribution of the report as class.
        """
        return OutputAPI(df_org=self.df_org, df_fit=self.df_fit, df_pre=self.df_pre)

    def __call__(self) -> Dict[str, Any]:
        """Get the complete report as dictionary.

        !!! info "About the report and `exclude_none_dictionary`"

            The report is generated by using the `ReportAPI` class, which is a
            `Pydantic`-definition of the report. The `Pydantic`-definition is
            converted to a dictionary by using the `.model_dump()` option of `Pydantic`.
            The `recursive_exclude_none` function is used to remove all `None` values
            from the dictionary, which are hidden in the nested dictionaries.

        Returns:
            Dict[str, Any]: Report as dictionary by using the `.dict()` option of
                 pydantic. `None` is excluded.
        """
        report = ReportAPI(
            input=self.make_input_contribution,
            solver=self.make_solver_contribution,
            output=self.make_output_contribution,
        ).model_dump(exclude_none=True)
        report = exclude_none_dictionary(report)
        report = transform_nested_types(report)
        return report

class ExportResults:
    """Class for exporting results as csv."""

    def export_df(self, df: pd.DataFrame, args: FnameAPI) -> None:
        """Export the dataframe as csv.

        Args:
            df (pd.DataFrame): Dataframe to export.
            args (FnameAPI): Arguments for the file export including the path, prefix,
                 and suffix.
        """
        df.to_csv(
            self.fname2path(
                fname=args.fname,
                prefix=args.prefix,
                suffix=args.suffix,
                folder=args.folder,
            ),
            index=False,
        )

    def export_report(self, report: Dict[Any, Any], args: FnameAPI) -> None:
        """Export the results as toml file.

        Args:
            report (Dict[Any, Any]): Results as dictionary to export.
            args (FnameAPI): Arguments for the file export including the path, prefix,
                 and suffix.
        """
        with self.fname2path(
            fname=args.fname,
            prefix=args.prefix,
            suffix=args.suffix,
            folder=args.folder,
        ).open(
            "wb+",
        ) as f:
            tomli_w.dump(report, f)

    @staticmethod
    def fname2path(
        fname: str,
        suffix: str,
        prefix: Optional[str] = None,
        folder: Optional[str] = None,
    ) -> Path:
        """Translate string to Path object.

        Args:
            fname (str): Filename
            suffix (str): Name of the suffix of the file.
            prefix (Optional[str], optional): Name of the prefix of the file. Defaults
                 to None.
            folder (Optional[str], optional): Folder, where it will be saved.
                 This folders will be created, if not exist. Defaults to None.

        Returns:
            Path: Path object of the file.
        """
        if prefix:
            fname = f"{prefix}_{fname}"
        _fname = Path(fname).with_suffix(f".{suffix}")
        if folder:
            Path(folder).mkdir(parents=True, exist_ok=True)
            _fname = Path(folder) / _fname
        return _fname