API Reference¶

class CellViabilityProtocol:
    """
    A class to represent a cell viability analysis protocol.

    Attributes
    ----------
    config : dict
        A dictionary containing configuration for the protocol.
    name : str
        The name of the protocol.
    verbose : bool
        A flag to indicate whether to run in verbose mode.

    Methods
    -------
    _load_screening() -> Screening
        Loads and returns a Screening instance.
    execute()
        Executes the cell viability analysis protocol.
    """

    def __init__(self, config: dict, name: str, basedir: str = "results", verbose: bool = False) -> None:
        self.config: dict = config
        self.screen: Screen = self._load_screen(config, name)
        self.model: stardist.models.model2d.StarDist2D | None = None
        self.basedir: str = basedir
        self.verbose: bool = verbose

    # -------------------------------------------------------------------------
    # Loading and setup
    # -------------------------------------------------------------------------
    def _create_directories(self, plate: Plate, npy: bool = False, instances: bool = False) -> None:
        """
        Creates necessary directories for storing results.

        Parameters
        ----------
        plate : str
            The name of the plate.
        npy : bool, optional
            If True, creates a directory for .npy files, by default False.
        instances : bool, optional
            If True, creates a directory for instance segmentation masks, by default False.
        """
        platedir = os.path.join(self.basedir, self.screen.name, plate.name)
        os.makedirs(platedir, exist_ok=True)

        if instances:
            os.makedirs(os.path.join(platedir, "instances"), exist_ok=True)
        if npy:
            os.makedirs(os.path.join(platedir, "npy"), exist_ok=True)

    def _load_model(self, warmup: bool = True) -> stardist.models.model2d.StarDist2D:
        """
        Loads the pre-trained StarDist2D model for cell segmentation.

        Parameters
        ----------
        use_gpu : bool, optional
            Whether to use GPU for model inference, by default True.

        Returns
        -------
        StarDist2D
            The loaded StarDist2D model.
        """
        model: stardist.models.model2d.StarDist2D = stardist.models.StarDist2D.from_pretrained("2D_versatile_fluo")

        # Warm-up the model (optional, but can speed up first prediction)
        if warmup:
            for _ in range(10):
                _ = model.predict_instances(numpy.zeros((256, 256), dtype=numpy.float32))

        return model

    def _load_screen(self, config: dict, name: str) -> Screen:
        """
        Loads and returns a Screen instance.

        Parameters
        ----------
        config : dict
            A dictionary containing configuration for the screen.
        name : str
            The name of the screen.

        Returns
        -------
        Screen
            An instance of the Screen class.
        """
        return Screen(config, name)

    # -------------------------------------------------------------------------
    # Image processing and characterization
    # -------------------------------------------------------------------------
    def _segment(
        self,
        image: Image,
        channel: int = 0,
        sigma: float = 1.0,
        min_size: int = 0,
        max_size: int = 1000000,
    ) -> Image:
        """
        Segments the images to identify cells.

        Parameters
        ----------
        image : Image
            The image to segment.
        channel : int, optional
            The channel to process, by default 0.
        sigma : float, optional
            The standard deviation for Gaussian filtering, by default 1.0.
        min_size : int, optional
            The minimum object size (in pixels) to keep, by default 0.
        max_size : int, optional
            The maximum object size (in pixels) to keep, by default 1e6.

        Returns
        -------
        Image
            The segmented image.
        """
        img: numpy.ndarray = image.data[0, 0, channel, :, :]

        # Gaussian smoothing and normalization
        filtered: numpy.ndarray = skimage.filters.gaussian(img, sigma=sigma)

        # Instance segmentation using StarDist
        if self.model is not None:
            labels: numpy.ndarray
            labels, _ = self.model.predict_instances(normalize(filtered))

        if min_size > 0:
            labels = skimage.morphology.remove_small_objects(labels, min_size=int(min_size))

        if max_size < 1e6:
            labels = labels ^ skimage.morphology.remove_small_objects(labels, min_size=int(max_size))

        # Return the segmented image
        segmented = Image()
        segmented.upload(BioImage(labels))

        return segmented

    def _characterize(self, segmented: Image) -> pandas.DataFrame:
        """
        Counts and characterizes cells in the given image.

        Parameters
        ----------
        segmented : Image
            The segmented image to analyze.

        Returns
        -------
        pandas.DataFrame
            A DataFrame containing properties of the counted cells.
        """
        props = skimage.measure.regionprops_table(
            segmented.data[0, 0, 0, :, :],
            properties=[
                "label",
                "area",
                "perimeter",
                "eccentricity",
            ],
        )

        return pandas.DataFrame(props)

    def _analyze_well(self, plate: Plate, well: Well, parameters: dict, npy: bool, instances: bool) -> tuple:
        """
        Analyzes a single well in a plate.

        Parameters
        ----------
        plate : Plate
            The plate containing the well.
        well : Well
            The well to analyze.
        parameters : dict
            A dictionary containing analysis parameters.
        npy : bool
            If True, saves instance segmentation masks as .npy files.
        instances : bool
            If True, saves instance segmentation masks as .png files.

        Returns
        -------
        tuple
            A tuple containing the number of cells and their properties.
        """
        # Characterizations to be calculated
        ncells: int = 0
        properties: list[pandas.DataFrame] = []

        n = [] * len(well.images)
        for image in well.images:
            if self.verbose:
                print(f"{image.filename}", end=" ")

            # Pre-processing and Segmentation
            segmented: Image = self._segment(
                image,
                channel=parameters.get("channel", 0),
                sigma=parameters.get("sigma", 1.0),
                min_size=parameters.get("min_size", 0.0),
                max_size=parameters.get("max_size", 1e6),
            )

            # Basename for saving files
            if instances or npy:
                basename: str = os.path.splitext(os.path.basename(image.filename))[0]
            platedir = os.path.join(self.basedir, self.screen.name, plate.name)

            # Save .png file
            if instances:
                filename: str = os.path.join(platedir, "instances", f"{basename}.png")
                self._save_instances(image, segmented, filename)

            # Save .npy file
            if npy:
                filename = os.path.join(platedir, "npy", f"{basename}.npy")
                self._save_npy(segmented, filename)

            # Cell properties characterization
            props: pandas.DataFrame = self._characterize(segmented)
            props["screen"] = self.screen.name
            props["plate"] = plate.name
            props["well"] = well.name
            props["field"] = image.field
            properties.append(props)

            # Cell counting
            n.append(int(props["label"].count()))

        # Merge fields
        if parameters.get("merge", "sum") == "sum":
            ncells = sum(n)

        return ncells, pandas.concat(properties, ignore_index=True)

    def _analyze_plate(
        self, plate: Plate, parameters: dict, npy: bool, instances: bool
    ) -> tuple[pandas.DataFrame, pandas.DataFrame]:
        """
        Analyzes a single plate in the screening.

        Parameters
        ----------
        plate : Plate
            The plate to analyze.
        parameters : dict
            A dictionary containing analysis parameters.
        npy : bool
            If True, saves instance segmentation masks as .npy files.
        instances : bool
            If True, saves instance segmentation masks as .png files.

        Returns
        -------
        tuple[pandas.DataFrame, pandas.DataFrame]
            A tuple containing the number of cells and their properties.
        """
        # Characterizations to be calculated
        ncells: dict[str, int] = {}
        properties: list[pandas.DataFrame] = []

        for well in plate.wells:
            if self.verbose:
                print(f"> Analyzing well {well.name} ...")

            # Analyze the well
            ncells[well.name], props = self._analyze_well(plate, well, parameters, npy, instances)
            properties.append(props)

            if self.verbose:
                print("\n", end="", flush=True)

        # Convert cell counting to DataFrame
        df_ncells: pandas.DataFrame = (
            pandas.DataFrame.from_dict(ncells, orient="index", columns=["ncells"])
            .reset_index()
            .rename(columns={"index": "well"})
        )
        df_ncells.insert(0, "plate", plate.name)

        # Convert properties to DataFrame
        df_properties: pandas.DataFrame = pandas.concat(properties, ignore_index=True)

        return df_ncells, df_properties

    # -------------------------------------------------------------------------
    # Saving
    # -------------------------------------------------------------------------
    def _save_npy(self, image: Image, filename: str) -> None:
        """
        Saves the given image as a .npy file.

        Parameters
        ----------
        image : Image
            The image to save.
        filename : str
            The filename to save the .npy file.
        """
        numpy.save(filename, image.data)

    def _save_instances(self, image: Image, segmented: Image, filename: str) -> None:
        """
        Saves the instance segmentation mask as a .png file.

        Parameters
        ----------
        image : Image
            The original image.
        segmented : Image
            The segmented image to save.
        filename : str
            The filename to save the .png file.
        """
        # Get segmented channel
        channel = self.config["parameters"].get("channel", 0)

        plt.figure()
        plt.imshow(render_label(segmented.data[0, 0, 0, :, :], img=image.data[0, 0, channel, :, :]))
        plt.axis("off")
        plt.savefig(filename, bbox_inches="tight", pad_inches=0)
        plt.close()

    # -------------------------------------------------------------------------
    # Post-processing: Normalization (inCPE), Z-score and hit selecion
    # -------------------------------------------------------------------------
    def _zscore(self, ncells: pandas.DataFrame) -> float:
        """
        Applies Z-score normalization to the cell counting.

        Parameters
        ----------
        ncells : pandas.DataFrame
            The DataFrame containing cell counting.

        Returns
        -------
        float
            The Z-score value.

        Note
        ----
        Z-score formula: Z' = 1 - (3 * (sp + sn)) / |mp - mn|
        where sp and sn are the standard deviations of the positive and
        negative controls, and mp and mn are their means.
        """
        # Select positive and negative controls
        pos: pandas.Series = ncells.loc[ncells["well"].isin(self.config["controls"]["positive"]), "ncells"]
        neg: pandas.Series = ncells.loc[ncells["well"].isin(self.config["controls"]["negative"]), "ncells"]

        # Calculate Z-score for plate
        zscore: float = 1 - (3 * (pos.std() + neg.std())) / abs(pos.mean() - neg.mean())

        return zscore

    def _normalization(self, ncells: pandas.DataFrame) -> pandas.DataFrame:
        """
        Applies inCPE normalization to the cell counting.

        The inCPE (inhibition of cytopathic effect) is calculated as:

            inCPE = (Ncells - mean(Zpos)) / (mean(Zneg) - mean(Zpos))

        where:
            - Zpos: positive control wells (infected, untreated)
            - Zneg: negative control wells (non-infected, untreated)

        Parameters
        ----------
        ncells : pandas.DataFrame
            The DataFrame containing cell counts. Must include columns:
            'well' and 'ncells'.

        Returns
        -------
        pandas.DataFrame
            The DataFrame with an additional column 'inCPE'.
        """
        # Select positive and negative controls
        pos: pandas.Series = ncells.loc[ncells["well"].isin(self.config["controls"]["positive"]), "ncells"]
        neg: pandas.Series = ncells.loc[ncells["well"].isin(self.config["controls"]["negative"]), "ncells"]

        # Compute inCPE normalization
        ncells["inCPE"] = (ncells["ncells"] - pos.mean()) / (neg.mean() - pos.mean())

        return ncells

    def _filter_candidates(
        self,
        data: dict[str, pandas.DataFrame],
        zscore_per_plate: pandas.DataFrame,
        zscore: float = 0.5,
        incpe: float = 0.3,
    ) -> pandas.DataFrame:
        """
        Filters candidate hits based on Z-score and inCPE thresholds.

        Parameters
        ----------
        data : dict[str,pandas.DataFrame]
            The dictionary containing cell counting and inCPE values for each plate.
        zscore_per_plate : pandas.DataFrame
            The DataFrame containing Z-scores per plate.
        zscore : float, optional
            The Z-score threshold for hit selection, by default 0.5.
        incpe : float, optional
            The inCPE threshold for hit selection, by default 0.3.

        Returns
        -------
        pandas.DataFrame
            A DataFrame containing the filtered candidate hits.
        """
        # Get approved plates based on Z-score
        approved: list[str] = zscore_per_plate.loc[zscore_per_plate["zscore"] >= zscore, "plate"].tolist()

        # Filter hits based on inCPE and approved plates
        hits: pandas.DataFrame = pandas.DataFrame()
        for plate in approved:
            # Get all data from approved plate
            plate_data: pandas.DataFrame = data[plate]

            # Remove controls from data
            plate_data = plate_data.loc[
                ~plate_data["well"].isin(self.config["controls"]["negative"])
                & ~plate_data["well"].isin(self.config["controls"]["positive"])
            ]

            # Select hits based on incpe
            plate_hits = plate_data[plate_data["inCPE"] >= incpe]
            hits = pandas.concat([hits, plate_hits], ignore_index=True)

        # Print approval rate
        print(f"> Approved plates: {len(approved)} ({(len(approved) / len(data)) * 100:.2f}%)")

        # Print number of hits
        print(f"> Number of hits: {len(hits)}")

        return hits

    # -------------------------------------------------------------------------
    # Execution
    # -------------------------------------------------------------------------
    def execute(
        self, npy: bool = False, instances: bool = False
    ) -> tuple[pandas.DataFrame, pandas.DataFrame, dict[str, pandas.DataFrame], dict[str, pandas.DataFrame]]:
        """
        Executes the cell viability analysis protocol.

        Parameters
        ----------
        npy : bool, optional
            If True, saves instance segmentation masks as .npy files, by default False.
        instances : bool, optional
            If True, saves instance segmentation masks as .png files, by default False.

        Returns
        -------
        pandas.DataFrame
            A DataFrame containing the filtered candidate hits.
        pandas.DataFrame
            A DataFrame containing Z-scores for all plates.
        dict[str, pandas.DataFrame]
            A dictionary with plate names as keys and their corresponding
            analysis results as pandas DataFrames.
        dict[str, pandas.DataFrame]
            A dictionary with plate names as keys and their corresponding
            morphology properties as pandas DataFrames.

        Notes
        -----
        The method processes each plate in the screening, analyzes each well,
        and applies the specified cell viability analysis protocol.
        """
        # Load the model if not already loaded
        if self.model is None:
            print("> Loading StarDist model ...")
            self.model = self._load_model(warmup=True)

        # Initialize ncells and morphology dictionary
        ncells: dict[str, pandas.DataFrame] = {}
        morphology: dict[str, pandas.DataFrame] = {}
        zscore: dict[str, float] = {}

        # Iterate over plates, wells, and images
        for plate in self.screen.plates:
            if self.verbose:
                print(f"> Analyzing plate {plate.name} ...")

            # Create directories for the plate
            self._create_directories(plate=plate, instances=instances, npy=npy)

            # Analyze the plate
            ncells[plate.name], properties = self._analyze_plate(
                plate=plate, parameters=self.config["parameters"], npy=npy, instances=instances
            )
            morphology[plate.name] = properties

            # Analyze zcore for the plate
            zscore[plate.name] = self._zscore(ncells[plate.name])

            # Save status file
            with open(os.path.join(self.basedir, self.screen.name, plate.name, "status"), "w") as f:
                if zscore[plate.name] >= 0.5:
                    f.write("SUCCESS")
                else:
                    print(f"Warning: Z-score {zscore[plate.name]:.2f} is below the cutoff of 0.5.")
                    f.write("FAILED")

            # Normalization (inCPE)
            ncells[plate.name] = self._normalization(ncells[plate.name])

            # Plate map visualization
            plate_map(
                filename=os.path.join(self.basedir, self.screen.name, plate.name, "ncells.html"),
                data=ncells[plate.name],
                colname="ncells",
                controls=self.config["controls"],
            )
            plate_map(
                filename=os.path.join(self.basedir, self.screen.name, plate.name, "inCPE.html"),
                data=ncells[plate.name],
                colname="inCPE",
                controls=self.config["controls"],
            )

            # Save morphology as Excel file
            morphology[plate.name].to_csv(
                f"{self.basedir}/{self.screen.name}/{plate.name}/morphology.csv.gz", index=False, compression="gzip"
            )

        # Combine all z-scores into a DataFrame
        zscore_per_plate = pandas.DataFrame(list(zscore.items()), columns=["plate", "zscore"])

        # Filter hits
        hits: pandas.DataFrame = self._filter_candidates(
            ncells,
            zscore_per_plate,
            zscore=self.config["filter"].get("zscore", 0.5),
            incpe=self.config["filter"].get("zscore", 0.3),
        )

        # Save ncells as multi-sheet Excel file
        with pandas.ExcelWriter(f"{self.basedir}/{self.screen.name}/summary.xlsx", engine="openpyxl") as writer:
            zscore_per_plate.to_excel(writer, sheet_name="Z-score", index=False)
            for plate in self.screen.plates:
                ncells[plate.name].to_excel(writer, sheet_name=plate.name, index=False)

        # Save hits to Excel file
        with pandas.ExcelWriter(f"{self.basedir}/{self.screen.name}/hits.xlsx", engine="openpyxl") as writer:
            hits.to_excel(writer, sheet_name="Hits", index=False)

        # Unload model from memory
        self.model = None

        return hits, zscore_per_plate, ncells, morphology

class Image:
    """This class is used for an image of a well.

    Attributes
    ----------
    _image : BioImage | None
        The BioImage object representing the image.
    filename : str | None
        The path to the image file.
    image : BioImage
        The BioImage object representing the image.
    """

    def __init__(self) -> None:
        """
        Initialize the Image object.
        """
        self.field: int | None = None
        self.filename: str | None = None
        self._image: BioImage | None = None

    def __str__(self) -> str:
        return f"<CellViability.screening.image.Image `{self.filename}` object at {hex(id(self))}>"

    def __repr__(self) -> str:
        return f"<CellViability.screening.image.Image `{self.filename}` object at {hex(id(self))}>"

    def lazyload(self, field: int, filename: str) -> "Image":
        """
        Lazily load image metadata (field and filename) without loading the image data.

        Parameters
        ----------
        field : int
            The field number (must be positive).
        filename : str
            Path to the image file.

        Raises
        ------
        FileNotFoundError
            If the image file is not found.
        ValueError
            If the field number is not positive.
        ValueError
            If the filename is not a valid string.
        """
        if not isinstance(field, int) or field < 1:
            raise ValueError("Field number must be a positive integer.")
        if not isinstance(filename, str) or not filename:
            raise ValueError("Filename must be a non-empty string.")
        if not os.path.exists(filename):
            raise FileNotFoundError(f"Image '{filename}' not found.")

        self.field = field
        self.filename = filename
        self._image = None

        return self

    def upload(self, image: BioImage) -> None:
        """
        Upload an image to this object.

        Parameters
        ----------
        image : BioImage
            The image to be saved.
        """
        self._image = image
        self.field = None
        self.filename = None

    @property
    def data(self) -> numpy.ndarray:
        """Return the image data as a numpy array.

        Returns
        -------
        numpy.ndarray
            The image data as a numpy array.
        """
        if self._image is None:
            if self.filename is None:
                raise ValueError("No image loaded or filename provided.")
            self._image = BioImage(self.filename)
        return self._image.data

    @property
    def image(self) -> BioImage:
        """Return the BioImage object.

        Returns
        -------
        BioImage
            The BioImage object representing the image.
        """
        if self._image is None:
            if self.filename is None:
                raise ValueError("No image loaded or filename provided.")
            self._image = BioImage(self.filename)
        return self._image

class Plate:
    """This class is used for a plate in a screening experiment.

    Attributes
    ----------
    datadir : str
        The directory where the plate data is stored.
    name : str
        The name of the plate.
    wells : list of Well
        The list of wells in the plate.
    """

    def __init__(self, config: dict, name: str, datadir: str):
        """
        Initialize the Plate object.

        Parameters
        ----------
        config : dict
            The configuration dictionary.
        name : str
            The name of the plate.
        datadir : str
            Path to the directory containing plate images.

        Raises
        ------
        ValueError
            If the data directory is not found.
        ValueError
            If the number of wells does not match the expected number from config.
        """
        # Process plate name
        self.name: str = name

        # Get data directory from the configuration
        if not os.path.exists(datadir):
            raise ValueError(f"Data directory '{datadir}' not found in the configuration.")
        self.datadir: str = datadir

        # Load wells
        self.wells: list[Well] = self._load_wells(config)

        # Check if number of wells matches expected number from config
        if len(self.wells) != config.get("wells"):
            raise ValueError(
                f"Number of wells in plate '{self.name}' ({len(self.wells)}) does not match expected number ({config.get('wells')})."
            )

    def __str__(self) -> str:
        return f"<CellViability.screening.plate.Plate `{self.name}` object at {hex(id(self))}>"

    def __repr__(self) -> str:
        return f"<CellViability.screening.plate.Plate `{self.name}` object at {hex(id(self))}>"

    def _load_wells(self, config: dict) -> list[Well]:
        """
        Load wells from the plate configuration.

        Parameters
        ----------
        config : dict
            The configuration dictionary.

        Returns
        -------
        list[Well]
            The list of wells in the plate.
        """
        raw: dict[str, list[str]] = {}

        # Get files in datadir
        for filename in sorted(os.listdir(self.datadir)):
            if filename.endswith(".tif"):
                # Get metadata from filename
                # Columbus 2.4.0.104236 build format
                # Example: '001001-1-001001001.tif
                row, column, _, _ = _get_metadata_from_filename(filename)
                well: str = f"{row}{column:02d}"

                # Group images by well
                raw.setdefault(well, []).append(os.path.join(self.datadir, filename))

        # Sort wells by row and column
        sorted_wells: list[str] = sorted(raw.keys(), key=well_sort)

        # Load wells in sorted order
        wells: list[Well] = [Well(config, wellname, raw[wellname]) for wellname in sorted_wells]

        return wells

    def well(self, name: str) -> Well:
        """Return a well object.

        Parameters
        ----------
        name : str
            The name of the well. Examples: 'A01', 'B12', etc.

        Returns
        -------
        Well
            The well object.
        """
        # Check if well is loaded
        if len(self.wells) == 0:
            raise ValueError("Wells not loaded. Please load wells first.")

        # Check if well index is out of bounds
        if name not in [well.name for well in self.wells]:
            raise ValueError(f"Well {name} does not exist in plate.")

        # Get index of well in wells
        idx: int = [well.name for well in self.wells].index(name)

        return self.wells[idx]

class Screen:
    """This class is used for a screen .

    Attributes
    ----------
    datadir : str
        The directory where the screening data is stored.
    name : str
        The name of the screening.
    plates : list[Plate]
        The list of plates in the screening.
    """

    def __init__(self, config: dict, name: str):
        """
        Initialize the Screen object.

        Parameters
        ----------
        config : dict
            The configuration dictionary.
        name : str
            The name of the screening.

        Raises
        ------
        ValueError
            If the data directory is not found in the configuration.
        ValueError
            If the data directory does not exist.
        """
        # Get screen name
        self.name: str = name

        # Get data directory from the configuration
        datadir: str | None = config.get("datadir")
        if datadir is None:
            raise ValueError("Data directory not found in the configuration.")
        elif not os.path.exists(datadir):
            raise ValueError(f"Data directory '{datadir}' does not exist.")
        else:
            self.datadir: str = datadir

        # Load plates from the experiment configuration
        self.plates: list[Plate] = self._load_plates(config)

    def __str__(self) -> str:
        return f"<CellViability.screening.Screen `{self.name}` object at {hex(id(self))}>"

    def __repr__(self) -> str:
        return f"<CellViability.screening.Screen `{self.name}` object at {hex(id(self))}>"

    def _load_plates(self, config: dict) -> list[Plate]:
        """
        Load plates from the experiment configuration.

        Parameters
        ----------
        config : dict
            The configuration dictionary.

        Returns
        -------
        list[Plate]
            The list of plates in the screening.
        """
        plates: list[Plate] = []

        platenames: list[str] = config.get("plates", [])
        for platename in platenames:
            # Get the data directory for the plate
            path: str = os.path.join(self.datadir, platename)

            # Create a Plate object and add it to the list
            plates.append(Plate(config, platename, path))

        return plates

    def plate(self, idx: int | str) -> Plate:
        """
        Return a plate object from plates attributes.

        Parameters
        ----------
        idx : int | str
            Index or name of the plate in plates attributes.
        """
        # Check if plate index is out of bounds
        if isinstance(idx, int):
            if idx < 0 or idx >= len(self.plates):
                raise ValueError(f"Plate index '{idx}' out of bounds.")
            return self.plates[idx]
        elif isinstance(idx, str):
            for plate in self.plates:
                if plate.name == idx:
                    return plate
            raise ValueError(f"Plate name '{idx}' not found.")

class Well:
    """This class is used for a well in a plate.

    Attributes
    ----------
    images : list[Image]
        The list of images in the well.
    name : str
        The name of the well.
    """

    def __init__(self, config: dict, name: str, filenames: list[str]):
        """
        Initialize the Well object.

        Parameters
        ----------
        config : dict
            The configuration dictionary.
        name : str
            The name of the well.
        filenames : List[str]
            List of paths to the images in the well.

        Raises
        ------
        ValueError
            If the number of images does not match the expected number from config.
        """
        # Process well name
        self.name: str = name

        # Load images
        self.images: list[Image] = self._load_images(filenames)

        # Check if number of images matches expected number from config
        if len(self.images) != config.get("fields"):
            raise ValueError(
                f"Number of images in well '{self.name}' ({len(self.images)}) does not match expected number ({config.get('fields')})."
            )

    def __str__(self) -> str:
        return f"<CellViability.screening.well.Well `{self.name}` object at {hex(id(self))}>"

    def __repr__(self) -> str:
        return f"<CellViability.screening.well.Well `{self.name}` object at {hex(id(self))}>"

    def _load_images(self, filenames: list[str]) -> list[Image]:
        """
        Load images from the well configuration.

        Parameters
        ----------
        filenames : list[str]
            List of paths to the images in the well.

        Returns
        -------
        list[Image]
            The list of images in the well.
        """
        # Load images from the well configuration
        images = []
        for filename in sorted(filenames):
            # Get metadata from filename
            # Columbus 2.4.0.104236 build format
            # Example: '001001-1-001001001.tif
            _, _, field, _ = _get_metadata_from_filename(filename)

            # Sort images by field
            images.append((field, filename))

        # Sort images by field number
        images.sort(key=lambda x: x[0])

        return [Image().lazyload(field, filename) for field, filename in images]

    def image(self, field: int) -> Image:
        """Return an image object.

        Parameters
        ----------
        field : int
            The field number. Examples: 1, 2, 3, etc.

        Returns
        -------
        Image
            The image object.

        Raises
        ------
        ValueError
            If images are not loaded or field does not exist.

        """
        # Check if well is loaded
        if len(self.images) == 0:
            raise ValueError("Images not loaded. Please load images first.")

        # Check if well index is out of bounds
        if field not in [image.field for image in self.images]:
            raise ValueError(f"Field #{field} does not exist in plate.")

        # Get index of well in wells
        idx = [image.field for image in self.images].index(field)

        return self.images[idx]