bactoscoop.imagecollection¶
The public collection coordinates loading, geometry, curation, measurements, and export. See Quick start.
Classes and public operations¶
ImageCollection¶
- class bactoscoop.imagecollection.ImageCollection(image_folder_path=None, px=0.065, error_policy='continue', log_cell_errors=False)¶
Create a dataset collection with physical calibration and explicit error handling.
Use this as the public entry point; load fields/masks or reload geometry before dependent analysis.
- Parameters:
image_folder_path – Dataset folder containing TIFFs and the masks subfolder; None delays path configuration.
px – Micrometres per pixel. Geometry arrays remain in pixel coordinates.
error_policy – “continue” records independent item/cell failures; “raise” raises the recorded error. Setup failures can still stop work.
log_cell_errors – Print each recorded cell error when true; recording is independent of this flag.
- Returns:
None (no explicit return statement).
Assigned state:
self.error_policy,self.log_cell_errors,self.processing_errors,self.cell_errors,self.completed_stages,self.px,self.images,self.masks,self.channel_images,self.channel_image_filenames,self.channel_images_by_field,self.inverted_image,self.channel_list,self.image_filenames,self.mask_filenames,self.phase_channel,self.segmentation_failed,self.image_folder_path,self.name,self.image_objects,self.mesh_df_collection,self.feature_dataframes,self.merged_features,self.mesh_prefilter_stats.Explicitly raised exceptions:
ValueError. Errors from called functions can also propagate or be recorded.
ImageCollection.processing_summary¶
- ImageCollection.processing_summary()¶
Report retained stage and cell error history.
Returns a new summary dictionary. completed does not imply every stage ran, and cell errors alone do not change that status.
Return expressions in source:
{'status': status, 'completed_stages': sorted(self.completed_stages), 'error_count': len(self.processing_errors), 'errors': list(self.processing_errors), 'cell_error_count': len(self.cell_errors), 'cell_errors': list(self.cell_errors)}
View current source, line 135.
Original docstring (legacy wording may differ from the current signature)
Return attempted-stage status and retained image/cell error records.
ImageCollection.load_masks¶
- ImageCollection.load_masks()¶
Read label TIFFs from the dataset masks subfolder.
Requires a dataset path; modifies masks and mask filenames; returns None.
- Returns:
None (no explicit return statement).
Assigned state:
self.masks,self.mask_filenames.View current source, line 283.
Original docstring (legacy wording may differ from the current signature)
Read masks from the ``/masks`` subfolder. Mutates ``self.masks`` and ``self.mask_filenames``.
ImageCollection.load_phase_images¶
- ImageCollection.load_phase_images(phase_channel='')¶
Load phase TIFFs using the selected channel suffix.
Requires a dataset path; sets images, filenames, paths, phase suffix, and stage state; returns None.
- Parameters:
phase_channel – TIFF suffix identifying the phase images, such as “C1”. An empty suffix is the signature default.
- Returns:
None (no explicit return statement).
Assigned state:
self.phase_channel,self.images,self.image_filenames,self.paths.Explicitly raised exceptions:
type(e). Errors from called functions can also propagate or be recorded.View current source, line 296.
Original docstring (legacy wording may differ from the current signature)
This method loads phase contrast images from the specified image folder path, based on the characters before the file-extension, and stores them in the 'self.images' array. Parameters ---------- phase_channel : str, optional Characters before the file-extension (e.g., "c1", "phase") to look for when using this function. (default is an empty string) Mutates ``self.images``, ``self.image_filenames`` and ``self.paths``.
ImageCollection.load_channel_images¶
- ImageCollection.load_channel_images(channel_list)¶
Load channels and index their arrays by field identity.
Requires a dataset path; clears stale data for requested channels and records load/duplicate-field failures; returns None.
- Parameters:
channel_list – Sequence of channel suffixes to load or attach.
- Returns:
None (no explicit return statement).
Assigned state:
self.channel_list,self.channel_images,self.channel_image_filenames,self.channel_images_by_field.View current source, line 322.
Original docstring (legacy wording may differ from the current signature)
This method loads channel images from the image folder path based on the specified characters before the file-extension and stores them in the 'self.channel_images' dictionary, where the channel name is used as the key. Parameters ---------- channel_list : List of str Characters before the extension (e.g., ["c2", "c3"]) to look for when using this function. Mutates ``self.channel_images``.
ImageCollection.create_image_objects¶
- ImageCollection.create_image_objects(phase_channel='')¶
Validate field matching and build a fresh image/cell population.
Loads missing phase/mask data, rejects invalid setup or stale masks after segmentation failure, and clears feature tables; returns None.
- Parameters:
phase_channel – TIFF suffix identifying the phase images, such as “C1”. An empty suffix is the signature default.
- Returns:
None (no explicit return statement).
Assigned state:
self.feature_dataframes,self.merged_features,self.image_objects.Explicitly raised exceptions:
RuntimeError. Errors from called functions can also propagate or be recorded.View current source, line 369.
Original docstring (legacy wording may differ from the current signature)
Create ``Image`` objects from the loaded masks and phase images. Invalid collection-level setup raises immediately. Failures while creating a single image object are logged and skipped so the rest of the batch can continue.
ImageCollection.add_channels¶
- ImageCollection.add_channels(img_objects, channel_list, load_data=True)¶
This method loads channel images based on the provided channel list and adds them to the individual image objects.
- Parameters:
img_objects – Image objects to attach channel data to.
channel_list – Sequence of channel suffixes to load or attach.
load_data – Load channel TIFFs before attaching them when true; false uses already loaded field-keyed data.
- Returns:
None (no explicit return statement).
Explicitly raised exceptions:
ValueError. Errors from called functions can also propagate or be recorded.View current source, line 409.
Original docstring (legacy wording may differ from the current signature)
This method loads channel images based on the provided channel list and adds them to the individual image objects. Parameters ---------- img_objects : List List of image objects. channel_list : List List of channel names.
ImageCollection.get_mesh_dataframe¶
- ImageCollection.get_mesh_dataframe(image_name)¶
This method returns the mesh dataframe associated with the specified image name.
- Parameters:
image_name – The name or identifier of the image.
Return expressions in source:
mesh_lookup.get(image_name) None
View current source, line 496.
Original docstring (legacy wording may differ from the current signature)
This method returns the mesh dataframe associated with the specified image name. Parameters ---------- image_name : str The name or identifier of the image.
ImageCollection.create_image_object¶
- ImageCollection.create_image_object(image, image_name, index, mask, mesh_df, px)¶
This method creates a single Image object using the provided image, image name, index, mask, mesh dataframe, and pixel size (px). If mesh data is present, it also creates associated Cell objects.
- Parameters:
image – The phase contrast image for the Image object.
image_name – The name or identifier of the image.
index – The index or position of the image.
mask – The mask or region of interest associated with the image.
mesh_df – The mesh dataframe associated with the image, if available, or None.
px – Micrometres per pixel. Geometry arrays remain in pixel coordinates.
Return expressions in source:
img_objView current source, line 512.
Original docstring (legacy wording may differ from the current signature)
This method creates a single Image object using the provided image, image name, index, mask, mesh dataframe, and pixel size (px). If mesh data is present, it also creates associated Cell objects. Parameters ---------- image : phase contrast image The phase contrast image for the Image object. image_name : str The name or identifier of the image. index : int The index or position of the image. mask : mask or None The mask or region of interest associated with the image. mesh_df : pd.DataFrame or None The mesh dataframe associated with the image, if available, or None. px : float The pixel size in micrometers.
ImageCollection.segment_images¶
- ImageCollection.segment_images(mask_thresh, minsize, n, model_name='bact_phase_omni')¶
Run Omnipose for selected phase images and save their masks.
Requires loaded phase images. Returns True on success or False on a recorded failure in continue mode; raise policy propagates errors.
- Parameters:
mask_thresh – Threshold passed as Omnipose mask_threshold.
minsize – Minimum accepted segmentation-mask size in pixels.
n – Selected image positions; wrapper accepts None for all. Indices must be nonempty, unique valid integers.
model_name – Omnipose model identifier; default collection model is bact_phase_omni.
Return expressions in source:
True False
Assigned state:
self.segmentation_failed,self.masks,self.mask_filenames.
ImageCollection.batch_detect_objects¶
- ImageCollection.batch_detect_objects(channels=None, reset_channels=True, align=False, smoothing=0.1, log_sigma=3, kernel_width=4, min_overlap_ratio=0.01, max_external_ratio=0.1)¶
Replace requested-channel detections and collect object contours/geometry.
Requires image objects with cells. Loads channels, changes cell.object_meshdata and object_detection_df; returns the combined detection DataFrame.
- Parameters:
channels – Requested channel identifiers; for correlation, channel pairs are generated from this sequence.
reset_channels – Clear loaded channel dictionaries and background/interpolation caches before loading requested channels.
align – Use the object-detection alignment path for the selected signal.
smoothing – Smoothing passed to the contour/mesh fitting path.
log_sigma – Laplacian-of-Gaussian sigma for signal-object detection.
kernel_width – Width of the square dilation kernel used for candidate object masks.
min_overlap_ratio – Minimum accepted overlap ratio under the utility implementation; inspect its denominator in source.
max_external_ratio – Maximum accepted outside-cell ratio under the utility implementation.
Return expressions in source:
self.object_detection_df
Assigned state:
self.object_detection_df,self.channel_images,self.channel_image_filenames,self.channel_images_by_field.View current source, line 564.
Original docstring (legacy wording may differ from the current signature)
Detect objects within the contour of the cell. Parameters ---------- channels : List of strings, optional The channel names of the channels to perform object detection on. log_sigma : int, optional The sigma parameter of the Laplacian of Gaussian filter used in object detection. (default is 3) kernel_width : int, optional The kernel width of the kernel used for dilating the object masks. Decreasing results in smaller masks, while increasing results in larger masks. (default is 4) min_overlap_ratio : float, optional Minimum overlap between the object and cell required for the object to be kept. (default is 0.01) max_external_ratio : float, optional The maximum ratio an object is allowed to lie outside the cell contour. (default is 0.1) Returns ------- pd.DataFrame A DataFrame containing cell_id, object_contours, and frame information.
ImageCollection.batch_process_mesh¶
- ImageCollection.batch_process_mesh(pkl_name=None, object_list=None, save_data=True, phase_channel='', join_thresh=4, split_thresh=0.35, CD_width=False, smoothing=0.1, neighbor_filter_max_neighbors=None, neighbor_filter_connectivity=1, max_daughter_cell_mesh_rows=800)¶
Join/split cells, construct geometry, collect mesh tables, and optionally save a pickle.
Requires compatible phase images and masks. Updates cells, mesh_df_collection and mesh_prefilter_stats. Returns None.
- Parameters:
pkl_name – Mesh input filename or pickle output name. For feature output, .pkl means exact filename; a suffixless name is a legacy tag.
object_list – Explicit image-object sequence to process; None selects collection targets.
save_data – Write the combined mesh table when true.
phase_channel – TIFF suffix identifying the phase images, such as “C1”. An empty suffix is the signature default.
join_thresh – Maximum pole-to-pole joining distance in pixels.
split_thresh – Relative constriction threshold used by the splitting pipeline.
CD_width – Use the width-based constriction path when true; otherwise use the pipeline phase-signal path.
smoothing – Smoothing passed to the contour/mesh fitting path.
neighbor_filter_max_neighbors – Maximum number of touching distinct labels allowed before meshing; None disables the prefilter.
neighbor_filter_connectivity – 1 or 4 for edge contact; 2 or 8 for edge and diagonal contact.
max_daughter_cell_mesh_rows – Maximum rebuilt mesh rows per daughter during cell splitting (default 800; integer >= 4). Rejects oversized predicted counts before reconstruction; both final daughters must have 4..limit rows. Does not limit unsplit parents and is separate from feature extraction max_mesh_size.
- Returns:
None (no explicit return statement).
Assigned state:
self.mesh_df_collection,self.mesh_prefilter_stats.Explicitly raised exceptions:
ValueError. Errors from called functions can also propagate or be recorded.View current source, line 688.
Original docstring (legacy wording may differ from the current signature)
Process cellular meshes from segmented masks and store the data in Cell objects. After segmentation, this method can process the resulting masks and create cellular meshes from them. It first joins cells with a pole-pole distance (px) below the 'join_thresh'. Subsequently, meshes of all cells are created and cells can be split again if the constriction degree exceeds the 'split_thresh'. The data is then stored in Cell objects and can be exported in a pickle file. Parameters ---------- pkl_name : str, optional Name of the pickle file to save the mesh data. If None, the file will be saved as 'folder_name_meshdata.pkl'. object_list : List, optional Specify a list of Image objects to be processed. If 'object_list' is None, all Image instances in 'image_objects' are processed. phase_channel : str, optional Characters before the file-extension (.tif, .tiff) that the algorithm looks for when using this function (e.g., "c1", "phase"). join_thresh : int, optional The pole-pole distance threshold for joining cells. Cells with a distance below this threshold will have their masks joined. (default is 4) split_thresh : float, optional The constriction degree threshold for splitting cells. Cells with a constriction degree exceeding this threshold will be split. (default is 0.35) max_daughter_cell_mesh_rows : int, optional Maximum rebuilt daughter mesh rows (default 800, minimum 4). Oversized resampling is rejected before allocation; both final daughters must have 4..limit rows. This is separate from the feature extraction max_mesh_size parameter and does not limit unsplit parents.
ImageCollection.batch_load_mesh¶
- ImageCollection.batch_load_mesh(pkl_name, pkl_path=None, phase_channel='')¶
Load saved pickle or mesh Parquet and reconstruct image objects.
Requires the matching phase images/masks and compatible geometry columns. Recreates population and clears feature state; returns None.
- Parameters:
pkl_name – Mesh input filename or pickle output name. For feature output, .pkl means exact filename; a suffixless name is a legacy tag.
pkl_path – Directory containing an input mesh file; None selects the image folder.
phase_channel – TIFF suffix identifying the phase images, such as “C1”. An empty suffix is the signature default.
- Returns:
None (no explicit return statement).
Assigned state:
self.mesh_df_collection.Explicitly raised exceptions:
FileNotFoundError,ValueError. Errors from called functions can also propagate or be recorded.View current source, line 791.
Original docstring (legacy wording may differ from the current signature)
Load mesh data from a pickle-file and create image objects from the data. Parameters ---------- pkl_name : str Name of the pickle file where the mesh data is stored (e.g., 'Ecoli_meshdata.pkl'). pkl_path : str, optional Path to the file where the mesh data is stored. If not provided, the method will look in the image folder path. phase_channel : str, optional Characters before the file-extension (.tif, .tiff) that the algorithm looks for when using this function (e.g., "c1", "phase").
ImageCollection.batch_mask2mesh¶
- ImageCollection.batch_mask2mesh(pkl_name=None, object_list=None, save_data=True, phase_channel='', smoothing=0.1)¶
Create meshes from masks without the joining or splitting as in the batch_process_mesh method.
- Parameters:
pkl_name – Mesh input filename or pickle output name. For feature output, .pkl means exact filename; a suffixless name is a legacy tag.
object_list – Explicit image-object sequence to process; None selects collection targets.
save_data – Write the combined mesh table when true.
phase_channel – TIFF suffix identifying the phase images, such as “C1”. An empty suffix is the signature default.
smoothing – Smoothing passed to the contour/mesh fitting path.
- Returns:
None (no explicit return statement).
Assigned state:
self.mesh_df_collection.View current source, line 831.
Original docstring (legacy wording may differ from the current signature)
Create meshes from masks without the joining or splitting as in the batch_process_mesh method. Parameters ---------- pkl_name : str, optional Name of the pickle file to save the mesh data. If None, the file will be saved as 'folder_name_meshdata.pkl'. object_list : List, optional Specify a list of Image objects to be processed. If 'object_list' is None, all Image instances in 'image_objects' are processed. phase_channel : str, optional Characters before the file-extension (.tif, .tiff) that the algorithm looks for when using this function (e.g., "c1", "phase").
ImageCollection.batch_shift_correction¶
- ImageCollection.batch_shift_correction(shifted_channel, reset_channels=False, log_sigma=1.5, kernel_width=3, min_overlap_ratio=0.1, max_external_ratio=1, phase_log_sigma=0.5, phase_closing_level=2, signal_closing_level=12, max_shift_correction=15)¶
Batch shift correction.
- Parameters:
shifted_channel – Input
shifted_channelconsumed by this implementation; its exact use is visible in the linked source below. No maintained parameter description is present in the original docstring.reset_channels – Clear loaded channel dictionaries and background/interpolation caches before loading requested channels.
log_sigma – Laplacian-of-Gaussian sigma for signal-object detection.
kernel_width – Width of the square dilation kernel used for candidate object masks.
min_overlap_ratio – Minimum accepted overlap ratio under the utility implementation; inspect its denominator in source.
max_external_ratio – Maximum accepted outside-cell ratio under the utility implementation.
phase_log_sigma – Input
phase_log_sigmaconsumed by this implementation; its exact use is visible in the linked source below. No maintained parameter description is present in the original docstring.phase_closing_level – Input
phase_closing_levelconsumed by this implementation; its exact use is visible in the linked source below. No maintained parameter description is present in the original docstring.signal_closing_level – Input
signal_closing_levelconsumed by this implementation; its exact use is visible in the linked source below. No maintained parameter description is present in the original docstring.max_shift_correction – Input
max_shift_correctionconsumed by this implementation; its exact use is visible in the linked source below. No maintained parameter description is present in the original docstring.
Return expressions in source:
average_success_percentage 0.0
Assigned state:
self.channel_images,self.channel_image_filenames,self.channel_images_by_field.
ImageCollection.batch_calculate_features¶
- ImageCollection.batch_calculate_features(channel_method_pairs, all_data=True, reset=True, use_shifted_contours=False, shift_signal=False, max_mesh_size=600, retain_contour_on_object_mesh_failure_channels=None)¶
Calculate selected feature families for the current cell population.
Requires image objects and loaded signals/detections as appropriate. Replaces selected tables, may remove large cells, clears merged_features; returns the feature_dataframes dictionary.
- Parameters:
channel_method_pairs – Pairs of (channel list, feature method), for example [([None], “morphological”), ([“C2”], “profiling”)].
all_data – Feature-method-specific option; objects includes detailed per-object arrays when true.
reset – Clear stored feature dataframes when true; false retains other pairs while replacing each recalculated pair.
use_shifted_contours – Select stored shifted contour, midline, and mesh geometry; the correction must already exist.
shift_signal – Enable the method-specific optional signal cropping/shift path; this is not a universal object-coordinate shift.
max_mesh_size – Maximum accepted mesh row count; cells above this limit are removed from the image cell population.
retain_contour_on_object_mesh_failure_channels – Channels whose object rows keep contour measurements and NaN mesh aggregates when object geometry fails.
Return expressions in source:
self.feature_dataframes
Assigned state:
self.merged_features,self.feature_dataframes.Explicitly raised exceptions:
ValueError,TypeError. Errors from called functions can also propagate or be recorded.View current source, line 982.
Original docstring (legacy wording may differ from the current signature)
Calculate features of all image objects for specified channels and methods. This method calculates features for all image objects based on the specified channel-method pairs. It takes a list of tuples, where each tuple contains channel names and the feature calculation method. The resulting feature dataframes are stored in a dictionary. Parameters ---------- channel_method_pairs : List[Tuple[List[str], str]] A list of tuples where each tuple contains the channel names and feature calculation method. Example of channel_method_pairs: [(['c1'], 'profiling'), (['c2', 'c3'], 'objects'), ([None], 'svm')]. With the example pairs, this method will analyze c1 using the profiling method, then c2 and c3 using the objects method, and finally the phase contrast channel using the svm method. add_profiling_data : bool, optional Whether to include profiling data in the feature calculation. (default is True) reset : bool, optional If True, the dictionary storing the dataframes will be reset. If False, dataframes are added to the existing dictionary. (default is True) retain_contour_on_object_mesh_failure_channels : list[str] or None, optional Channels whose objects features retain contour-based measurements when any detected object mesh is invalid. Other channels omit that cell's objects feature row. None is equivalent to an empty list. This option does not affect other feature methods. Returns ------- Dict A dictionary containing dataframes with calculated features.
ImageCollection.batch_calculate_signal_correlation_features¶
- ImageCollection.batch_calculate_signal_correlation_features(df, channels, feature_method_tuples)¶
Add selected between-channel measurements to the supplied dataframe.
Requires both prefixed feature columns. Mutates and returns df; does not independently merge or validate an entire workflow.
- Parameters:
df – DataFrame to inspect, transform, or augment. Correlation mutates it in place and returns it.
channels – Requested channel identifiers; for correlation, channel pairs are generated from this sequence.
feature_method_tuples – Pairs of (feature-name list, correlation-selector list) applied to each channel pair.
Return expressions in source:
df
ImageCollection.curate_dataset¶
- ImageCollection.curate_dataset(path_to_model, cols=4, control=False, save_curated_data=True)¶
Predict SVM quality labels and retain the accepted cell population.
Requires cells and a compatible named SVM schema. Resets feature tables, updates curated_df and mesh_df_collection, optionally saves geometry; returns None.
- Parameters:
path_to_model – Path to a serialized SVM carrying the
feature_names_in_training-column schema.cols – Legacy curation argument retained for compatibility; unused by the current curation preparation.
control – Request visual examples of retained/rejected classes; random selection can be unavailable for small classes.
save_curated_data – Write curated mesh pickle when true; in-memory curation always occurs.
- Returns:
None (no explicit return statement).
Assigned state:
self.curated_df,self.pos,self.neg.View current source, line 1235.
Original docstring (legacy wording may differ from the current signature)
Curate the dataset based on a trained support vector machine model. This method calculates SVM features and uses a trained SVM model to classify cells based on these features. It curates the dataset by discarding cells that are classified as label 0 (non-interesting). Optionally, it can include positive and negative control cells. Parameters: path_to_model (str): Path to the trained SVM model. cols (int): Retained for backward compatibility; currently unused. control (bool): Whether to include positive and negative control cells. save_curated_data (bool): Whether to write the curated mesh pickle. The in-memory mesh dataframe is updated either way. Returns: None
ImageCollection.add_meshdata_to_dataframe¶
- ImageCollection.add_meshdata_to_dataframe()¶
Add meshdata to dataframe.
- Returns:
None (no explicit return statement).
Assigned state:
self.mesh_df_collection.
ImageCollection.export_curated_masks¶
- ImageCollection.export_curated_masks(output_subfolder='curated_masks', overwrite=True)¶
Rasterize retained contours and record overlap with original segmentation labels.
Requires image objects with original masks. Writes TIFFs and a provenance CSV; returns (list of mask paths, provenance DataFrame).
- Parameters:
output_subfolder – Destination for newly rasterized curated masks, relative to the dataset folder.
overwrite – Replace existing curated mask TIFFs when true; false raises for a file already present.
Return expressions in source:
(mask_paths, provenance)
Explicitly raised exceptions:
ValueError,FileExistsError. Errors from called functions can also propagate or be recorded.View current source, line 1331.
Original docstring (legacy wording may differ from the current signature)
Write one label mask per image from the SVM-curated cell contours. This method is intended to be run after :meth:`curate_dataset`. It never changes the original Omnipose masks in ``masks``. Instead, it writes new masks to ``output_subfolder`` and records how every curated label overlaps the original labels, so the output can be used directly by BactoFeatures. Parameters ---------- output_subfolder : str, optional Folder below ``image_folder_path`` for the exported label TIFFs. overwrite : bool, optional If ``False``, fail before replacing an existing curated-mask TIFF. Returns ------- tuple[list[str], pandas.DataFrame] Paths to the exported masks and a provenance table with one row per curated cell.
ImageCollection.merge_dataframes¶
- ImageCollection.merge_dataframes(include_metadata_tag=False, discard_morphological_nan=False)¶
Merge family/channel tables by image_name, cell_id, and frame.
Requires feature tables; channel prefixes are added and a first-value pivot is used. Modifies and returns merged_features.
- Parameters:
include_metadata_tag – Rename identity columns with
Metadata_prefixes.discard_morphological_nan – Drop merged rows missing cell_area or cell_length; these columns must exist.
Return expressions in source:
self.merged_features
Assigned state:
self.merged_features.Explicitly raised exceptions:
ValueError. Errors from called functions can also propagate or be recorded.View current source, line 1436.
Original docstring (legacy wording may differ from the current signature)
Merge feature dataframes into a single dataframe. Merges multiple feature dataframes into a single dataframe, ensuring that columns are properly renamed to identify the channel and removes duplicates based on specific columns. Args: include_metadata_tag (bool): Whether to rename 'image_name', 'cell_id', and 'frame' to 'Metadata_*'. discard_nan (bool): Whether to discard rows with NaN in 'cell_area' and 'cell_length'. Returns: pd.DataFrame: The merged feature dataframe.
ImageCollection.dataframe_to_pkl¶
- ImageCollection.dataframe_to_pkl(pkl_name=None)¶
Save merged features as a pickle in the image folder.
Requires merged_features; uses atomic replacement and returns the saved path.
- Parameters:
pkl_name – Mesh input filename or pickle output name. For feature output, .pkl means exact filename; a suffixless name is a legacy tag.
Return expressions in source:
os.path.join(self.image_folder_path, filename)
Explicitly raised exceptions:
ValueError. Errors from called functions can also propagate or be recorded.View current source, line 1504.
Original docstring (legacy wording may differ from the current signature)
Save merged features in the image folder and return the pickle path. A suffixless ``pkl_name`` is a legacy tag appended to the dataset name; a name ending in ``.pkl`` is used as the exact filename.
ImageCollection.meshdata_to_parquet¶
- ImageCollection.meshdata_to_parquet(parquet_name=None)¶
Save reloadable nested geometry to compressed Parquet.
Requires nonempty mesh_df_collection; writes within the image folder and returns None.
- Parameters:
parquet_name – Output filename ending in .parquet within the image folder; None chooses the dataset-based default.
- Returns:
None (no explicit return statement).
Explicitly raised exceptions:
ValueError. Errors from called functions can also propagate or be recorded.View current source, line 1521.
Original docstring (legacy wording may differ from the current signature)
Save the current mesh dataframe as reloadable Parquet in the image folder. Geometry arrays become nested numeric lists in Parquet. Reload with ``batch_load_mesh("name.parquet", phase_channel=...)``. Requires the optional ``pyarrow`` package.
ImageCollection.dataframe_to_parquet¶
- ImageCollection.dataframe_to_parquet(parquet_name=None)¶
Save merged features as compressed Parquet in the image folder.
Requires merged_features and PyArrow; replaces the target atomically and returns None.
- Parameters:
parquet_name – Output filename ending in .parquet within the image folder; None chooses the dataset-based default.
- Returns:
None (no explicit return statement).
Explicitly raised exceptions:
ValueError. Errors from called functions can also propagate or be recorded.View current source, line 1533.
Original docstring (legacy wording may differ from the current signature)
Save merged features as Parquet in the image folder (requires pyarrow).
Internal helpers¶
ImageCollection._require_image_folder_path¶
- ImageCollection._require_image_folder_path()¶
require image folder path.
- Returns:
None (no explicit return statement).
Explicitly raised exceptions:
ValueError. Errors from called functions can also propagate or be recorded.
ImageCollection._require_loaded_images¶
- ImageCollection._require_loaded_images()¶
require loaded images.
- Returns:
None (no explicit return statement).
Explicitly raised exceptions:
ValueError. Errors from called functions can also propagate or be recorded.
ImageCollection._record_processing_error¶
- ImageCollection._record_processing_error(stage, error, image_name=None, channel=None, cell_id=None)¶
record processing error.
- Parameters:
stage – Input
stageconsumed by this implementation; its exact use is visible in the linked source below. No maintained parameter description is present in the original docstring.error – Input
errorconsumed by this implementation; its exact use is visible in the linked source below. No maintained parameter description is present in the original docstring.image_name – Input
image_nameconsumed by this implementation; its exact use is visible in the linked source below. No maintained parameter description is present in the original docstring.channel – Channel identifier for the selected signal, or None for phase/morphology where supported.
cell_id – Cell identifier local to the selected image; check that it remains after curation/filtering.
Return expressions in source:
record
ImageCollection._record_cell_error¶
- ImageCollection._record_cell_error(stage, error, image_name, channel, cell_id, error_type=None)¶
record cell error.
- Parameters:
stage – Input
stageconsumed by this implementation; its exact use is visible in the linked source below. No maintained parameter description is present in the original docstring.error – Input
errorconsumed by this implementation; its exact use is visible in the linked source below. No maintained parameter description is present in the original docstring.image_name – Input
image_nameconsumed by this implementation; its exact use is visible in the linked source below. No maintained parameter description is present in the original docstring.channel – Channel identifier for the selected signal, or None for phase/morphology where supported.
cell_id – Cell identifier local to the selected image; check that it remains after curation/filtering.
error_type – Input
error_typeconsumed by this implementation; its exact use is visible in the linked source below. No maintained parameter description is present in the original docstring.
Return expressions in source:
record
ImageCollection._record_stage_success¶
- ImageCollection._record_stage_success(stage)¶
record stage success.
- Parameters:
stage – Input
stageconsumed by this implementation; its exact use is visible in the linked source below. No maintained parameter description is present in the original docstring.- Returns:
None (no explicit return statement).
ImageCollection._validate_phase_image_state¶
- ImageCollection._validate_phase_image_state()¶
validate phase image state.
Return expressions in source:
matchedExplicitly raised exceptions:
ValueError. Errors from called functions can also propagate or be recorded.
ImageCollection._normalize_channel_list¶
- ImageCollection._normalize_channel_list(channel_list, argument_name='channel_list')¶
normalize channel list.
- Parameters:
channel_list – Sequence of channel suffixes to load or attach.
argument_name – Input
argument_nameconsumed by this implementation; its exact use is visible in the linked source below. No maintained parameter description is present in the original docstring.
Return expressions in source:
normalized_channelsExplicitly raised exceptions:
ValueError,TypeError. Errors from called functions can also propagate or be recorded.
ImageCollection._iter_processing_targets¶
- ImageCollection._iter_processing_targets(object_list, phase_channel)¶
iter processing targets.
- Parameters:
object_list – Explicit image-object sequence to process; None selects collection targets.
phase_channel – TIFF suffix identifying the phase images, such as “C1”. An empty suffix is the signature default.
Return expressions in source:
[object_list] self.image_objects list(object_list)
Explicitly raised exceptions:
TypeError. Errors from called functions can also propagate or be recorded.
ImageCollection._get_mesh_dataframe_lookup¶
- ImageCollection._get_mesh_dataframe_lookup()¶
Build an image-name lookup from the current mesh dataframe.
Return expressions in source:
{image_name: group.reset_index(drop=True) for image_name, group in self.mesh_df_collection.groupby('image_name', sort=False)} None
View current source, line 266.
Original docstring (legacy wording may differ from the current signature)
Build an image-name lookup from the current mesh dataframe. Do not retain this lookup across calls: callers can replace or mutate ``mesh_df_collection``, and a cached lookup could then return stale meshes for newly loaded data.
ImageCollection._apply_curation_labels¶
- ImageCollection._apply_curation_labels()¶
Apply curation labels by stable image identity, with frame fallback.
- Returns:
None (no explicit return statement).
View current source, line 1154.
Original docstring (legacy wording may differ from the current signature)
Apply curation labels by stable image identity, with frame fallback.
ImageCollection._atomic_write¶
- ImageCollection._atomic_write(filename, writer)¶
atomic write.
- Parameters:
filename – Input
filenameconsumed by this implementation; its exact use is visible in the linked source below. No maintained parameter description is present in the original docstring.writer – Input
writerconsumed by this implementation; its exact use is visible in the linked source below. No maintained parameter description is present in the original docstring.
- Returns:
None (no explicit return statement).
Explicitly raised exceptions:
ValueError. Errors from called functions can also propagate or be recorded.
ImageCollection._to_parquet¶
- ImageCollection._to_parquet(filename, data, mesh_data=False)¶
to parquet.
- Parameters:
filename – Input
filenameconsumed by this implementation; its exact use is visible in the linked source below. No maintained parameter description is present in the original docstring.data – Input
dataconsumed by this implementation; its exact use is visible in the linked source below. No maintained parameter description is present in the original docstring.mesh_data – Input
mesh_dataconsumed by this implementation; its exact use is visible in the linked source below. No maintained parameter description is present in the original docstring.
- Returns:
None (no explicit return statement).
Explicitly raised exceptions:
ValueError. Errors from called functions can also propagate or be recorded.
ImageCollection._to_pickle¶
- ImageCollection._to_pickle(pkl_name, data)¶
Save data to a pkl file.
- Parameters:
pkl_name – Mesh input filename or pickle output name. For feature output, .pkl means exact filename; a suffixless name is a legacy tag.
data – Input
dataconsumed by this implementation; its exact use is visible in the linked source below. No maintained parameter description is present in the original docstring.
- Returns:
None (no explicit return statement).
View current source, line 1576.
Original docstring (legacy wording may differ from the current signature)
Save data to a pkl file.
ImageCollection._write_pickle_file¶
- ImageCollection._write_pickle_file(path, data)¶
write pickle file.
- Parameters:
path – Input
pathconsumed by this implementation; its exact use is visible in the linked source below. No maintained parameter description is present in the original docstring.data – Input
dataconsumed by this implementation; its exact use is visible in the linked source below. No maintained parameter description is present in the original docstring.
- Returns:
None (no explicit return statement).