Plots API

Description

A plot represents an arbitrary area within a field. Each plot is uniquely identified by its associated Experiment, Season, and Site, and can optionally reference an Accession and Population.

It is defined by the following properties:

Property	Type	Description
id	UUID	The unique identifier of the plot.
plot_number	int	The number of the plot.
plot_row_number	int	The row number of the plot.
plot_column_number	int	The column number of the plot.
plot_geometry_info	dict	Geometry information about the plot.
plot_info	dict	Additional information about the plot.
experiment_id	UUID	The ID of the associated experiment.
season_id	UUID	The ID of the associated season.
site_id	UUID	The ID of the associated site.
accession_id	UUID	The ID of the associated accession.
population_id	UUID	The ID of the associated population.
experiment_name	str	The name of the associated experiment.
season_name	str	The name of the associated season.
site_name	str	The name of the associated site.

Module

This module defines the Plot class, which represents a plot entity, including its metadata, associations to experiments, seasons, sites, accessions, and populations, and related operations.

It includes methods for creating, retrieving, updating, and deleting plots, as well as methods for checking existence, searching, and managing associations with experiments, seasons, sites, accessions, and populations.

This module includes the following methods:

• exists: Check if a plot with the given parameters exists.
• create: Create a new plot.
• get: Retrieve a plot by its parameters.
• get_by_id: Retrieve a plot by its ID.
• get_all: Retrieve all plots.
• search: Search for plots based on various criteria.
• update: Update the details of a plot.
• delete: Delete a plot.
• refresh: Refresh the plot's data from the database.
• get_info: Get the additional information of the plot.
• set_info: Set the additional information of the plot.
• Association methods for experiments, seasons, sites, accessions, and populations.

Plot

Bases: APIBase

Represents a plot entity, including its metadata, associations to experiments, seasons, sites, accessions, and populations, and related operations.

Attributes:

Name	Type	Description
id	Optional[ID]	The unique identifier of the plot.
plot_number	int	The number of the plot.
plot_row_number	int	The row number of the plot.
plot_column_number	int	The column number of the plot.
plot_geometry_info	Optional[dict]	Geometry information about the plot.
plot_info	Optional[dict]	Additional information about the plot.
experiment_id	Optional[ID]	The ID of the associated experiment.
season_id	Optional[ID]	The ID of the associated season.
site_id	Optional[ID]	The ID of the associated site.
experiment_name	Optional[str]	The name of the associated experiment.
season_name	Optional[str]	The name of the associated season.
site_name	Optional[str]	The name of the associated site.

Source code in gemini/api/plot.py

class Plot(APIBase):
    """
    Represents a plot entity, including its metadata, associations to experiments, seasons, sites, accessions, and populations, and related operations.

    Attributes:
        id (Optional[ID]): The unique identifier of the plot.
        plot_number (int): The number of the plot.
        plot_row_number (int): The row number of the plot.
        plot_column_number (int): The column number of the plot.
        plot_geometry_info (Optional[dict]): Geometry information about the plot.
        plot_info (Optional[dict]): Additional information about the plot.
        experiment_id (Optional[ID]): The ID of the associated experiment.
        season_id (Optional[ID]): The ID of the associated season.
        site_id (Optional[ID]): The ID of the associated site.
        experiment_name (Optional[str]): The name of the associated experiment.
        season_name (Optional[str]): The name of the associated season.
        site_name (Optional[str]): The name of the associated site.
    """

    id: Optional[ID] = Field(None, validation_alias=AliasChoices("id", "plot_id"))
    plot_number: int
    plot_row_number: int
    plot_column_number: int
    plot_geometry_info: Optional[dict] = None
    plot_info: Optional[dict] = None
    experiment_id: Optional[ID] = None
    season_id: Optional[ID] = None
    site_id: Optional[ID] = None
    accession_id: Optional[ID] = None
    population_id: Optional[ID] = None

    experiment_name: Optional[str] = Field(None, exclude=True)
    season_name: Optional[str] = Field(None, exclude=True)
    site_name: Optional[str] = Field(None, exclude=True)
    accession_name: Optional[str] = Field(None, exclude=True)
    population_name: Optional[str] = Field(None, exclude=True)

    def __str__(self):
        """Return a string representation of the Plot object."""
        return f"Plot(plot_number={self.plot_number}, plot_row_number={self.plot_row_number}, plot_column_number={self.plot_column_number}, id={self.id})"

    def __repr__(self):
        """Return a detailed string representation of the Plot object."""
        return f"Plot(plot_number={self.plot_number}, plot_row_number={self.plot_row_number}, plot_column_number={self.plot_column_number}, id={self.id})"

    @classmethod
    def exists(
        cls,
        plot_number: int,
        plot_row_number: int,
        plot_column_number: int,
        experiment_name: str = None,
        season_name: str = None,
        site_name: str = None
    ) -> bool:
        """
        Check if a plot with the given parameters exists.

        Examples:
            >>> Plot.exists(plot_number=1, plot_row_number=2, plot_column_number=3)
            True
            >>> Plot.exists(plot_number=1, plot_row_number=2, plot_column_number=3, experiment_name="Experiment 1")
            False

        Args:
            plot_number (int): The plot number.
            plot_row_number (int): The row number of the plot.
            plot_column_number (int): The column number of the plot.
            experiment_name (str, optional): The name of the experiment. Defaults to None.
            season_name (str, optional): The name of the season. Defaults to None.
            site_name (str, optional): The name of the site. Defaults to None.
        Returns:
            bool: True if the plot exists, False otherwise.
        """
        try:
            exists = PlotViewModel.exists(
                plot_number=plot_number,
                plot_row_number=plot_row_number,
                plot_column_number=plot_column_number,
                experiment_name=experiment_name,
                season_name=season_name,
                site_name=site_name
            )
            return exists
        except Exception as e:
            logger.error(f"Error checking existence of plot: {e}")
            return False

    @classmethod
    def create(
        cls,
        plot_number: int,
        plot_row_number: int,
        plot_column_number: int,
        plot_info: dict = None,
        plot_geometry_info: dict = None,
        experiment_name: str = None,
        season_name: str = None,
        site_name: str = None,
        accession_name: str = None,
        population_name: str = None,
    ) -> Optional["Plot"]:
        try:
            from gemini.api.accession import Accession
            from gemini.api.population import Population
            from gemini.api.experiment import Experiment
            from gemini.api.season import Season
            from gemini.api.site import Site

            experiment_id = None
            season_id = None
            site_id = None
            accession_id = None
            population_id = None

            if experiment_name:
                exp = Experiment.get(experiment_name=experiment_name)
                if exp:
                    experiment_id = exp.id
            if season_name and experiment_name:
                sea = Season.get(season_name=season_name, experiment_name=experiment_name)
                if sea:
                    season_id = sea.id
            if site_name:
                sit = Site.get(site_name=site_name)
                if sit:
                    site_id = sit.id
            if accession_name:
                acc = Accession.get(accession_name=accession_name)
                if acc:
                    accession_id = acc.id
            if population_name:
                pop = Population.get(population_name=population_name)
                if pop:
                    population_id = pop.id

            db_instance = PlotModel.get_or_create(
                plot_number=plot_number,
                plot_row_number=plot_row_number,
                plot_column_number=plot_column_number,
                plot_info=plot_info,
                plot_geometry_info=plot_geometry_info,
                experiment_id=experiment_id,
                season_id=season_id,
                site_id=site_id,
                accession_id=accession_id,
                population_id=population_id,
            )
            return cls.model_validate(db_instance)
        except Exception as e:
            logger.error(f"Error creating plot: {e}")
            return None

    @classmethod
    def create_bulk(cls, plots: List[dict]) -> Tuple[bool, int, int]:
        """
        Bulk-create plots in a small, fixed number of queries.

        Resolves experiment / season / site / accession / population names to IDs
        via one SELECT per entity type, then issues a single
        ``INSERT ... ON CONFLICT DO NOTHING`` for all rows. This replaces the
        per-plot path (5 SELECTs + 1 get_or_create per plot) used by
        :meth:`create`, which does not scale for the import wizard where a
        single spreadsheet can carry thousands of unique plots.

        Args:
            plots: A list of dicts matching ``PlotInput`` — each with
                ``plot_number``, ``plot_row_number``, ``plot_column_number`` and
                optional name-based references (``experiment_name``,
                ``season_name``, ``site_name``, ``accession_name``,
                ``population_name``) plus optional ``plot_info`` /
                ``plot_geometry_info``.
        Returns:
            Tuple of (success, submitted_count, skipped_count). ``skipped_count``
            counts rows whose required FKs (experiment / season / site) could
            not be resolved.
        """
        try:
            from gemini.db.models.experiments import ExperimentModel
            from gemini.db.models.seasons import SeasonModel
            from gemini.db.models.sites import SiteModel
            from gemini.db.models.accessions import AccessionModel
            from gemini.db.models.populations import PopulationModel

            if not plots:
                return True, 0, 0

            experiment_names = {p.get("experiment_name") for p in plots if p.get("experiment_name")}
            season_names = {p.get("season_name") for p in plots if p.get("season_name")}
            site_names = {p.get("site_name") for p in plots if p.get("site_name")}
            accession_names = {p.get("accession_name") for p in plots if p.get("accession_name")}
            population_names = {p.get("population_name") for p in plots if p.get("population_name")}

            with db_engine.get_session() as session:
                exp_id_by_name: dict = {}
                if experiment_names:
                    rows = session.execute(
                        select(ExperimentModel.id, ExperimentModel.experiment_name)
                        .where(ExperimentModel.experiment_name.in_(experiment_names))
                    ).all()
                    exp_id_by_name = {r.experiment_name: r.id for r in rows}

                season_id_by_key: dict = {}
                if season_names and exp_id_by_name:
                    rows = session.execute(
                        select(SeasonModel.id, SeasonModel.season_name, SeasonModel.experiment_id)
                        .where(SeasonModel.season_name.in_(season_names))
                        .where(SeasonModel.experiment_id.in_(list(exp_id_by_name.values())))
                    ).all()
                    # SQLAlchemy returns ExperimentModel.id as str (as_uuid=False)
                    # but SeasonModel.experiment_id as UUID object (as_uuid=True).
                    # Normalise to str so the (season_name, experiment_id) key
                    # matches what we look up below with exp_id_by_name values.
                    season_id_by_key = {(r.season_name, str(r.experiment_id)): r.id for r in rows}

                site_id_by_name: dict = {}
                if site_names:
                    rows = session.execute(
                        select(SiteModel.id, SiteModel.site_name)
                        .where(SiteModel.site_name.in_(site_names))
                    ).all()
                    site_id_by_name = {r.site_name: r.id for r in rows}

                acc_id_by_name: dict = {}
                if accession_names:
                    rows = session.execute(
                        select(AccessionModel.id, AccessionModel.accession_name)
                        .where(AccessionModel.accession_name.in_(accession_names))
                    ).all()
                    acc_id_by_name = {r.accession_name: r.id for r in rows}

                pop_id_by_name: dict = {}
                if population_names:
                    rows = session.execute(
                        select(PopulationModel.id, PopulationModel.population_name)
                        .where(PopulationModel.population_name.in_(population_names))
                    ).all()
                    pop_id_by_name = {r.population_name: r.id for r in rows}

            rows_to_insert = []
            skipped = 0
            for p in plots:
                exp_name = p.get("experiment_name")
                experiment_id = exp_id_by_name.get(exp_name) if exp_name else None
                season_id = (
                    season_id_by_key.get((p.get("season_name"), experiment_id))
                    if experiment_id and p.get("season_name")
                    else None
                )
                site_id = site_id_by_name.get(p.get("site_name")) if p.get("site_name") else None

                if experiment_id is None or season_id is None or site_id is None:
                    skipped += 1
                    continue

                rows_to_insert.append({
                    "plot_number": p["plot_number"],
                    "plot_row_number": p["plot_row_number"],
                    "plot_column_number": p["plot_column_number"],
                    "experiment_id": experiment_id,
                    "season_id": season_id,
                    "site_id": site_id,
                    "accession_id": acc_id_by_name.get(p.get("accession_name")) if p.get("accession_name") else None,
                    "population_id": pop_id_by_name.get(p.get("population_name")) if p.get("population_name") else None,
                    "plot_info": p.get("plot_info") or {},
                    "plot_geometry_info": p.get("plot_geometry_info") or {},
                })

            if skipped:
                logger.warning(
                    f"Skipping {skipped}/{len(plots)} plots with unresolved experiment/season/site references."
                )

            if not rows_to_insert:
                return True, 0, skipped

            with db_engine.get_session() as session:
                stmt = pg_insert(PlotModel.__table__).values(rows_to_insert).on_conflict_do_nothing(
                    index_elements=[
                        "experiment_id",
                        "season_id",
                        "site_id",
                        "plot_number",
                        "plot_row_number",
                        "plot_column_number",
                    ]
                )
                session.execute(stmt)

            logger.info(f"Bulk-inserted {len(rows_to_insert)} plots ({skipped} skipped).")
            return True, len(rows_to_insert), skipped
        except Exception as e:
            logger.error(f"Error bulk-creating plots: {e}")
            return False, 0, len(plots)

    @classmethod
    def get(
        cls,
        plot_number: int,
        plot_row_number: int,
        plot_column_number: int,
        experiment_name: str = None,
        season_name: str = None,
        site_name: str = None,
    ) -> Optional["Plot"]:
        """
        Retrieve a plot by its parameters.

        Examples:
            >>> plot = Plot.get(plot_number=1, plot_row_number=2, plot_column_number=3)
            >>> print(plot)
            Plot(plot_number=1, plot_row_number=2, plot_column_number=3, id=UUID(...))

        Args:
            plot_number (int): The plot number.
            plot_row_number (int): The row number of the plot.
            plot_column_number (int): The column number of the plot.
            experiment_name (str, optional): The name of the experiment. Defaults to None.
            season_name (str, optional): The name of the season. Defaults to None.
            site_name (str, optional): The name of the site. Defaults to None.
        Returns:
            Optional[Plot]: The plot instance, or None if not found.
        """
        try:
            plot = PlotViewModel.get_by_parameters(
                plot_number=plot_number,
                plot_row_number=plot_row_number,
                plot_column_number=plot_column_number,
                experiment_name=experiment_name,
                season_name=season_name,
                site_name=site_name
            )
            if not plot:
                logger.debug(f"Plot with number {plot_number}, row {plot_row_number}, column {plot_column_number} not found.")
                return None
            plot = cls.model_validate(plot)
            return plot
        except Exception as e:
            logger.error(f"Error getting plot: {e}")
            return None

    @classmethod
    def get_by_id(cls, id: UUID | int | str) -> Optional["Plot"]:
        """
        Retrieve a plot by its ID.

        Examples:
            >>> plot = Plot.get_by_id(UUID('...'))
            >>> print(plot)
            Plot(plot_number=1, plot_row_number=2, plot_column_number=3, id=UUID('...'))

        Args:
            id (UUID | int | str): The ID of the plot.
        Returns:
            Optional[Plot]: The plot instance, or None if not found.
        """
        try:
            plot = PlotViewModel.get_by_parameters(plot_id=id)
            if not plot:
                logger.warning(f"Plot with ID {id} does not exist.")
                return None
            plot = cls.model_validate(plot)
            return plot
        except Exception as e:
            logger.error(f"Error getting plot by ID: {e}")
            return None

    @classmethod
    def get_all(cls, limit: int = None, offset: int = None) -> Optional[List["Plot"]]:
        """
        Retrieve all plots.

        Examples:
            >>> plots = Plot.get_all()
            >>> for plot in plots:
            ...     print(plot)
            Plot(plot_number=1, plot_row_number=2, plot_column_number=3, id=UUID(...))
            Plot(plot_number=2, plot_row_number=3, plot_column_number=4, id=UUID(...))


        Returns:
            Optional[List[Plot]]: A list of all plots, or None if not found.
        """
        try:
            plots = PlotModel.all(limit=limit, offset=offset)
            if not plots or len(plots) == 0:
                logger.info("No plots found.")
                return None
            plots = [cls.model_validate(plot) for plot in plots]
            return plots
        except Exception as e:
            logger.error(f"Error getting all plots: {e}")
            return None

    @classmethod
    def search(
        cls,
        plot_number: int = None,
        plot_row_number: int = None,
        plot_column_number: int = None,
        experiment_name: str = None,
        season_name: str = None,
        site_name: str = None,
        accession_name: str = None,
        population_name: str = None,
    ) -> Optional[List["Plot"]]:
        try:
            if not any([plot_number, plot_row_number, plot_column_number, experiment_name, season_name, site_name, accession_name, population_name]):
                logger.warning("At least one search parameter must be provided.")
                return None

            plots = PlotViewModel.search(
                plot_number=plot_number,
                plot_row_number=plot_row_number,
                plot_column_number=plot_column_number,
                experiment_name=experiment_name,
                season_name=season_name,
                site_name=site_name,
                accession_name=accession_name,
                population_name=population_name,
            )
            if not plots or len(plots) == 0:
                logger.info("No plots found with the provided search parameters.")
                return None
            plots = [cls.model_validate(plot) for plot in plots]
            return plots if plots else None
        except Exception as e:
            logger.error(f"Error searching plots: {e}")
            return None

    def update(
        self,
        plot_number: int = None,
        plot_row_number: int = None,
        plot_column_number: int = None,
        plot_info: dict = None,
        plot_geometry_info: dict = None
    ) -> Optional["Plot"]:
        """
        Update the details of the plot.

        Examples:
            >>> plot = Plot.get_by_id(UUID('...'))
            >>> updated_plot = plot.update(plot_number=2, plot_row_number=3)
            >>> print(updated_plot)
            Plot(plot_number=2, plot_row_number=3, plot_column_number=3, id=UUID('...'))

        Args:
            plot_number (int, optional): The new plot number. Defaults to None.
            plot_row_number (int, optional): The new row number. Defaults to None.
            plot_column_number (int, optional): The new column number. Defaults to None.
            plot_info (dict, optional): The new plot information. Defaults to None.
            plot_geometry_info (dict, optional): The new geometry information. Defaults to None.
        Returns:
            Optional[Plot]: The updated plot instance, or None if an error occurred.
        """
        try:
            if not any([plot_number, plot_row_number, plot_column_number, plot_info, plot_geometry_info]):
                logger.warning("At least one parameter must be provided.")
                return None

            current_id = self.id
            plot = PlotModel.get(current_id)
            if not plot:
                logger.warning(f"Plot with ID {current_id} does not exist.")
                return None
            plot = PlotModel.update(
                plot,
                plot_number=plot_number,
                plot_row_number=plot_row_number,
                plot_column_number=plot_column_number,
                plot_info=plot_info,
                plot_geometry_info=plot_geometry_info
            )
            plot = self.model_validate(plot)
            self.refresh()
            return plot
        except Exception as e:
            logger.error(f"Error updating plot: {e}")
            return None

    def refresh(self) -> Optional["Plot"]:
        """
        Refresh the plot's data from the database.

        Examples:
            >>> plot = Plot.get_by_id(UUID('...'))
            >>> refreshed_plot = plot.refresh()
            >>> print(refreshed_plot)
            Plot(plot_number=1, plot_row_number=2, plot_column_number=3, id=UUID('...'))

        Returns:
            Optional[Plot]: The refreshed plot instance, or None if an error occurred.
        """
        try:
            db_instance = PlotViewModel.get_by_parameters(plot_id=self.id)
            if not db_instance:
                logger.warning(f"Plot with ID {self.id} does not exist.")
                return self
            instance = self.model_validate(db_instance)
            instance_dict = dict(instance)
            for key, value in instance_dict.items():
                if hasattr(self, key) and key != "id":
                    value = getattr(instance, key)
                    setattr(self, key, value)
            return self
        except Exception as e:
            logger.error(f"Error refreshing plot: {e}")
            return None

    def delete(self) -> bool:
        """
        Delete the plot.

        Examples:
            >>> plot = Plot.get_by_id(UUID('...'))
            >>> deleted = plot.delete()
            >>> print(deleted)
            True

        Returns:
            bool: True if the plot was deleted, False otherwise.
        """
        try:
            current_id = self.id
            plot = PlotModel.get(current_id)
            if not plot:
                logger.warning(f"Plot with ID {current_id} does not exist.")
                return False
            PlotModel.delete(plot)
            return True
        except Exception as e:
            logger.error(f"Error deleting plot: {e}")
            return False

    def get_info(self) -> Optional[dict]:
        """
        Get the additional information of the plot.

        Examples:
            >>> plot = Plot.get_by_id(UUID('...'))
            >>> plot_info = plot.get_info()
            >>> print(plot_info)
            {'key': 'value'}

        Returns:
            Optional[dict]: The plot's info, or None if not found.
        """
        try:
            current_id = self.id
            plot = PlotModel.get(current_id)
            if not plot:
                logger.warning(f"Plot with ID {current_id} does not exist.")
                return None
            plot_info = plot.plot_info
            if not plot_info:
                logger.info("Plot info is empty.")
                return None
            return plot_info
        except Exception as e:
            logger.error(f"Error getting plot info: {e}")
            return None

    def set_info(self, plot_info: dict) -> Optional["Plot"]:
        """
        Set the additional information of the plot.

        Examples:
            >>> plot = Plot.get_by_id(UUID('...'))
            >>> updated_plot = plot.set_info({'key': 'new_value'})
            >>> print(updated_plot.get_info())
            {'key': 'new_value'}

        Args:
            plot_info (dict): The new information to set.
        Returns:
            Optional[Plot]: The updated plot instance, or None if an error occurred.
        """
        try:
            current_id = self.id
            plot = PlotModel.get(current_id)
            if not plot:
                logger.warning(f"Plot with ID {current_id} does not exist.")
                return None
            plot = PlotModel.update(
                plot,
                plot_info=plot_info
            )
            plot = self.model_validate(plot)
            self.refresh()
            return self
        except Exception as e:
            logger.error(f"Error setting plot info: {e}")  
            return None

    def get_associated_experiment(self) -> Optional["Experiment"]:
        """
        Get the experiment associated with this plot.

        Examples:
            >>> plot = Plot.get_by_id(UUID('...'))
            >>> experiment = plot.get_associated_experiment()
            >>> print(experiment)
            Experiment(experiment_name='Experiment 1', experiment_start_date='2023-01-01', experiment_end_date='2023-12-31', id=UUID(...))

        Returns:
            Optional[Experiment]: The associated experiment, or None if not found.
        """
        try:
            from gemini.api.experiment import Experiment
            if not self.experiment_id:
                logger.info("Plot does not belong to any experiment.")
                return None
            experiment = Experiment.get_by_id(self.experiment_id)
            if not experiment:
                logger.warning(f"Experiment with ID {self.experiment_id} does not exist.")
                return None
            return experiment
        except Exception as e:
            logger.error(f"Error getting experiment: {e}")
            return None


    def belongs_to_experiment(self, experiment_name: str) -> bool:
        """
        Check if this plot is associated with a specific experiment.

        Examples:
            >>> plot = Plot.get_by_id(UUID('...'))
            >>> is_associated = plot.belongs_to_experiment("Experiment 1")
            >>> print(is_associated)
            True

        Args:
            experiment_name (str): The name of the experiment to check.
        Returns:
            bool: True if associated, False otherwise.
        """
        try:
            from gemini.api.experiment import Experiment
            experiment = Experiment.get(experiment_name=experiment_name)
            if not experiment:
                logger.warning(f"Experiment with name {experiment_name} does not exist.")
                return False
            association_exists = PlotViewModel.exists(
                plot_id=self.id,
                experiment_id=experiment.id
            )
            return association_exists
        except Exception as e:
            logger.error(f"Error checking if plot belongs to experiment: {e}")
            return False

    def associate_experiment(self, experiment_name: str) -> Optional["Experiment"]:
        """
        Associate this plot with an experiment.

        Examples:
            >>> plot = Plot.get_by_id(UUID('...'))
            >>> experiment = plot.associate_experiment("Experiment 1")
            >>> print(experiment)
            Experiment(experiment_name='Experiment 1', experiment_start_date='2023-01-01', experiment_end_date='2023-12-31', id=UUID(...))

        Args:
            experiment_name (str): The name of the experiment to associate.
        Returns:
            Optional[Experiment]: The associated experiment, or None if an error occurred.
        """
        try:
            from gemini.api.experiment import Experiment
            experiment = Experiment.get(experiment_name=experiment_name)
            if not experiment:
                logger.warning(f"Experiment with name {experiment_name} does not exist.")
                return None
            existing_association = PlotViewModel.get_by_parameters(
                plot_id=self.id,
                experiment_id=experiment.id
            )
            if existing_association:
                logger.info(f"Plot {self.id} is already associated with experiment {experiment_name}.")
                return self
            db_plot = PlotModel.get(self.id)
            db_plot = PlotModel.update_parameter(
                db_plot,
                "experiment_id",
                experiment.id
            )
            logger.info(f"Plot {self.id} associated with experiment {experiment_name}.")
            self.refresh()
            return experiment
        except Exception as e:
            logger.error(f"Error assigning experiment to plot: {e}")
            return None

    def unassociate_experiment(self) -> Optional["Experiment"]:
        """
        Unassociate this plot from its experiment.

        Examples:
            >>> plot = Plot.get_by_id(UUID('...'))
            >>> experiment = plot.unassociate_experiment()
            >>> print(experiment)
            Experiment(experiment_name='Experiment 1', experiment_start_date='2023-01-01', experiment_end_date='2023-12-31', id=UUID(...))

        Returns:
            Optional[Experiment]: The unassociated experiment, or None if an error occurred.
        """
        try:
            from gemini.api.experiment import Experiment
            if not self.experiment_id:
                logger.info("Plot does not belong to any experiment.")
                return None
            experiment = Experiment.get_by_id(self.experiment_id)
            db_plot = PlotModel.get(self.id)
            db_plot = PlotModel.update_parameter(
                db_plot,
                "experiment_id",
                None
            )
            self.refresh()
            return experiment   
        except Exception as e:
            logger.error(f"Error unassigning experiment from plot: {e}")
            return None

    def get_associated_season(self) -> Optional["Season"]:
        """
        Get the season associated with this plot.

        Examples:
            >>> plot = Plot.get_by_id(UUID('...'))
            >>> season = plot.get_associated_season()
            >>> print(season)
            Season(season_name='Season 1', season_start_date='2023-01-01', season_end_date='2023-12-31', id=UUID(...))

        Returns:
            Optional[Season]: The associated season, or None if not found.
        """
        try:
            from gemini.api.season import Season
            if not self.season_id:
                logger.info("Plot does not belong to any season.")
                return None
            season = Season.get_by_id(self.season_id)
            if not season:
                logger.warning(f"Season with ID {self.season_id} does not exist.")
                return None
            return season
        except Exception as e:
            logger.error(f"Error getting season: {e}")
            return None


    def belongs_to_season(self, season_name: str, experiment_name: str) -> bool:
        """
        Check if this plot is associated with a specific season.

        Examples:
            >>> plot = Plot.get_by_id(UUID('...'))
            >>> is_associated = plot.belongs_to_season("Season 1", "Experiment 1")
            >>> print(is_associated)
            True

        Args:
            season_name (str): The name of the season to check.
            experiment_name (str): The name of the experiment.
        Returns:
            bool: True if associated, False otherwise.
        """
        try:
            from gemini.api.season import Season
            from gemini.api.experiment import Experiment
            season = Season.get(season_name=season_name, experiment_name=experiment_name)
            experiment = Experiment.get(experiment_name=experiment_name)
            if not experiment or not season:
                logger.warning(f"Experiment with name {experiment_name} or season with name {season_name} does not exist.")
                return False
            association_exists = PlotViewModel.exists(
                plot_id=self.id,
                season_id=self.season_id,
                experiment_id=experiment.id
            )
            return association_exists
        except Exception as e:
            logger.error(f"Error checking if plot belongs to season: {e}")
            return False

    def associate_season(self, season_name: str, experiment_name: str) -> Optional["Season"]:
        """
        Associate this plot with a season.

        Examples:
            >>> plot = Plot.get_by_id(UUID('...'))
            >>> season = plot.associate_season("Season 1", "Experiment 1")
            >>> print(season)
            Season(season_name='Season 1', season_start_date='2023-01-01', season_end_date='2023-12-31', id=UUID(...))

        Args:
            season_name (str): The name of the season to associate.
            experiment_name (str): The name of the experiment.
        Returns:
            Optional[Season]: The associated season, or None if an error occurred.
        """
        try:
            from gemini.api.season import Season
            season = Season.get(season_name=season_name, experiment_name=experiment_name)
            if not season:
                logger.warning(f"Season with name {season_name} does not exist.")
                return None
            existing_association = PlotViewModel.get_by_parameters(
                plot_id=self.id,
                season_id=season.id,
                experiment_id=season.experiment_id
            )
            if existing_association:
                logger.info(f"Plot {self.id} is already associated with season {season_name}.")
                return self
            db_plot = PlotModel.get(self.id)
            db_plot = PlotModel.update_parameter(
                db_plot,
                "season_id",
                season.id
            )
            logger.info(f"Plot {self.id} associated with season {season_name}.")
            self.refresh()
            return season
        except Exception as e:
            logger.error(f"Error assigning season to plot: {e}")
            return None

    def unassociate_season(self) -> Optional["Season"]:
        """
        Unassociate this plot from its season.

        Examples:
            >>> plot = Plot.get_by_id(UUID('...'))
            >>> season = plot.unassociate_season()
            >>> print(season)
            Season(season_name='Season 1', season_start_date='2023-01-01', season_end_date='2023-12-31', id=UUID(...))

        Returns:
            Optional[Season]: The unassociated season, or None if an error occurred.
        """
        try:
            from gemini.api.season import Season
            if not self.season_id:
                logger.info("Plot does not belong to any season.")
                return None
            season = Season.get_by_id(self.season_id)
            db_plot = PlotModel.get(self.id)
            db_plot = PlotModel.update_parameter(
                db_plot,
                "season_id",
                None
            )
            self.refresh()
            return season
        except Exception as e:
            logger.error(f"Error unassigning season from plot: {e}")
            return None

    def get_associated_site(self) -> Optional["Site"]:
        """
        Get the site associated with this plot.

        Examples:
            >>> plot = Plot.get_by_id(UUID('...'))
            >>> site = plot.get_associated_site()
            >>> print(site)
            Site(site_name='Site 1', id=UUID(...))

        Returns:
            Optional[Site]: The associated site, or None if not found.
        """
        try:
            from gemini.api.site import Site
            if not self.site_id:
                logger.info("Plot does not belong to any site.")
                return None
            site = Site.get_by_id(self.site_id)
            if not site:
                logger.warning(f"Site with ID {self.site_id} does not exist.")
                return None
            return site
        except Exception as e:
            logger.error(f"Error getting site: {e}")
            return None

    def belongs_to_site(self, site_name: str) -> bool:
        """
        Check if this plot is associated with a specific site.

        Examples:
            >>> plot = Plot.get_by_id(UUID('...'))
            >>> is_associated = plot.belongs_to_site("Site 1")
            >>> print(is_associated)
            True

        Args:
            site_name (str): The name of the site to check.
        Returns:
            bool: True if associated, False otherwise.
        """
        try:
            from gemini.api.site import Site
            site = Site.get(site_name=site_name)
            if not site:
                logger.warning(f"Site with name {site_name} does not exist.")
                return False
            association_exists = PlotViewModel.exists(
                plot_id=self.id,
                site_id=site.id
            )
            return association_exists
        except Exception as e:
            logger.error(f"Error checking if plot belongs to site: {e}")
            return False

    def associate_site(self, site_name: str) -> Optional["Site"]:
        """
        Associate this plot with a site.

        Examples:
            >>> plot = Plot.get_by_id(UUID('...'))
            >>> site = plot.associate_site("Site 1")
            >>> print(site)
            Site(site_name='Site 1', id=UUID(...))

        Args:
            site_name (str): The name of the site to associate.
        Returns:
            Optional[Site]: The associated site, or None if an error occurred.
        """
        try:
            from gemini.api.site import Site
            site = Site.get(site_name=site_name)
            if not site:
                logger.warning(f"Site with name {site_name} does not exist.")
                return None
            existing_association = PlotViewModel.get_by_parameters(
                plot_id=self.id,
                site_id=site.id
            )
            if existing_association:
                logger.info(f"Plot {self.id} is already associated with site {site_name}.")
                return self
            db_plot = PlotModel.get(self.id)
            db_plot = PlotModel.update_parameter(
                db_plot,
                "site_id",
                site.id
            )
            logger.info(f"Plot {self.id} associated with site {site_name}.")
            self.refresh()
            return site
        except Exception as e:
            logger.error(f"Error assigning site to plot: {e}")
            return None

    def unassociate_site(self) -> Optional["Site"]:
        """
        Unassociate this plot from its site.

        Examples:
            >>> plot = Plot.get_by_id(UUID('...'))
            >>> site = plot.unassociate_site()
            >>> print(site)
            Site(site_name='Site 1', id=UUID(...))

        Returns:
            Optional[Site]: The unassociated site, or None if an error occurred.
        """
        try:
            from gemini.api.site import Site
            if not self.site_id:
                logger.info("Plot does not belong to any site.")
                return None
            site = Site.get_by_id(self.site_id)
            db_plot = PlotModel.get(self.id)
            db_plot = PlotModel.update_parameter(
                db_plot,
                "site_id",
                None
            )
            self.refresh()
            return site
        except Exception as e:
            logger.error(f"Error unassigning site from plot: {e}")
            return None

    def get_accession(self) -> Optional["Accession"]:
        try:
            if not self.accession_id:
                return None
            from gemini.api.accession import Accession
            return Accession.get_by_id(self.accession_id)
        except Exception as e:
            logger.error(f"Error getting accession for plot: {e}")
            return None

    def get_population(self) -> Optional["Population"]:
        try:
            if not self.population_id:
                return None
            from gemini.api.population import Population
            return Population.get_by_id(self.population_id)
        except Exception as e:
            logger.error(f"Error getting population for plot: {e}")
            return None

__repr__()

Return a detailed string representation of the Plot object.

Source code in gemini/api/plot.py

def __repr__(self):
    """Return a detailed string representation of the Plot object."""
    return f"Plot(plot_number={self.plot_number}, plot_row_number={self.plot_row_number}, plot_column_number={self.plot_column_number}, id={self.id})"

__str__()

Return a string representation of the Plot object.

Source code in gemini/api/plot.py

def __str__(self):
    """Return a string representation of the Plot object."""
    return f"Plot(plot_number={self.plot_number}, plot_row_number={self.plot_row_number}, plot_column_number={self.plot_column_number}, id={self.id})"

associate_experiment(experiment_name)

Associate this plot with an experiment.

Examples:

>>> plot = Plot.get_by_id(UUID('...'))
>>> experiment = plot.associate_experiment("Experiment 1")
>>> print(experiment)
Experiment(experiment_name='Experiment 1', experiment_start_date='2023-01-01', experiment_end_date='2023-12-31', id=UUID(...))

Parameters:

Name	Type	Description	Default
experiment_name	str	The name of the experiment to associate.	required

Returns: Optional[Experiment]: The associated experiment, or None if an error occurred.

Source code in gemini/api/plot.py

def associate_experiment(self, experiment_name: str) -> Optional["Experiment"]:
    """
    Associate this plot with an experiment.

    Examples:
        >>> plot = Plot.get_by_id(UUID('...'))
        >>> experiment = plot.associate_experiment("Experiment 1")
        >>> print(experiment)
        Experiment(experiment_name='Experiment 1', experiment_start_date='2023-01-01', experiment_end_date='2023-12-31', id=UUID(...))

    Args:
        experiment_name (str): The name of the experiment to associate.
    Returns:
        Optional[Experiment]: The associated experiment, or None if an error occurred.
    """
    try:
        from gemini.api.experiment import Experiment
        experiment = Experiment.get(experiment_name=experiment_name)
        if not experiment:
            logger.warning(f"Experiment with name {experiment_name} does not exist.")
            return None
        existing_association = PlotViewModel.get_by_parameters(
            plot_id=self.id,
            experiment_id=experiment.id
        )
        if existing_association:
            logger.info(f"Plot {self.id} is already associated with experiment {experiment_name}.")
            return self
        db_plot = PlotModel.get(self.id)
        db_plot = PlotModel.update_parameter(
            db_plot,
            "experiment_id",
            experiment.id
        )
        logger.info(f"Plot {self.id} associated with experiment {experiment_name}.")
        self.refresh()
        return experiment
    except Exception as e:
        logger.error(f"Error assigning experiment to plot: {e}")
        return None

associate_season(season_name, experiment_name)

Associate this plot with a season.

Examples:

>>> plot = Plot.get_by_id(UUID('...'))
>>> season = plot.associate_season("Season 1", "Experiment 1")
>>> print(season)
Season(season_name='Season 1', season_start_date='2023-01-01', season_end_date='2023-12-31', id=UUID(...))

Parameters:

Name	Type	Description	Default
season_name	str	The name of the season to associate.	required
experiment_name	str	The name of the experiment.	required

Returns: Optional[Season]: The associated season, or None if an error occurred.

Source code in gemini/api/plot.py

def associate_season(self, season_name: str, experiment_name: str) -> Optional["Season"]:
    """
    Associate this plot with a season.

    Examples:
        >>> plot = Plot.get_by_id(UUID('...'))
        >>> season = plot.associate_season("Season 1", "Experiment 1")
        >>> print(season)
        Season(season_name='Season 1', season_start_date='2023-01-01', season_end_date='2023-12-31', id=UUID(...))

    Args:
        season_name (str): The name of the season to associate.
        experiment_name (str): The name of the experiment.
    Returns:
        Optional[Season]: The associated season, or None if an error occurred.
    """
    try:
        from gemini.api.season import Season
        season = Season.get(season_name=season_name, experiment_name=experiment_name)
        if not season:
            logger.warning(f"Season with name {season_name} does not exist.")
            return None
        existing_association = PlotViewModel.get_by_parameters(
            plot_id=self.id,
            season_id=season.id,
            experiment_id=season.experiment_id
        )
        if existing_association:
            logger.info(f"Plot {self.id} is already associated with season {season_name}.")
            return self
        db_plot = PlotModel.get(self.id)
        db_plot = PlotModel.update_parameter(
            db_plot,
            "season_id",
            season.id
        )
        logger.info(f"Plot {self.id} associated with season {season_name}.")
        self.refresh()
        return season
    except Exception as e:
        logger.error(f"Error assigning season to plot: {e}")
        return None

associate_site(site_name)

Associate this plot with a site.

Examples:

>>> plot = Plot.get_by_id(UUID('...'))
>>> site = plot.associate_site("Site 1")
>>> print(site)
Site(site_name='Site 1', id=UUID(...))

Parameters:

Name	Type	Description	Default
site_name	str	The name of the site to associate.	required

Returns: Optional[Site]: The associated site, or None if an error occurred.

Source code in gemini/api/plot.py

def associate_site(self, site_name: str) -> Optional["Site"]:
    """
    Associate this plot with a site.

    Examples:
        >>> plot = Plot.get_by_id(UUID('...'))
        >>> site = plot.associate_site("Site 1")
        >>> print(site)
        Site(site_name='Site 1', id=UUID(...))

    Args:
        site_name (str): The name of the site to associate.
    Returns:
        Optional[Site]: The associated site, or None if an error occurred.
    """
    try:
        from gemini.api.site import Site
        site = Site.get(site_name=site_name)
        if not site:
            logger.warning(f"Site with name {site_name} does not exist.")
            return None
        existing_association = PlotViewModel.get_by_parameters(
            plot_id=self.id,
            site_id=site.id
        )
        if existing_association:
            logger.info(f"Plot {self.id} is already associated with site {site_name}.")
            return self
        db_plot = PlotModel.get(self.id)
        db_plot = PlotModel.update_parameter(
            db_plot,
            "site_id",
            site.id
        )
        logger.info(f"Plot {self.id} associated with site {site_name}.")
        self.refresh()
        return site
    except Exception as e:
        logger.error(f"Error assigning site to plot: {e}")
        return None

belongs_to_experiment(experiment_name)

Check if this plot is associated with a specific experiment.

Examples:

>>> plot = Plot.get_by_id(UUID('...'))
>>> is_associated = plot.belongs_to_experiment("Experiment 1")
>>> print(is_associated)
True

Parameters:

Name	Type	Description	Default
experiment_name	str	The name of the experiment to check.	required

Returns: bool: True if associated, False otherwise.

Source code in gemini/api/plot.py

def belongs_to_experiment(self, experiment_name: str) -> bool:
    """
    Check if this plot is associated with a specific experiment.

    Examples:
        >>> plot = Plot.get_by_id(UUID('...'))
        >>> is_associated = plot.belongs_to_experiment("Experiment 1")
        >>> print(is_associated)
        True

    Args:
        experiment_name (str): The name of the experiment to check.
    Returns:
        bool: True if associated, False otherwise.
    """
    try:
        from gemini.api.experiment import Experiment
        experiment = Experiment.get(experiment_name=experiment_name)
        if not experiment:
            logger.warning(f"Experiment with name {experiment_name} does not exist.")
            return False
        association_exists = PlotViewModel.exists(
            plot_id=self.id,
            experiment_id=experiment.id
        )
        return association_exists
    except Exception as e:
        logger.error(f"Error checking if plot belongs to experiment: {e}")
        return False

belongs_to_season(season_name, experiment_name)

Check if this plot is associated with a specific season.

Examples:

>>> plot = Plot.get_by_id(UUID('...'))
>>> is_associated = plot.belongs_to_season("Season 1", "Experiment 1")
>>> print(is_associated)
True

Parameters:

Name	Type	Description	Default
season_name	str	The name of the season to check.	required
experiment_name	str	The name of the experiment.	required

Returns: bool: True if associated, False otherwise.

Source code in gemini/api/plot.py

def belongs_to_season(self, season_name: str, experiment_name: str) -> bool:
    """
    Check if this plot is associated with a specific season.

    Examples:
        >>> plot = Plot.get_by_id(UUID('...'))
        >>> is_associated = plot.belongs_to_season("Season 1", "Experiment 1")
        >>> print(is_associated)
        True

    Args:
        season_name (str): The name of the season to check.
        experiment_name (str): The name of the experiment.
    Returns:
        bool: True if associated, False otherwise.
    """
    try:
        from gemini.api.season import Season
        from gemini.api.experiment import Experiment
        season = Season.get(season_name=season_name, experiment_name=experiment_name)
        experiment = Experiment.get(experiment_name=experiment_name)
        if not experiment or not season:
            logger.warning(f"Experiment with name {experiment_name} or season with name {season_name} does not exist.")
            return False
        association_exists = PlotViewModel.exists(
            plot_id=self.id,
            season_id=self.season_id,
            experiment_id=experiment.id
        )
        return association_exists
    except Exception as e:
        logger.error(f"Error checking if plot belongs to season: {e}")
        return False

belongs_to_site(site_name)

Check if this plot is associated with a specific site.

Examples:

>>> plot = Plot.get_by_id(UUID('...'))
>>> is_associated = plot.belongs_to_site("Site 1")
>>> print(is_associated)
True

Parameters:

Name	Type	Description	Default
site_name	str	The name of the site to check.	required

Returns: bool: True if associated, False otherwise.

Source code in gemini/api/plot.py

def belongs_to_site(self, site_name: str) -> bool:
    """
    Check if this plot is associated with a specific site.

    Examples:
        >>> plot = Plot.get_by_id(UUID('...'))
        >>> is_associated = plot.belongs_to_site("Site 1")
        >>> print(is_associated)
        True

    Args:
        site_name (str): The name of the site to check.
    Returns:
        bool: True if associated, False otherwise.
    """
    try:
        from gemini.api.site import Site
        site = Site.get(site_name=site_name)
        if not site:
            logger.warning(f"Site with name {site_name} does not exist.")
            return False
        association_exists = PlotViewModel.exists(
            plot_id=self.id,
            site_id=site.id
        )
        return association_exists
    except Exception as e:
        logger.error(f"Error checking if plot belongs to site: {e}")
        return False

create_bulk(plots) classmethod

Bulk-create plots in a small, fixed number of queries.

Resolves experiment / season / site / accession / population names to IDs via one SELECT per entity type, then issues a single INSERT ... ON CONFLICT DO NOTHING for all rows. This replaces the per-plot path (5 SELECTs + 1 get_or_create per plot) used by :meth:create, which does not scale for the import wizard where a single spreadsheet can carry thousands of unique plots.

Parameters:

Name	Type	Description	Default
plots	List[dict]	A list of dicts matching PlotInput — each with plot_number, plot_row_number, plot_column_number and optional name-based references (experiment_name, season_name, site_name, accession_name, population_name) plus optional plot_info / plot_geometry_info.	required

Returns: Tuple of (success, submitted_count, skipped_count). skipped_count counts rows whose required FKs (experiment / season / site) could not be resolved.

Source code in gemini/api/plot.py

@classmethod
def create_bulk(cls, plots: List[dict]) -> Tuple[bool, int, int]:
    """
    Bulk-create plots in a small, fixed number of queries.

    Resolves experiment / season / site / accession / population names to IDs
    via one SELECT per entity type, then issues a single
    ``INSERT ... ON CONFLICT DO NOTHING`` for all rows. This replaces the
    per-plot path (5 SELECTs + 1 get_or_create per plot) used by
    :meth:`create`, which does not scale for the import wizard where a
    single spreadsheet can carry thousands of unique plots.

    Args:
        plots: A list of dicts matching ``PlotInput`` — each with
            ``plot_number``, ``plot_row_number``, ``plot_column_number`` and
            optional name-based references (``experiment_name``,
            ``season_name``, ``site_name``, ``accession_name``,
            ``population_name``) plus optional ``plot_info`` /
            ``plot_geometry_info``.
    Returns:
        Tuple of (success, submitted_count, skipped_count). ``skipped_count``
        counts rows whose required FKs (experiment / season / site) could
        not be resolved.
    """
    try:
        from gemini.db.models.experiments import ExperimentModel
        from gemini.db.models.seasons import SeasonModel
        from gemini.db.models.sites import SiteModel
        from gemini.db.models.accessions import AccessionModel
        from gemini.db.models.populations import PopulationModel

        if not plots:
            return True, 0, 0

        experiment_names = {p.get("experiment_name") for p in plots if p.get("experiment_name")}
        season_names = {p.get("season_name") for p in plots if p.get("season_name")}
        site_names = {p.get("site_name") for p in plots if p.get("site_name")}
        accession_names = {p.get("accession_name") for p in plots if p.get("accession_name")}
        population_names = {p.get("population_name") for p in plots if p.get("population_name")}

        with db_engine.get_session() as session:
            exp_id_by_name: dict = {}
            if experiment_names:
                rows = session.execute(
                    select(ExperimentModel.id, ExperimentModel.experiment_name)
                    .where(ExperimentModel.experiment_name.in_(experiment_names))
                ).all()
                exp_id_by_name = {r.experiment_name: r.id for r in rows}

            season_id_by_key: dict = {}
            if season_names and exp_id_by_name:
                rows = session.execute(
                    select(SeasonModel.id, SeasonModel.season_name, SeasonModel.experiment_id)
                    .where(SeasonModel.season_name.in_(season_names))
                    .where(SeasonModel.experiment_id.in_(list(exp_id_by_name.values())))
                ).all()
                # SQLAlchemy returns ExperimentModel.id as str (as_uuid=False)
                # but SeasonModel.experiment_id as UUID object (as_uuid=True).
                # Normalise to str so the (season_name, experiment_id) key
                # matches what we look up below with exp_id_by_name values.
                season_id_by_key = {(r.season_name, str(r.experiment_id)): r.id for r in rows}

            site_id_by_name: dict = {}
            if site_names:
                rows = session.execute(
                    select(SiteModel.id, SiteModel.site_name)
                    .where(SiteModel.site_name.in_(site_names))
                ).all()
                site_id_by_name = {r.site_name: r.id for r in rows}

            acc_id_by_name: dict = {}
            if accession_names:
                rows = session.execute(
                    select(AccessionModel.id, AccessionModel.accession_name)
                    .where(AccessionModel.accession_name.in_(accession_names))
                ).all()
                acc_id_by_name = {r.accession_name: r.id for r in rows}

            pop_id_by_name: dict = {}
            if population_names:
                rows = session.execute(
                    select(PopulationModel.id, PopulationModel.population_name)
                    .where(PopulationModel.population_name.in_(population_names))
                ).all()
                pop_id_by_name = {r.population_name: r.id for r in rows}

        rows_to_insert = []
        skipped = 0
        for p in plots:
            exp_name = p.get("experiment_name")
            experiment_id = exp_id_by_name.get(exp_name) if exp_name else None
            season_id = (
                season_id_by_key.get((p.get("season_name"), experiment_id))
                if experiment_id and p.get("season_name")
                else None
            )
            site_id = site_id_by_name.get(p.get("site_name")) if p.get("site_name") else None

            if experiment_id is None or season_id is None or site_id is None:
                skipped += 1
                continue

            rows_to_insert.append({
                "plot_number": p["plot_number"],
                "plot_row_number": p["plot_row_number"],
                "plot_column_number": p["plot_column_number"],
                "experiment_id": experiment_id,
                "season_id": season_id,
                "site_id": site_id,
                "accession_id": acc_id_by_name.get(p.get("accession_name")) if p.get("accession_name") else None,
                "population_id": pop_id_by_name.get(p.get("population_name")) if p.get("population_name") else None,
                "plot_info": p.get("plot_info") or {},
                "plot_geometry_info": p.get("plot_geometry_info") or {},
            })

        if skipped:
            logger.warning(
                f"Skipping {skipped}/{len(plots)} plots with unresolved experiment/season/site references."
            )

        if not rows_to_insert:
            return True, 0, skipped

        with db_engine.get_session() as session:
            stmt = pg_insert(PlotModel.__table__).values(rows_to_insert).on_conflict_do_nothing(
                index_elements=[
                    "experiment_id",
                    "season_id",
                    "site_id",
                    "plot_number",
                    "plot_row_number",
                    "plot_column_number",
                ]
            )
            session.execute(stmt)

        logger.info(f"Bulk-inserted {len(rows_to_insert)} plots ({skipped} skipped).")
        return True, len(rows_to_insert), skipped
    except Exception as e:
        logger.error(f"Error bulk-creating plots: {e}")
        return False, 0, len(plots)

delete()

Delete the plot.

Examples:

>>> plot = Plot.get_by_id(UUID('...'))
>>> deleted = plot.delete()
>>> print(deleted)
True

Returns:

Name	Type	Description
bool	bool	True if the plot was deleted, False otherwise.

Source code in gemini/api/plot.py

def delete(self) -> bool:
    """
    Delete the plot.

    Examples:
        >>> plot = Plot.get_by_id(UUID('...'))
        >>> deleted = plot.delete()
        >>> print(deleted)
        True

    Returns:
        bool: True if the plot was deleted, False otherwise.
    """
    try:
        current_id = self.id
        plot = PlotModel.get(current_id)
        if not plot:
            logger.warning(f"Plot with ID {current_id} does not exist.")
            return False
        PlotModel.delete(plot)
        return True
    except Exception as e:
        logger.error(f"Error deleting plot: {e}")
        return False

exists(plot_number, plot_row_number, plot_column_number, experiment_name=None, season_name=None, site_name=None) classmethod

Check if a plot with the given parameters exists.

Examples:

>>> Plot.exists(plot_number=1, plot_row_number=2, plot_column_number=3)
True
>>> Plot.exists(plot_number=1, plot_row_number=2, plot_column_number=3, experiment_name="Experiment 1")
False

Parameters:

Name	Type	Description	Default
plot_number	int	The plot number.	required
plot_row_number	int	The row number of the plot.	required
plot_column_number	int	The column number of the plot.	required
experiment_name	str	The name of the experiment. Defaults to None.	None
season_name	str	The name of the season. Defaults to None.	None
site_name	str	The name of the site. Defaults to None.	None

Returns: bool: True if the plot exists, False otherwise.

Source code in gemini/api/plot.py

@classmethod
def exists(
    cls,
    plot_number: int,
    plot_row_number: int,
    plot_column_number: int,
    experiment_name: str = None,
    season_name: str = None,
    site_name: str = None
) -> bool:
    """
    Check if a plot with the given parameters exists.

    Examples:
        >>> Plot.exists(plot_number=1, plot_row_number=2, plot_column_number=3)
        True
        >>> Plot.exists(plot_number=1, plot_row_number=2, plot_column_number=3, experiment_name="Experiment 1")
        False

    Args:
        plot_number (int): The plot number.
        plot_row_number (int): The row number of the plot.
        plot_column_number (int): The column number of the plot.
        experiment_name (str, optional): The name of the experiment. Defaults to None.
        season_name (str, optional): The name of the season. Defaults to None.
        site_name (str, optional): The name of the site. Defaults to None.
    Returns:
        bool: True if the plot exists, False otherwise.
    """
    try:
        exists = PlotViewModel.exists(
            plot_number=plot_number,
            plot_row_number=plot_row_number,
            plot_column_number=plot_column_number,
            experiment_name=experiment_name,
            season_name=season_name,
            site_name=site_name
        )
        return exists
    except Exception as e:
        logger.error(f"Error checking existence of plot: {e}")
        return False

get(plot_number, plot_row_number, plot_column_number, experiment_name=None, season_name=None, site_name=None) classmethod

Retrieve a plot by its parameters.

Examples:

>>> plot = Plot.get(plot_number=1, plot_row_number=2, plot_column_number=3)
>>> print(plot)
Plot(plot_number=1, plot_row_number=2, plot_column_number=3, id=UUID(...))

Parameters:

Name	Type	Description	Default
plot_number	int	The plot number.	required
plot_row_number	int	The row number of the plot.	required
plot_column_number	int	The column number of the plot.	required
experiment_name	str	The name of the experiment. Defaults to None.	None
season_name	str	The name of the season. Defaults to None.	None
site_name	str	The name of the site. Defaults to None.	None

Returns: Optional[Plot]: The plot instance, or None if not found.

Source code in gemini/api/plot.py

@classmethod
def get(
    cls,
    plot_number: int,
    plot_row_number: int,
    plot_column_number: int,
    experiment_name: str = None,
    season_name: str = None,
    site_name: str = None,
) -> Optional["Plot"]:
    """
    Retrieve a plot by its parameters.

    Examples:
        >>> plot = Plot.get(plot_number=1, plot_row_number=2, plot_column_number=3)
        >>> print(plot)
        Plot(plot_number=1, plot_row_number=2, plot_column_number=3, id=UUID(...))

    Args:
        plot_number (int): The plot number.
        plot_row_number (int): The row number of the plot.
        plot_column_number (int): The column number of the plot.
        experiment_name (str, optional): The name of the experiment. Defaults to None.
        season_name (str, optional): The name of the season. Defaults to None.
        site_name (str, optional): The name of the site. Defaults to None.
    Returns:
        Optional[Plot]: The plot instance, or None if not found.
    """
    try:
        plot = PlotViewModel.get_by_parameters(
            plot_number=plot_number,
            plot_row_number=plot_row_number,
            plot_column_number=plot_column_number,
            experiment_name=experiment_name,
            season_name=season_name,
            site_name=site_name
        )
        if not plot:
            logger.debug(f"Plot with number {plot_number}, row {plot_row_number}, column {plot_column_number} not found.")
            return None
        plot = cls.model_validate(plot)
        return plot
    except Exception as e:
        logger.error(f"Error getting plot: {e}")
        return None

get_all(limit=None, offset=None) classmethod

Retrieve all plots.

Examples:

>>> plots = Plot.get_all()
>>> for plot in plots:
...     print(plot)
Plot(plot_number=1, plot_row_number=2, plot_column_number=3, id=UUID(...))
Plot(plot_number=2, plot_row_number=3, plot_column_number=4, id=UUID(...))

Returns:

Type	Description
Optional[List[Plot]]	Optional[List[Plot]]: A list of all plots, or None if not found.

Source code in gemini/api/plot.py

@classmethod
def get_all(cls, limit: int = None, offset: int = None) -> Optional[List["Plot"]]:
    """
    Retrieve all plots.

    Examples:
        >>> plots = Plot.get_all()
        >>> for plot in plots:
        ...     print(plot)
        Plot(plot_number=1, plot_row_number=2, plot_column_number=3, id=UUID(...))
        Plot(plot_number=2, plot_row_number=3, plot_column_number=4, id=UUID(...))


    Returns:
        Optional[List[Plot]]: A list of all plots, or None if not found.
    """
    try:
        plots = PlotModel.all(limit=limit, offset=offset)
        if not plots or len(plots) == 0:
            logger.info("No plots found.")
            return None
        plots = [cls.model_validate(plot) for plot in plots]
        return plots
    except Exception as e:
        logger.error(f"Error getting all plots: {e}")
        return None

get_associated_experiment()

Get the experiment associated with this plot.

Examples:

>>> plot = Plot.get_by_id(UUID('...'))
>>> experiment = plot.get_associated_experiment()
>>> print(experiment)
Experiment(experiment_name='Experiment 1', experiment_start_date='2023-01-01', experiment_end_date='2023-12-31', id=UUID(...))

Returns:

Type	Description
Optional[Experiment]	Optional[Experiment]: The associated experiment, or None if not found.

Source code in gemini/api/plot.py

def get_associated_experiment(self) -> Optional["Experiment"]:
    """
    Get the experiment associated with this plot.

    Examples:
        >>> plot = Plot.get_by_id(UUID('...'))
        >>> experiment = plot.get_associated_experiment()
        >>> print(experiment)
        Experiment(experiment_name='Experiment 1', experiment_start_date='2023-01-01', experiment_end_date='2023-12-31', id=UUID(...))

    Returns:
        Optional[Experiment]: The associated experiment, or None if not found.
    """
    try:
        from gemini.api.experiment import Experiment
        if not self.experiment_id:
            logger.info("Plot does not belong to any experiment.")
            return None
        experiment = Experiment.get_by_id(self.experiment_id)
        if not experiment:
            logger.warning(f"Experiment with ID {self.experiment_id} does not exist.")
            return None
        return experiment
    except Exception as e:
        logger.error(f"Error getting experiment: {e}")
        return None

get_associated_season()

Get the season associated with this plot.

Examples:

>>> plot = Plot.get_by_id(UUID('...'))
>>> season = plot.get_associated_season()
>>> print(season)
Season(season_name='Season 1', season_start_date='2023-01-01', season_end_date='2023-12-31', id=UUID(...))

Returns:

Type	Description
Optional[Season]	Optional[Season]: The associated season, or None if not found.

Source code in gemini/api/plot.py

def get_associated_season(self) -> Optional["Season"]:
    """
    Get the season associated with this plot.

    Examples:
        >>> plot = Plot.get_by_id(UUID('...'))
        >>> season = plot.get_associated_season()
        >>> print(season)
        Season(season_name='Season 1', season_start_date='2023-01-01', season_end_date='2023-12-31', id=UUID(...))

    Returns:
        Optional[Season]: The associated season, or None if not found.
    """
    try:
        from gemini.api.season import Season
        if not self.season_id:
            logger.info("Plot does not belong to any season.")
            return None
        season = Season.get_by_id(self.season_id)
        if not season:
            logger.warning(f"Season with ID {self.season_id} does not exist.")
            return None
        return season
    except Exception as e:
        logger.error(f"Error getting season: {e}")
        return None

get_associated_site()

Get the site associated with this plot.

Examples:

>>> plot = Plot.get_by_id(UUID('...'))
>>> site = plot.get_associated_site()
>>> print(site)
Site(site_name='Site 1', id=UUID(...))

Returns:

Type	Description
Optional[Site]	Optional[Site]: The associated site, or None if not found.

Source code in gemini/api/plot.py

def get_associated_site(self) -> Optional["Site"]:
    """
    Get the site associated with this plot.

    Examples:
        >>> plot = Plot.get_by_id(UUID('...'))
        >>> site = plot.get_associated_site()
        >>> print(site)
        Site(site_name='Site 1', id=UUID(...))

    Returns:
        Optional[Site]: The associated site, or None if not found.
    """
    try:
        from gemini.api.site import Site
        if not self.site_id:
            logger.info("Plot does not belong to any site.")
            return None
        site = Site.get_by_id(self.site_id)
        if not site:
            logger.warning(f"Site with ID {self.site_id} does not exist.")
            return None
        return site
    except Exception as e:
        logger.error(f"Error getting site: {e}")
        return None

get_by_id(id) classmethod

Retrieve a plot by its ID.

Examples:

>>> plot = Plot.get_by_id(UUID('...'))
>>> print(plot)
Plot(plot_number=1, plot_row_number=2, plot_column_number=3, id=UUID('...'))

Parameters:

Name	Type	Description	Default
id	UUID | int | str	The ID of the plot.	required

Returns: Optional[Plot]: The plot instance, or None if not found.

Source code in gemini/api/plot.py

@classmethod
def get_by_id(cls, id: UUID | int | str) -> Optional["Plot"]:
    """
    Retrieve a plot by its ID.

    Examples:
        >>> plot = Plot.get_by_id(UUID('...'))
        >>> print(plot)
        Plot(plot_number=1, plot_row_number=2, plot_column_number=3, id=UUID('...'))

    Args:
        id (UUID | int | str): The ID of the plot.
    Returns:
        Optional[Plot]: The plot instance, or None if not found.
    """
    try:
        plot = PlotViewModel.get_by_parameters(plot_id=id)
        if not plot:
            logger.warning(f"Plot with ID {id} does not exist.")
            return None
        plot = cls.model_validate(plot)
        return plot
    except Exception as e:
        logger.error(f"Error getting plot by ID: {e}")
        return None

get_info()

Get the additional information of the plot.

Examples:

>>> plot = Plot.get_by_id(UUID('...'))
>>> plot_info = plot.get_info()
>>> print(plot_info)
{'key': 'value'}

Returns:

Type	Description
Optional[dict]	Optional[dict]: The plot's info, or None if not found.

Source code in gemini/api/plot.py

def get_info(self) -> Optional[dict]:
    """
    Get the additional information of the plot.

    Examples:
        >>> plot = Plot.get_by_id(UUID('...'))
        >>> plot_info = plot.get_info()
        >>> print(plot_info)
        {'key': 'value'}

    Returns:
        Optional[dict]: The plot's info, or None if not found.
    """
    try:
        current_id = self.id
        plot = PlotModel.get(current_id)
        if not plot:
            logger.warning(f"Plot with ID {current_id} does not exist.")
            return None
        plot_info = plot.plot_info
        if not plot_info:
            logger.info("Plot info is empty.")
            return None
        return plot_info
    except Exception as e:
        logger.error(f"Error getting plot info: {e}")
        return None

refresh()

Refresh the plot's data from the database.

Examples:

>>> plot = Plot.get_by_id(UUID('...'))
>>> refreshed_plot = plot.refresh()
>>> print(refreshed_plot)
Plot(plot_number=1, plot_row_number=2, plot_column_number=3, id=UUID('...'))

Returns:

Type	Description
Optional[Plot]	Optional[Plot]: The refreshed plot instance, or None if an error occurred.

Source code in gemini/api/plot.py

def refresh(self) -> Optional["Plot"]:
    """
    Refresh the plot's data from the database.

    Examples:
        >>> plot = Plot.get_by_id(UUID('...'))
        >>> refreshed_plot = plot.refresh()
        >>> print(refreshed_plot)
        Plot(plot_number=1, plot_row_number=2, plot_column_number=3, id=UUID('...'))

    Returns:
        Optional[Plot]: The refreshed plot instance, or None if an error occurred.
    """
    try:
        db_instance = PlotViewModel.get_by_parameters(plot_id=self.id)
        if not db_instance:
            logger.warning(f"Plot with ID {self.id} does not exist.")
            return self
        instance = self.model_validate(db_instance)
        instance_dict = dict(instance)
        for key, value in instance_dict.items():
            if hasattr(self, key) and key != "id":
                value = getattr(instance, key)
                setattr(self, key, value)
        return self
    except Exception as e:
        logger.error(f"Error refreshing plot: {e}")
        return None

set_info(plot_info)

Set the additional information of the plot.

Examples:

>>> plot = Plot.get_by_id(UUID('...'))
>>> updated_plot = plot.set_info({'key': 'new_value'})
>>> print(updated_plot.get_info())
{'key': 'new_value'}

Parameters:

Name	Type	Description	Default
plot_info	dict	The new information to set.	required

Returns: Optional[Plot]: The updated plot instance, or None if an error occurred.

Source code in gemini/api/plot.py

def set_info(self, plot_info: dict) -> Optional["Plot"]:
    """
    Set the additional information of the plot.

    Examples:
        >>> plot = Plot.get_by_id(UUID('...'))
        >>> updated_plot = plot.set_info({'key': 'new_value'})
        >>> print(updated_plot.get_info())
        {'key': 'new_value'}

    Args:
        plot_info (dict): The new information to set.
    Returns:
        Optional[Plot]: The updated plot instance, or None if an error occurred.
    """
    try:
        current_id = self.id
        plot = PlotModel.get(current_id)
        if not plot:
            logger.warning(f"Plot with ID {current_id} does not exist.")
            return None
        plot = PlotModel.update(
            plot,
            plot_info=plot_info
        )
        plot = self.model_validate(plot)
        self.refresh()
        return self
    except Exception as e:
        logger.error(f"Error setting plot info: {e}")  
        return None

unassociate_experiment()

Unassociate this plot from its experiment.

Examples:

>>> plot = Plot.get_by_id(UUID('...'))
>>> experiment = plot.unassociate_experiment()
>>> print(experiment)
Experiment(experiment_name='Experiment 1', experiment_start_date='2023-01-01', experiment_end_date='2023-12-31', id=UUID(...))

Returns:

Type	Description
Optional[Experiment]	Optional[Experiment]: The unassociated experiment, or None if an error occurred.

Source code in gemini/api/plot.py

def unassociate_experiment(self) -> Optional["Experiment"]:
    """
    Unassociate this plot from its experiment.

    Examples:
        >>> plot = Plot.get_by_id(UUID('...'))
        >>> experiment = plot.unassociate_experiment()
        >>> print(experiment)
        Experiment(experiment_name='Experiment 1', experiment_start_date='2023-01-01', experiment_end_date='2023-12-31', id=UUID(...))

    Returns:
        Optional[Experiment]: The unassociated experiment, or None if an error occurred.
    """
    try:
        from gemini.api.experiment import Experiment
        if not self.experiment_id:
            logger.info("Plot does not belong to any experiment.")
            return None
        experiment = Experiment.get_by_id(self.experiment_id)
        db_plot = PlotModel.get(self.id)
        db_plot = PlotModel.update_parameter(
            db_plot,
            "experiment_id",
            None
        )
        self.refresh()
        return experiment   
    except Exception as e:
        logger.error(f"Error unassigning experiment from plot: {e}")
        return None

unassociate_season()

Unassociate this plot from its season.

Examples:

>>> plot = Plot.get_by_id(UUID('...'))
>>> season = plot.unassociate_season()
>>> print(season)
Season(season_name='Season 1', season_start_date='2023-01-01', season_end_date='2023-12-31', id=UUID(...))

Returns:

Type	Description
Optional[Season]	Optional[Season]: The unassociated season, or None if an error occurred.

Source code in gemini/api/plot.py

def unassociate_season(self) -> Optional["Season"]:
    """
    Unassociate this plot from its season.

    Examples:
        >>> plot = Plot.get_by_id(UUID('...'))
        >>> season = plot.unassociate_season()
        >>> print(season)
        Season(season_name='Season 1', season_start_date='2023-01-01', season_end_date='2023-12-31', id=UUID(...))

    Returns:
        Optional[Season]: The unassociated season, or None if an error occurred.
    """
    try:
        from gemini.api.season import Season
        if not self.season_id:
            logger.info("Plot does not belong to any season.")
            return None
        season = Season.get_by_id(self.season_id)
        db_plot = PlotModel.get(self.id)
        db_plot = PlotModel.update_parameter(
            db_plot,
            "season_id",
            None
        )
        self.refresh()
        return season
    except Exception as e:
        logger.error(f"Error unassigning season from plot: {e}")
        return None

unassociate_site()

Unassociate this plot from its site.

Examples:

>>> plot = Plot.get_by_id(UUID('...'))
>>> site = plot.unassociate_site()
>>> print(site)
Site(site_name='Site 1', id=UUID(...))

Returns:

Type	Description
Optional[Site]	Optional[Site]: The unassociated site, or None if an error occurred.

Source code in gemini/api/plot.py

def unassociate_site(self) -> Optional["Site"]:
    """
    Unassociate this plot from its site.

    Examples:
        >>> plot = Plot.get_by_id(UUID('...'))
        >>> site = plot.unassociate_site()
        >>> print(site)
        Site(site_name='Site 1', id=UUID(...))

    Returns:
        Optional[Site]: The unassociated site, or None if an error occurred.
    """
    try:
        from gemini.api.site import Site
        if not self.site_id:
            logger.info("Plot does not belong to any site.")
            return None
        site = Site.get_by_id(self.site_id)
        db_plot = PlotModel.get(self.id)
        db_plot = PlotModel.update_parameter(
            db_plot,
            "site_id",
            None
        )
        self.refresh()
        return site
    except Exception as e:
        logger.error(f"Error unassigning site from plot: {e}")
        return None

update(plot_number=None, plot_row_number=None, plot_column_number=None, plot_info=None, plot_geometry_info=None)

Update the details of the plot.

Examples:

>>> plot = Plot.get_by_id(UUID('...'))
>>> updated_plot = plot.update(plot_number=2, plot_row_number=3)
>>> print(updated_plot)
Plot(plot_number=2, plot_row_number=3, plot_column_number=3, id=UUID('...'))

Parameters:

Name	Type	Description	Default
plot_number	int	The new plot number. Defaults to None.	None
plot_row_number	int	The new row number. Defaults to None.	None
plot_column_number	int	The new column number. Defaults to None.	None
plot_info	dict	The new plot information. Defaults to None.	None
plot_geometry_info	dict	The new geometry information. Defaults to None.	None

Returns: Optional[Plot]: The updated plot instance, or None if an error occurred.

Source code in gemini/api/plot.py

def update(
    self,
    plot_number: int = None,
    plot_row_number: int = None,
    plot_column_number: int = None,
    plot_info: dict = None,
    plot_geometry_info: dict = None
) -> Optional["Plot"]:
    """
    Update the details of the plot.

    Examples:
        >>> plot = Plot.get_by_id(UUID('...'))
        >>> updated_plot = plot.update(plot_number=2, plot_row_number=3)
        >>> print(updated_plot)
        Plot(plot_number=2, plot_row_number=3, plot_column_number=3, id=UUID('...'))

    Args:
        plot_number (int, optional): The new plot number. Defaults to None.
        plot_row_number (int, optional): The new row number. Defaults to None.
        plot_column_number (int, optional): The new column number. Defaults to None.
        plot_info (dict, optional): The new plot information. Defaults to None.
        plot_geometry_info (dict, optional): The new geometry information. Defaults to None.
    Returns:
        Optional[Plot]: The updated plot instance, or None if an error occurred.
    """
    try:
        if not any([plot_number, plot_row_number, plot_column_number, plot_info, plot_geometry_info]):
            logger.warning("At least one parameter must be provided.")
            return None

        current_id = self.id
        plot = PlotModel.get(current_id)
        if not plot:
            logger.warning(f"Plot with ID {current_id} does not exist.")
            return None
        plot = PlotModel.update(
            plot,
            plot_number=plot_number,
            plot_row_number=plot_row_number,
            plot_column_number=plot_column_number,
            plot_info=plot_info,
            plot_geometry_info=plot_geometry_info
        )
        plot = self.model_validate(plot)
        self.refresh()
        return plot
    except Exception as e:
        logger.error(f"Error updating plot: {e}")
        return None