phenonaut.output package

Submodules

phenonaut.output.boxplot module

phenonaut.output.boxplot.write_boxplot_to_file(df: DataFrame, x_label_in_df: str, y_label_in_df: str, output_file: str | Path, title='Boxplot', x_label: str | None = None, y_label: str | None = None, figsize=(10, 6.18), orient: str | None = None)

Write a boxplot to a file

Boxplot generation from pd.DataFrames using the Seaborn library

Parameters:

  • df (pd.DataFrame) – Input DataFrame

  • x_label_in_df (str) – Label for the x-axis which appears in the dataframe.

  • y_label_in_df (str) – Label for the y-axis which appears in the dataframe.

  • output_file (Union[str, Path]) – Output (PNG) filename.

  • title (str, optional) – Title to be displayed on the plot, by default “Boxplot”

  • x_label (Optional[str], optional) – Optionally, override the use of the x-label present in the dataframe and display a different one on the axis. If None, the the value of x_label_in_df is used. By default None.

  • y_label (Optional[str], optional) – Optionally, override the use of the y-label present in the dataframe and display a different one on the axis. If None, the the value of y_label_in_df is used. By default None.

  • figsize (tuple, optional) – Optional tuple of image height-width (in inches - as dictated by matplotlib/seaborn), by default (10, 6.18).

  • orient (str, optional) – ‘h’ or ‘v’ accepted and passed to seaborn to orient boxplots horizontally or vertically respectively. If None, then the best orientation is guessed. By default None.

phenonaut.output.heatmap module

phenonaut.output.heatmap.write_heatmap_from_df(df: DataFrame, title: str, output_file: str | Path, axis_labels: tuple[str, str] = ('', ''), annot: bool | ndarray = True, transpose: bool | None = None, standard_deviations_df: DataFrame | None = None, figsize: Tuple | List | None = None, figure_dpi: int = 300, vmin: float | None = None, vmax: float | None = None, annotation_fontsize: int = 10, annotation_best_fontsize: int = 12, lower_is_better: bool = False, annotation_format_string_value='.2f', annotation_format_string_std='.3f', highlight_best: bool = True, pallet_name: str = 'seagreen', put_cbar_on_left: bool = False, sns_colour_palette: Colormap | None = None) → None

Write heatmap from pd.DataFrame

Write a PNG or SVG heatmap image to a file uisng seaborn to read from a pd.DataFrame.

Parameters:

  • df (pd.DataFrame) – Input DataFrame containing values for the heatmap

  • title (str) – Heatmap title

  • output_file (Union[str, Path]) – Output path for the image, must have the extension .png or .svg.

  • axis_labels (tuple[str, str], optional) – Tuple denoting labels to use for each axis, by default (“”, “”)

  • annot (Union[bool, np.ndarray], optional) – If True, the the values of each heatmap cell/box are writen alongside applying the correct background colouring to the cell/box. By default True.

  • transpose (Union[bool, None], optional) – Transpose the heatmap, by default None

  • standard_deviations_df (Optional[pd.DataFrame], optional) – Optionally, supply a second pd.DataFrame containing standard deviations which may be included alongside the annotations within each cell/box. By default None.

  • figsize (Optional[Union[Tuple, List]], optional) – Optional argument for setting the figure size. If None, then a target output width is set at 10, and the height calculated through examination of the number of elements, keeping square aspect ratios for each cell/box. By default None.

  • figure_dpi (int, optional) – Resolution (dots per inch) at which to save the image (only useful if writing PNGs), by default 300.

  • vmin (Optional[float], optional) – Minimum value to use for defining the colour/shading range. If None, then it is set to the lowest value present in the input DataFrame. By default None.

  • vmax (Optional[float], optional) – Maximum value to use for defining the colour/shading range. If None, then it is set to the highest value present in the input DataFrame. By default None.

  • annotation_fontsize (int, optional) – Font size for annotations, by default 10

  • annotation_best_fontsize (int, optional) – Font size for the annotation used to highlight the best value present within the input DataFrame, by default 12

  • lower_is_better (bool, optional) – Used for selecting the best value within the dataframe. If True, then the best heatmap value is taken to be the lowest. By default False.

  • annotation_format_string_value (str, optional) – Optional formatting string for annotation f-strings, by default “.2f”.

  • annotation_format_string_std (str, optional) – Optional formatting string for standard deviation annotation f-strings, by default “.3f”.

  • highlight_best (bool, optional) – If True, then highlight the best result, with best being determined through use of the ‘lower_is_better’ keyword. By default True.

  • pallet_name (str, optional) – Pallet to use for the colour bar. By default “seagreen”.

  • put_cbar_on_left (bool, optional) – If True, then position the colour bar on the left. If False, then position the colour bar on the right. By default False.

  • sns_colour_palette (Optional[Colormap], optional) – Optionally, supply a seaborn colour map for use in the colour bar. By default None.

phenonaut.output.pair_plot module

phenonaut.output.pair_plot.show_pair_plot(self, ds: Dataset)

Visualise the dataset using a pairplot.

Parameters:

ds (Dataset) – The dataset to visualise

phenonaut.output.pptx module

class phenonaut.output.pptx.PhenonautPPTX(cover_title: str = 'Phenonaut', cover_subtitle: str = '', template_file: str | Path | None = None, experiment_hash: str | None = None)

Bases: object

Phenonaut PPTX class

Allows the creation of PPTX presentation files through insertion of images into slides.

Instantiate the object using:

Parameters:

  • cover_title (str, optional) – Title to be displayed on the main title page of the presentation, by default “Phenonaut”.

  • cover_subtitle (str, optional) – Subtitle to be displayed on the main title page of the presentation, by default an empty string (“”).

  • template_file (Optional[Union[Path, str]], optional) – Template file that can be used to style the presentation. Phenonaut is supplied with a suitable template which is used as default when this argument is None. By default None.

  • experiment_hash (Optional[str], optional) – Optionally supply a hash string which is displayed within the PPTX file. By default None.

Then call add_image_slide to add slides, before finally calling save.

add_image_slide(title: str, img_file: Path | str, width: int | float | None = None, height: int | float | None = None)

Add an image slide to an existing presentation

Parameters:

  • title (str) – Slide title

  • img_file (Union[Path, str]) – Image file to insert into slide

  • width (Optional[Union[int, float]], optional) – Width in cm to scale image. No scaling is done if argument is None, by default None.

  • height (Optional[Union[int, float]], optional) – Height in cm to scale image. No scaling is done if argument is None, by default None.

save(output_pptx_file: Path | str)

Save the presentation

Parameters:

output_pptx_file (Union[Path, str]) – Output file path

phenonaut.output.scatter module

class phenonaut.output.scatter.Scatter(plot_config: Path | str | dict | None = None, figsize: Tuple[float, float] | None = (8, 6), title: str | None = '2D scatter', x_label: str | None = None, y_label: str | None = None, show_legend: bool | None = True, marker_size: int = 90, axis_ranges: Tuple[Tuple[float, float], Tuple[float, float]] | None = ((None, None), (None, None)))

Bases: PhenonautVisualisation

Phenonaut scatter visualisation object.

The object should be constructed, and then its add member function used to add points to the scatter. It may then be saved by calling save, or displayed using show.

Scatter inherits from the PhenonautVisualisation base class, which optionally stores a dictionary called plot_config. As currently implemented, plot_config dictionaries can contain one nested dictionary under a ‘plot_markers’ key, with keys to this nested dictionary being perturbation ids, and values are arguments to the matplotlib marker types. To populate this base class dictionary, pass a config dictionary to the constructor, like

{'plot_markers':{'pert1':'X', 'pert2':'x'}}.
Parameters:

  • plot_config (Optional[Union[Path, str, dict]], optional) – Optional configuration dictionary, allows alows specification of initialisation arguments via dictionary. Supply keys and values as argument as values. By default None.

  • figsize (Optional[Tuple[float, float]], optional) – Output figure size (in inches, as directed by matplotlib/seaborn). By default (8, 6)

  • title (Optional[str], optional) – Plot title, by default “2D scatter”

  • x_label (Optional[str], optional) – x-axis label, by default None

  • y_label (Optional[str], optional) – y-axis label, by default None

  • show_legend (Optional[bool], optional) – If True, then add a legend to the plot. By default True.

  • marker_size (int, optional) – The size of each datapoint within the scatter. By default 90

  • axis_ranges (Optional[Tuple[Tuple[float, float], Tuple[float, float]]], optional) – Optional tuple of tuples giving the min and max extents of each axis. If None is given for any value, then the corresponding min/max for that axis is calcaulated and used. By default ((None, None), (None, None)).

add(dataset: Dataset | Phenonaut, perturbations: List[str] | None = None, markers: dict | list | bool = True, marker_size: int | None = None)

Add points to the scatter plot

Parameters:

  • dataset (Union[Dataset, Phenonaut]) – Phenonaut dataset or Phenonaut object (if it contains only one dataset) from which to take datapoints.

  • perturbations (Optional[List[str]], optional) – If perturbation column is set on the dataset and a list of perturbations is given here, then plot only those matching datapoints. If None, then all datapoints are plotted. By default None,

  • markers (Union[dict, list, bool], optional) – Dictionary containing pertubation ids as keys, and then values to pass to matplotlib defining marker styles, or a list of tuples of this form. If True, then let matplotlib enumerate marker types. By default True.

  • marker_size (int, optional) – Size at which to draw datapoints. If None, then the value is taken from the marker_size argument used to construct the scatter object see constructor docstring. By default None.

Raises:

DataError – Scatter plots are 2D, more than 2 features found.

save_figure(output_image_path: Path | str, **savefig_kwargs)

Save the current scatter plot to PNG/SVG file

Saving of the image is achieved using the matplotlib plt.savefig. After the output filename, any argument/option may be given that is also valid in calls to plt.savefig.

Parameters:

output_image_path (Union[Path, str]) – Output file path for the scatter plot.

show()

Show the plot on the screen

phenonaut.output.spreadsheet module

phenonaut.output.spreadsheet.write_xlsx(output_file: Path | str, dfs: DataFrame | list[DataFrame] | dict[str, DataFrame], df_names: tuple | str | None = None)

Write an XLSX spreadsheet file

Writing an XLSX file allows multiple sheets to be embedded in a single file which may be advantageous over CSV/TSV in many situations.

Parameters:

  • output_file (Union[Path, str]) – Output file path.

  • dfs (Union[pd.DataFrame, list[pd.DataFrame], dict[str, pd.DataFrame]]) – DataFrame for output, list of DataFrames, or dictionary of DataFrames. If a single DataFrame is given, or list of DataFrames, then the df_names argument must contain a str, or list of str respectively. If a dictionary is passed for this parameter, then the keys under which each DataFrame exist are used as sheet names.

  • df_names (Union[tuple, str], optional) – The name of sheets under which DataFrames are stored in the spreadsheet. If a dictionary was given for the dfs parameter, then this parameter has no effect. If this parameter is None, then sheets are named ‘Sheet#N’, where #N is a number starting at 1 and incremented with each addition of a new sheet. By default None.

Raises:

ValueError – output_file should be Path or str

phenonaut.output.visualisation_base module

class phenonaut.output.visualisation_base.PhenonautVisualisation(plot_config: Path | str | dict | None = None)

Bases: object

Base class for Phenonaut visualisations.

Constructor allows supply of a plot_config dictionary, which is then stored in object under the name ‘config’. Out of this dictionary, if it exists, then a nested ‘plot_markers’ dictionary is extracted and placed into the class’ markers member variable.

Parameters:

config (Optional[Union[Path, str, dict]], optional) – Configuration dictionary, which will be stored in config member variable. If None, then an empty dictionary is initialised as the config member variable. By default, None

Module contents