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:

Important

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, skip_pattern='canvas', interactive=True, feedback=True, autoload=True, autosave=True, autoshow=True, log_ow=False, dir_path=None, 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.

Parameters:

  • image_path (str) – Path to the source image file or a valid phenopype directory.

  • tag (str) – Tag to label and identify the Pype configuration, appended to all result files.

  • skip (bool, optional) – Skip directories that already contain processed files with the specified tag (default is False).

  • skip_pattern (str, optional) – Pattern to identify files that should be skipped (default is “canvas”).

  • interactive (bool, optional) – If True, enables interactive mode which may open text editors or image windows (default is True).

  • feedback (bool, optional) – Enable verbose feedback throughout the processing steps (default is True).

  • autoload (bool, optional) – Automatically load existing data or configurations if available (default is True).

  • autosave (bool, optional) – Automatically save results upon completion of processing (default is True).

  • autoshow (bool, optional) – Automatically display images after processing (default is True).

  • log_ow (bool, optional) – Overwrite existing log files (default is False).

  • dir_path (str, optional) – Specify a directory where all output should be stored. Defaults to the directory of the image path.

  • config_path (str, optional) – Custom path to a Pype configuration file. Must adhere to YAML syntax and phenopype structure.

  • fix_names (bool, optional) – Automatically correct deprecated function names to the current accepted names (default is True).

  • load_contours (bool, optional) – Preload contours from saved data (default is False).

  • zoom_memory (bool, optional) – Remember zoom settings between sessions (default is True).

  • debug (bool, optional) – Enable debug mode to provide detailed error messages and processing info (default is False).

  • kwargs (dict) – Additional keyword arguments for developer options.

Return type:

Pype instance (for inspection)

Examples

>>> pype_instance = Pype(image_path="path/to/image.jpg", tag="experiment_1")
Initializes a Pype instance for non-interactive processing with automatic saving enabled.