Pype class

phenopype’s core method to process image datasets with high throughput and reproducibility. Should be used in conjunction with images organized in a Phenopype directory structure. The Pype class has specific implicit behavior that aims at supporting speed and robustness when working in “production” (i.e., when performing the actual analysis of large image datasets compared to prototyping and low throughput workflow). These are the most important things to keep in mind during a Pype iteration:


Enhanced Window control

In addition to regular window control functions documented in Tutorial 2:

  • Editing and saving the opened configuration file in the text editor will trigger another iteration, i.e., close the image window and run the config file again.

  • Closing the image window manually (with the X button in the upper right) also triggers another run.

  • Esc will close all windows and interrupt the pype routine (triggers sys.exit(), which will also end a Python session if run from the command line), as well as any loops.

  • Each step that requires user interaction (e.g., create_mask or landmarks) needs to be confirmed with Enter until the next function in the sequence is executed.

  • At the end of the analysis, when the final steps (visualization and export functions) have run, use Ctrl+Enter to finish and close the window.

Function execution

  • Pype will automatically load the image and execute all functions in sequence, but it will not overwrite data from past iterations on disk unless specified.

  • To overwrite interactive user input, set the argument edit: true or edit: overwrite in the function’s annotation control arguments.

  • If you forget to remove an overwrite argument and are prompted to overwrite previous input, immediately change to edit: false argument, and save the config file.

  • If a Pype is initialized on a project directory, it will attempt to load input data (e.g., masks) that contain the provided tag argument. For example, pp.Pype(path, tag="v1") will attempt to load any files in the directory that contain the suffix "v1" (e.g., "annotations_v1.json").

Visualizing the results

Aspects of visual feedback during a pype run (can be completely suppressed by setting visualize=False):

  • Visual feedback (i.e., output from landmarks, detect_contours or create_mask) are drawn onto a “canvas” (a copy of the original image).

  • Use select_canvas to draw the results either on the raw image, a binary image, or a single color channel (gray, red, green or blue).

  • If select_canvas is not explicitly specified, it is called automatically and defaults to the raw image as canvas.

  • Output from all functions needs to be specified manually. For example, after using - landmarks, - draw_landmarks should be called in the visualization module.

  • Visual parameters of interactive tools (e.g., point_size or line_thickness) are specified separately in the respective function and in the visualization module.

Exporting the results

Saving annotations, canvas, and other results:

  • All results are saved automatically, even if the respective functions in export are not specified, with the tag argument in Pype as suffix.

  • If a file already exists in the directory, and the respective function is not listed under export, then it will not be overwritten.

  • If an export function is specified under export:, it will also not overwrite any existing file, unless specified using overwrite: true.

  • The canvas is an exception: it will always be saved and always be overwritten (unless specified with overwrite: False) to show the output from the last iteration. However, users can modify the canvas name with file_name in the arguments to save different output side by side. For example, file_name: binary under - save_canvas: saves the canvas as canvas_binary.jpg.

class phenopype.main.Pype(image_path, tag, skip=False, interactive=True, feedback=True, autoload=True, autosave=True, autoshow=True, log_ow=False, config_path=None, fix_names=True, load_contours=False, zoom_memory=True, debug=False, **kwargs)

Bases: object

The pype is phenopype’s core method that allows running all functions that are available in the program’s library in sequence. Users can execute the pype method on a file_path, an array, or a phenopype directory, which always will trigger three actions:

  1. open the contained yaml configuration with the default OS text editor

  2. parse the contained functions and execute them in the sequence (exceptions will be passed, but returned for diagnostics)

  3. open a Python-window showing the processed image.

After one iteration of these steps, users can evaluate the results and decide to modify the opened configuration file (e.g. either change function parameters or add new functions), and run the pype again, or to terminate the pype and save all results. The processed image, any extracted phenotypic information, as well as the modified config-file is stored inside the image directory, or a user-specified directory. By providing unique names, users can store different pype configurations and the associated results side by side.

  • image (array or str) – can be either a numpy array or a string that provides the path to source image file or path to a valid phenopype directory

  • name (str) – name of pype-config - will be appended to all results files

  • config_template (str, optional) – chose from list of provided templates (e.g. ex1, ex2, …)

  • config_path (str, optional) – custom path to a pype template (needs to adhere yaml syntax and phenopype structure)

  • delay (int, optional) – time in ms to add between reload attemps of yaml monitor. increase this value if saved changes in config file are not parsed in the first attempt.

  • dir_path (str, optional) – path to an existing directory where all output should be stored

  • skip (bool, optional) – skip directories that already have “name” as a suffix in the filename

  • interactive (bool, optional) – don’t open text editor or window, just apply functions and terminate

  • max_dim (int, optional) – maximum dimension that window can have

  • kwargs – developer options