classification package

classification_tools

towbintools.classification.qc_tools.compute_qc_features(mask: str | ndarray, image: str | ndarray | None, features: list[str] | None = None, channels: list[int] | None = None) → DataFrame | None[source]

Compute quality-control features from a mask and an optional intensity image.

Accepts file paths or NumPy arrays for both mask and image. Computes scikit-image region properties for the largest foreground object, plus a normalized-variance focus measure when an intensity image is provided.

Parameters:

  • mask (str or np.ndarray) – Binary mask (path to TIFF or array). Pixels > 0 are treated as foreground.

  • image (str, np.ndarray, or None) – Intensity image (path to TIFF, array, or None for mask-only features).

  • features (list[str], optional) – Region-property names to compute. If None, all properties returned by get_all_skimage_regionprops() are used. (default: None)

  • channels (list[int], optional) – Channel indices to load when image is a file path. (default: None)

Returns:

DataFrame of computed features, or None if the

mask is empty or an error occurs during extraction.

Return type:

pd.DataFrame or None

towbintools.classification.qc_tools.get_all_skimage_regionprops(mask_only: bool = False) → list[str][source]

Return all available scikit-image region-property names.

Excludes image-array and coordinates properties. When mask_only is True, intensity-based properties are also excluded so that the result can be used on masks without an intensity image.

Parameters:

mask_only (bool, optional) – If True, omit intensity-based properties (e.g. intensity_mean, moments_weighted). (default: False)

Returns:

Names of the available region properties.

Return type:

list[str]

towbintools.classification.classification_tools.classify_image(image: ndarray, features_function: Callable, classifier: XGBClassifier, classes: list, **kwargs) → str[source]

Classify an image based on features extracted by a provided function.

Parameters:

  • image (np.ndarray) – The image (or array of images) to classify.

  • features_function (callable) – A function that extracts a feature vector from image; called as features_function(image, **kwargs).

  • classifier (xgboost.XGBClassifier) – Trained XGBoost classifier.

  • classes (list) – Ordered list of class labels matching the classifier’s output columns (e.g. ["egg", "worm", "error"]).

  • **kwargs – Additional keyword arguments forwarded to features_function.

Returns:

The predicted class label (element of classes).

Return type:

str

towbintools.classification.classification_tools.classify_labels(mask: ndarray, image: ndarray, classifier: XGBClassifier, all_features: list[str], extra_properties: list, intensity_features: list[str], extra_intensity_features: list, num_closest: int | None = None, patches: list[int] | None = None, parallel: bool = True, n_jobs: int = -1, is_zstack: bool = False, confidence_threshold: float | None = None) → list[source]

Compute the features of all the labels in a mask and classify them using an XGBoost classifier.

Parameters:

  • mask (np.ndarray) – The mask of all regions.

  • image (np.ndarray) – The intensity image.

  • classifier (xgboost.XGBClassifier) – The trained classifier object.

  • all_features (list) – The list of features to compute.

  • extra_properties (list) – The list of extra properties to compute.

  • intensity_features (list) – The list of intensity features to compute.

  • extra_intensity_features (list) – The list of extra intensity features to compute.

  • num_closest (int) – The number of closest regions to consider.

  • patches (list) – The list of patch sizes to consider.

  • parallel (bool) – Whether to compute features in parallel.

  • n_jobs (int) – The number of jobs to run in parallel.

  • is_zstack (bool) – Whether the image is a z-stack.

  • confidence_threshold (float) – The confidence threshold for predictions to be considered valid.

Returns:

A list of predicted classes for all labels in the mask.

Return type:

list

towbintools.classification.classification_tools.classify_labels_and_convert_to_dataframe(mask: ndarray, image: ndarray, classifier: XGBClassifier, all_features: list[str], extra_properties: list, intensity_features: list[str], extra_intensity_features: list, num_closest: int | None = None, patches: list[int] | None = None, parallel: bool = True, n_jobs: int = -1, is_zstack: bool = False, confidence_threshold: float | None = None) → DataFrame[source]

Classify all the labels in a mask using an XGBoost classifier and convert the classification to a pandas DataFrame.

Parameters:

  • mask (np.ndarray) – The mask of all regions.

  • image (np.ndarray) – The intensity image.

  • classifier (xgboost.XGBClassifier) – The trained classifier object.

  • all_features (list) – The list of features to compute.

  • extra_properties (list) – The list of extra properties to compute.

  • intensity_features (list) – The list of intensity features to compute.

  • extra_intensity_features (list) – The list of extra intensity features to compute.

  • num_closest (int) – The number of closest regions to consider.

  • patches (list) – The list of patch sizes to consider.

  • parallel (bool) – Whether to compute features in parallel.

  • n_jobs (int) – The number of jobs to run in parallel.

  • is_zstack (bool) – Whether the image is a z-stack.

  • confidence_threshold (float) – The confidence threshold for predictions to be considered valid.

Returns:

A DataFrame with columns “Plane”, “Label”, and “Class”.

Return type:

pd.DataFrame

towbintools.classification.classification_tools.classify_labels_and_convert_to_dataframe_features_dict(mask: ndarray, image: ndarray, clf: XGBClassifier, features_dict: dict, parallel: bool = True, n_jobs: int = -1, is_zstack: bool = False, confidence_threshold: float | None = None) → DataFrame[source]

Classify all labels using a features dictionary and return the result as a DataFrame.

Combines classify_labels_features_dict() and convert_classification_to_dataframe().

Parameters:

  • mask (np.ndarray) – Labeled mask of all regions.

  • image (np.ndarray) – Intensity image.

  • clf (xgboost.XGBClassifier) – Trained XGBoost classifier.

  • features_dict (dict) – Feature configuration dictionary (see classify_labels_features_dict()).

  • parallel (bool, optional) – Whether to compute features in parallel. (default: True)

  • n_jobs (int, optional) – Number of parallel jobs. (default: -1)

  • is_zstack (bool, optional) – Whether the image is a z-stack. (default: False)

  • confidence_threshold (float, optional) – Minimum prediction confidence. (default: None)

Returns:

DataFrame with columns "Plane", "Label", and "Class".

Return type:

pd.DataFrame

towbintools.classification.classification_tools.classify_labels_and_convert_to_mask(mask: ndarray, image: ndarray, classifier: XGBClassifier, all_features: list[str], extra_properties: list, intensity_features: list[str], extra_intensity_features: list, num_closest: int | None = None, patches: list[int] | None = None, parallel: bool = True, n_jobs: int = -1, is_zstack: bool = False, confidence_threshold: float | None = None) → ndarray[source]

Classify all the labels in a mask using an XGBoost classifier and convert the classification to a mask.

Parameters:

  • mask (np.ndarray) – The mask of all regions.

  • image (np.ndarray) – The intensity image.

  • classifier (xgboost.XGBClassifier) – The trained classifier object.

  • all_features (list) – The list of features to compute.

  • extra_properties (list) – The list of extra properties to compute.

  • intensity_features (list) – The list of intensity features to compute.

  • extra_intensity_features (list) – The list of extra intensity features to compute.

  • num_closest (int) – The number of closest regions to consider.

  • patches (list) – The list of patch sizes to consider.

  • parallel (bool) – Whether to compute features in parallel.

  • n_jobs (int) – The number of jobs to run in parallel.

  • is_zstack (bool) – Whether the image is a z-stack.

  • confidence_threshold (float) – The confidence threshold for predictions to be considered valid.

Returns:

The given mask with pixel values replaced with class number + 1.

Return type:

np.ndarray

towbintools.classification.classification_tools.classify_labels_and_convert_to_mask_features_dict(mask: ndarray, image: ndarray, clf: XGBClassifier, features_dict: dict, parallel: bool = True, n_jobs: int = -1, is_zstack: bool = False, confidence_threshold: float | None = None) → ndarray[source]

Classify all labels using a features dictionary and return the result as a mask.

Combines classify_labels_features_dict() and convert_classification_to_mask().

Parameters:

  • mask (np.ndarray) – Labeled mask of all regions.

  • image (np.ndarray) – Intensity image.

  • clf (xgboost.XGBClassifier) – Trained XGBoost classifier.

  • features_dict (dict) – Feature configuration dictionary (see classify_labels_features_dict()).

  • parallel (bool, optional) – Whether to compute features in parallel. (default: True)

  • n_jobs (int, optional) – Number of parallel jobs. (default: -1)

  • is_zstack (bool, optional) – Whether the image is a z-stack. (default: False)

  • confidence_threshold (float, optional) – Minimum prediction confidence. (default: None)

Returns:

Mask with pixel values replaced by predicted class index + 1.

Return type:

np.ndarray

towbintools.classification.classification_tools.classify_labels_features_dict(mask: ndarray, image: ndarray, clf: XGBClassifier, features_dict: dict, parallel: bool = True, n_jobs: int = -1, is_zstack: bool = False, confidence_threshold: float | None = None) → list[source]

Classify all labels in a mask using a features dictionary.

Convenience wrapper around classify_labels() that unpacks feature configuration from a dictionary rather than requiring individual arguments.

Parameters:

  • mask (np.ndarray) – Labeled mask of all regions.

  • image (np.ndarray) – Intensity image.

  • clf (xgboost.XGBClassifier) – Trained XGBoost classifier.

  • features_dict (dict) – Dictionary with keys "all_features", "extra_properties", "intensity_features", "extra_intensity_features", "num_closest", and "patches".

  • parallel (bool, optional) – Whether to compute features in parallel. (default: True)

  • n_jobs (int, optional) – Number of parallel jobs (passed to joblib). (default: -1)

  • is_zstack (bool, optional) – Whether the image is a z-stack. (default: False)

  • confidence_threshold (float, optional) – Minimum prediction confidence; predictions below this threshold are set to -1. (default: None)

Returns:

Predicted class indices for all labels, structured as returned by

classify_labels().

Return type:

list

towbintools.classification.classification_tools.classify_plane(mask_plane: ndarray, image_plane: ndarray, classifier: XGBClassifier, all_features: list[str], extra_properties: list, intensity_features: list[str], extra_intensity_features: list, num_closest: int | None = None, patches: list[int] | None = None, parallel: bool = True, n_jobs: int = -1, confidence_threshold: float | None = None) → ndarray | None[source]

Compute the features of all the labels in a plane and classify them using an XGBoost classifier.

Parameters:

  • mask_plane (np.ndarray) – The mask of all regions.

  • image_plane (np.ndarray) – The intensity image.

  • classifier (xgboost.XGBClassifier) – The trained classifier object.

  • all_features (list) – The list of features to compute.

  • extra_properties (list) – The list of extra properties to compute.

  • intensity_features (list) – The list of intensity features to compute.

  • extra_intensity_features (list) – The list of extra intensity features to compute.

  • num_closest (int) – The number of closest regions to consider.

  • patches (list) – The list of patch sizes to consider.

  • parallel (bool) – Whether to compute features in parallel.

  • n_jobs (int) – The number of jobs to run in parallel.

  • confidence_threshold (float) – The confidence threshold for predictions to be considered valid.

Returns:

A list of predicted classes for all labels in the plane.

Return type:

list

towbintools.classification.classification_tools.compute_features_of_label(current_label: int, mask_plane: ndarray, image_plane: ndarray, all_features: list[str], extra_properties: list, intensity_features: list[str], extra_intensity_features: list, num_closest: int | None = None, patches: list[int] | None = None) → list[source]

Compute a set of features for a single label, including context features and patch features.

Parameters:

  • current_label (int) – The label of the current region.

  • mask_plane (np.ndarray) – The mask of all regions.

  • image_plane (np.ndarray) – The intensity image.

  • all_features (list) – The list of features to compute.

  • extra_properties (list) – The list of extra properties to compute.

  • intensity_features (list) – The list of intensity features to compute.

  • extra_intensity_features (list) – The list of extra intensity features to compute.

  • num_closest (int) – The number of closest regions to consider.

  • patches (list) – The list of patch sizes to consider.

Returns:

A list of features for the label.

Return type:

list

towbintools.classification.classification_tools.compute_features_of_plane(mask_plane: ndarray, image_plane: ndarray, all_features: list[str], extra_properties: list, intensity_features: list[str], extra_intensity_features: list, num_closest: int | None = None, patches: list[int] | None = None, parallel: bool = True, n_jobs: int = -1) → list[source]

Compute a set of features for a single label, including context features and patch features for all labels in a plane.

Parameters:

  • mask_plane (np.ndarray) – The mask of all regions.

  • image_plane (np.ndarray) – The intensity image.

  • all_features (list) – The list of features to compute.

  • extra_properties (list) – The list of extra properties to compute.

  • intensity_features (list) – The list of intensity features to compute.

  • extra_intensity_features (list) – The list of extra intensity features to compute.

  • num_closest (int) – The number of closest regions to consider.

  • patches (list) – The list of patch sizes to consider.

  • parallel (bool) – Whether to compute features in parallel.

  • n_jobs (int) – The number of jobs to run in parallel.

Returns:

A list of lists of features for all labels.

Return type:

list

towbintools.classification.classification_tools.convert_classification_to_dataframe(mask: ndarray, classification: list, is_zstack: bool = False) → DataFrame[source]

Convert a classification (list of predicted classes) to a pandas DataFrame.

Parameters:

  • mask (np.ndarray) – The mask of all regions.

  • classification (list) – The list of predicted classes for all labels.

  • is_zstack (bool) – Whether the image is a z-stack.

Returns:

A DataFrame with columns “Plane”, “Label”, and “Class”.

Return type:

pd.DataFrame

towbintools.classification.classification_tools.convert_classification_to_mask(mask: ndarray, classification: list, is_zstack: bool = False) → ndarray[source]

Convert a classification (list of predicted classes) to a mask.

Parameters:

  • mask (np.ndarray) – The mask of all regions.

  • classification (list) – The list of predicted classes for all labels.

  • is_zstack (bool) – Whether the image is a z-stack.

Returns:

The given mask with pixel values replaced with class number + 1.

Return type:

np.ndarray