Configuration Reference ======================= This section provides a reference of the configuration system of OpenHCS. How the configuration system works --------------------------------- In OpenHCS, there are multiple levels of configuration that determine how the software behaves. These levels include: 1. **Global Configuration**: the configuration that applies to the entire OpenHCS installation. 2. **Plate Configuration**: each plate can have its own configuration settings that override the global settings. 3. **Step Configuration**: each step within a plate's pipeline can have its own configuration settings. 4. **Materialization / Viewer Configuration**: for each individual step you can materialize its output to disk or stream it to a viewer (Napari/Fiji); this has its own configuration. Configurations automatically inherit from higher levels and can be overridden at lower levels. For example, you can run your analysis on all wells, but then open only one well in Napari to look at by using the well filter config at the Napari materialization level. Some options also inherit horizontally; those behaviours are explained in the relevant sections. Some levels do not expose all configuration options (for example, materialization has only materialization-relevant options). Appendix: Relevant Configuration Options --------------------------------------- There are several configuration groups used across OpenHCS. Below are commonly used groups and the key options biologists will encounter. (Note: each option usually has a GUI tooltip explaining its purpose.) GlobalPipelineConfig (main app / pipeline defaults) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - ``num_workers`` How many parallel workers to run for processing (higher = more CPU usage, but faster run times). - ``materialization_results_path`` Directory name where non-image analysis results (CSV/JSON) are written by default. - ``use_threading`` If true, use threads instead of processes (useful for some environments, don't touch this unless you know what you're doing). - ``auto_add_output_plate_to_plate_manager`` (abbreviation: ``auto_add_output_plate``) If true, when a plate run completes successfully, the computed output plate root (from path planning) is automatically added to Plate Manager as a new orchestrator if it is not already present. This allows immediate visualization of processed results without manual plate addition. **Environment variable**: ``OPENHCS_AUTO_ADD_OUTPUT_PLATE`` **Default**: ``False`` WellFilterConfig ~~~~~~~~~~~~~~~~~ - ``well_filter`` List, pattern, or integer limiting which wells are included (``None`` = all wells). - ``well_filter_mode`` ``INCLUDE`` or ``EXCLUDE`` behaviour for the ``well_filter`` list. ZarrConfig ~~~~~~~~~~~ - ``compression_level`` Compression level to use for Zarr storage (higher = smaller files but slower). VFSConfig (virtual file system) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - ``read_backend`` Backend used to read input files (auto-detected or explicit choice, don't touch this unless you know what you are doing). - ``intermediate_backend`` Backend for storing temporary intermediate results, like those streamed to viewers (memory, disk, etc.). - ``materialization_backend`` Backend used for explicit materialized outputs (e.g., ``ZARR`` vs ``DISK``). Typical choices for backends are ``ZARR``, ``DISK`` or ``MEMORY``. ``MEMORY`` stores data in system RAM; ``DISK`` writes regular files (e.g., TIFF); ``ZARR`` stores chunked arrays using the Zarr format (more efficient and space friendly for many workflows). AnalysisConsolidationConfig --------------------------- - ``enabled`` Run automatic consolidation of step outputs into summary files. - ``metaxpress_summary`` Produce MetaXpress-compatible summary format. - ``well_pattern``, ``file_extensions``, ``exclude_patterns``, ``output_filename`` Controls for which files to include/exclude and the consolidated output name. PlateMetadataConfig ~~~~~~~~~~~~~~~~~~~ - ``barcode``, ``plate_name``, ``plate_id``, ``description``, ``acquisition_user`` Optional metadata fields for the plate. PathPlanningConfig (directory / output naming) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - ``well_filter`` / ``well_filter_mode`` Inherited from ``StepWellFilterConfig`` unless overridden. - ``output_dir_suffix`` Suffix appended to generated output folders (default ``"_openhcs"``). For example, if your input folder is ``data/plate1``, the output folder will be ``data/plate1_openhcs``. - ``global_output_folder`` Optional root folder to place all plate workspaces and outputs. - ``sub_dir`` Subdirectory name used for image outputs inside a workspace. StepWellFilterConfig and StepMaterializationConfig ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - Step-level versions of well filtering and path planning. They inherit from higher levels unless overridden. - ``step_materialization_config.sub_dir`` Default folder for step-level materializations (default ``"checkpoints"``). VisualizerConfig ~~~~~~~~~~~~~~~~~ - ``temp_directory`` Directory for temporary visualization files (if ``None``, system temp is used). StreamingConfig (abstract) ~~~~~~~~~~~~~~~~~~~~~~~~~~ - ``persistent`` If true, keeps the streaming service open after initial use. NapariStreamingConfig ~~~~~~~~~~~~~~~~~~~~~ - ``colormap`` Colormap to use for visualization. - ``variable_size_handling`` How to handle variable-sized images (pad, rescale, etc.). - ``site``, ``channel``, ``timepoint``, ``well``, ``z_index``, ``step_name``, ``step_index``, ``source_mode`` Options for whether you'd like to group different variables by slice or stack. - ``napari_port``, ``napari_host`` Network settings for Napari streaming. FijiStreamingConfig ~~~~~~~~~~~~~~~~~~~ - ``lut`` Colormap to use for visualization. - ``auto_contrast`` If true, applies auto-contrast to images. - ``site``, ``channel``, ``timepoint``, ``well``, ``z_index``, ``step_name``, ``step_index``, ``source_mode`` Options for whether you'd like to group different variables by slice or stack. - ``fiji_port``, ``fiji_host``, ``fiji_executable_path`` Settings for Fiji/ImageJ streaming and the local executable location. Notes ~~~~~~ The above lists the configuration options most relevant to biologists using OpenHCS. There are many additional developer-level options in the code documentation (see ``openhcs/core/config.py`` for global defaults). If you don't know what an option does, it's usually best to leave it at its default value.