API reference

Core geometry and designs

Planting-site geometry.

The canonical geometry is an arbitrary set of two-dimensional plant coordinates. Rectangles, masks, polygons, GPS-like point sets and other shapes are convenience constructors around that representation.

Source code in src/cropmix/geometry.py

@dataclass(frozen=True)
class Field:
    """Planting-site geometry.

    The canonical geometry is an arbitrary set of two-dimensional plant
    coordinates.  Rectangles, masks, polygons, GPS-like point sets and other
    shapes are convenience constructors around that representation.
    """

    coordinates: np.ndarray
    site_ids: tuple[str, ...] | None = None
    boundary: np.ndarray | None = None
    grid_shape: tuple[int, int] | None = None
    metadata: dict[str, object] = dc_field(default_factory=dict)

    def __post_init__(self) -> None:
        coords = _as_coordinates(self.coordinates)
        object.__setattr__(self, "coordinates", coords)

        if self.site_ids is None:
            ids = tuple(str(i) for i in range(coords.shape[0]))
        else:
            ids = tuple(str(value) for value in self.site_ids)
            if len(ids) != coords.shape[0]:
                raise ValidationError("site_ids must have one entry per coordinate.")
            if len(set(ids)) != len(ids):
                raise ValidationError("site_ids must be unique.")
        object.__setattr__(self, "site_ids", ids)

        if self.boundary is not None:
            boundary = np.asarray(self.boundary, dtype=float)
            if boundary.ndim != 2 or boundary.shape[1] != 2 or len(boundary) < 3:
                raise ValidationError("boundary must have shape (n_vertices, 2), n_vertices >= 3.")
            if not np.isfinite(boundary).all():
                raise ValidationError("boundary coordinates must be finite.")
            boundary.setflags(write=False)
            object.__setattr__(self, "boundary", boundary)

        if self.grid_shape is not None:
            rows, cols = self.grid_shape
            if rows <= 0 or cols <= 0 or rows * cols != self.n_sites:
                raise ValidationError("grid_shape must match the number of sites.")

    @property
    def n_sites(self) -> int:
        return int(self.coordinates.shape[0])

    @property
    def x(self) -> np.ndarray:
        return self.coordinates[:, 0]

    @property
    def y(self) -> np.ndarray:
        return self.coordinates[:, 1]

    @property
    def extent(self) -> tuple[float, float, float, float]:
        return (
            float(self.x.min()),
            float(self.x.max()),
            float(self.y.min()),
            float(self.y.max()),
        )

    def distance_matrix(self) -> np.ndarray:
        delta = self.coordinates[:, None, :] - self.coordinates[None, :, :]
        return np.sqrt(np.sum(delta * delta, axis=2))

    def site_index(self, site_id: str) -> int:
        try:
            return self.site_ids.index(str(site_id))
        except ValueError as exc:
            raise KeyError(f"Unknown site_id: {site_id!r}") from exc

    @classmethod
    def from_coordinates(
        cls,
        coordinates: Iterable[Sequence[float]],
        *,
        site_ids: Sequence[str] | None = None,
        boundary: Iterable[Sequence[float]] | None = None,
        metadata: dict[str, object] | None = None,
    ) -> Field:
        return cls(
            coordinates=np.asarray(list(coordinates), dtype=float),
            site_ids=None if site_ids is None else tuple(site_ids),
            boundary=None if boundary is None else np.asarray(list(boundary), dtype=float),
            metadata={} if metadata is None else dict(metadata),
        )

    @classmethod
    def rectangular(
        cls,
        rows: int,
        columns: int,
        *,
        spacing: float | tuple[float, float] = 1.0,
        origin: tuple[float, float] = (0.0, 0.0),
    ) -> Field:
        if rows <= 0 or columns <= 0:
            raise ValidationError("rows and columns must be positive.")
        if isinstance(spacing, tuple):
            sx, sy = float(spacing[0]), float(spacing[1])
        else:
            sx = sy = float(spacing)
        if sx <= 0 or sy <= 0:
            raise ValidationError("spacing must be positive.")

        ox, oy = map(float, origin)
        coords = np.array(
            [(ox + c * sx, oy + r * sy) for r in range(rows) for c in range(columns)],
            dtype=float,
        )
        boundary = np.array(
            [
                (ox, oy),
                (ox + (columns - 1) * sx, oy),
                (ox + (columns - 1) * sx, oy + (rows - 1) * sy),
                (ox, oy + (rows - 1) * sy),
            ],
            dtype=float,
        )
        return cls(
            coordinates=coords,
            boundary=boundary,
            grid_shape=(rows, columns),
            metadata={"constructor": "rectangular", "spacing": (sx, sy)},
        )

    @classmethod
    def from_mask(
        cls,
        mask: np.ndarray,
        *,
        spacing: float | tuple[float, float] = 1.0,
        origin: tuple[float, float] = (0.0, 0.0),
    ) -> Field:
        mask = np.asarray(mask, dtype=bool)
        if mask.ndim != 2:
            raise ValidationError("mask must be two-dimensional.")
        if not mask.any():
            raise ValidationError("mask must contain at least one True cell.")
        if isinstance(spacing, tuple):
            sx, sy = map(float, spacing)
        else:
            sx = sy = float(spacing)
        if sx <= 0 or sy <= 0:
            raise ValidationError("spacing must be positive.")
        ox, oy = map(float, origin)
        coords = []
        ids = []
        for r, c in zip(*np.where(mask), strict=False):
            coords.append((ox + c * sx, oy + r * sy))
            ids.append(f"r{r}c{c}")
        return cls(
            coordinates=np.asarray(coords),
            site_ids=tuple(ids),
            metadata={"constructor": "mask", "mask_shape": tuple(mask.shape), "spacing": (sx, sy)},
        )

    @classmethod
    def from_polygon(
        cls,
        boundary: Iterable[Sequence[float]],
        *,
        spacing: float | tuple[float, float] = 1.0,
        origin: tuple[float, float] | None = None,
    ) -> Field:
        """Generate a regular planting lattice clipped to an arbitrary polygon.

        For already surveyed planting positions, prefer :meth:`from_coordinates`.
        """
        polygon = np.asarray(list(boundary), dtype=float)
        if polygon.ndim != 2 or polygon.shape[1] != 2 or len(polygon) < 3:
            raise ValidationError("boundary must contain at least three 2D vertices.")
        if isinstance(spacing, tuple):
            sx, sy = map(float, spacing)
        else:
            sx = sy = float(spacing)
        if sx <= 0 or sy <= 0:
            raise ValidationError("spacing must be positive.")

        xmin, ymin = polygon.min(axis=0)
        xmax, ymax = polygon.max(axis=0)
        if origin is None:
            ox, oy = float(xmin), float(ymin)
        else:
            ox, oy = map(float, origin)

        xs = np.arange(ox, xmax + sx * 0.5, sx)
        ys = np.arange(oy, ymax + sy * 0.5, sy)
        coords = [(x, y) for y in ys for x in xs if _point_in_polygon((x, y), polygon)]
        if not coords:
            raise ValidationError("No planting sites fall inside the polygon at the requested spacing.")
        return cls(
            coordinates=np.asarray(coords, dtype=float),
            boundary=polygon,
            metadata={"constructor": "polygon", "spacing": (sx, sy)},
        )

`from_polygon(boundary, *, spacing=1.0, origin=None)` `classmethod`

Generate a regular planting lattice clipped to an arbitrary polygon.

For already surveyed planting positions, prefer :meth:from_coordinates.

Source code in src/cropmix/geometry.py

@classmethod
def from_polygon(
    cls,
    boundary: Iterable[Sequence[float]],
    *,
    spacing: float | tuple[float, float] = 1.0,
    origin: tuple[float, float] | None = None,
) -> Field:
    """Generate a regular planting lattice clipped to an arbitrary polygon.

    For already surveyed planting positions, prefer :meth:`from_coordinates`.
    """
    polygon = np.asarray(list(boundary), dtype=float)
    if polygon.ndim != 2 or polygon.shape[1] != 2 or len(polygon) < 3:
        raise ValidationError("boundary must contain at least three 2D vertices.")
    if isinstance(spacing, tuple):
        sx, sy = map(float, spacing)
    else:
        sx = sy = float(spacing)
    if sx <= 0 or sy <= 0:
        raise ValidationError("spacing must be positive.")

    xmin, ymin = polygon.min(axis=0)
    xmax, ymax = polygon.max(axis=0)
    if origin is None:
        ox, oy = float(xmin), float(ymin)
    else:
        ox, oy = map(float, origin)

    xs = np.arange(ox, xmax + sx * 0.5, sx)
    ys = np.arange(oy, ymax + sy * 0.5, sy)
    coords = [(x, y) for y in ys for x in xs if _point_in_polygon((x, y), polygon)]
    if not coords:
        raise ValidationError("No planting sites fall inside the polygon at the requested spacing.")
    return cls(
        coordinates=np.asarray(coords, dtype=float),
        boundary=polygon,
        metadata={"constructor": "polygon", "spacing": (sx, sy)},
    )

Assign exactly one named variety to every planting site.

Source code in src/cropmix/design.py

@dataclass(frozen=True)
class MixtureDesign:
    """Assign exactly one named variety to every planting site."""

    field: Field
    assignment: tuple[str, ...]

    def __post_init__(self) -> None:
        assignment = tuple(str(x) for x in self.assignment)
        if len(assignment) != self.field.n_sites:
            raise ValidationError(
                f"assignment has {len(assignment)} labels but field has {self.field.n_sites} sites."
            )
        if any(not name.strip() for name in assignment):
            raise ValidationError("Variety labels cannot be empty.")
        object.__setattr__(self, "assignment", assignment)

    @property
    def n_sites(self) -> int:
        return self.field.n_sites

    @property
    def varieties(self) -> tuple[str, ...]:
        return tuple(sorted(set(self.assignment)))

    @property
    def counts(self) -> dict[str, int]:
        return dict(Counter(self.assignment))

    @property
    def proportions(self) -> dict[str, float]:
        return {name: count / self.n_sites for name, count in self.counts.items()}

    def variety_indices(self, variety: str) -> np.ndarray:
        return np.flatnonzero(np.asarray(self.assignment, dtype=object) == variety)

    def as_grid(self) -> np.ndarray:
        if self.field.grid_shape is None:
            raise ValidationError("This field has no complete rectangular grid_shape.")
        return np.asarray(self.assignment, dtype=object).reshape(self.field.grid_shape)

    def to_dataframe(self) -> pd.DataFrame:
        return pd.DataFrame(
            {
                "site_id": self.field.site_ids,
                "x": self.field.x,
                "y": self.field.y,
                "variety": self.assignment,
            }
        )

    def swapped(self, first: int, second: int) -> MixtureDesign:
        if not (0 <= first < self.n_sites and 0 <= second < self.n_sites):
            raise IndexError("Swap indices are outside the field.")
        values = list(self.assignment)
        values[first], values[second] = values[second], values[first]
        return MixtureDesign(self.field, tuple(values))

    def plot(self, ax=None, *, marker_size: float = 80, legend: bool = True):
        """Plot the planting assignment. Requires the optional `viz` extra."""
        try:
            import matplotlib.pyplot as plt
        except ImportError as exc:  # pragma: no cover - optional dependency
            raise ImportError("Install plotting support with `pip install cropmix[viz]`.") from exc

        if ax is None:
            _, ax = plt.subplots()
        for variety in self.varieties:
            idx = self.variety_indices(variety)
            ax.scatter(self.field.x[idx], self.field.y[idx], s=marker_size, label=variety)
        if self.field.boundary is not None:
            boundary = np.vstack([self.field.boundary, self.field.boundary[0]])
            ax.plot(boundary[:, 0], boundary[:, 1], linewidth=1)
        ax.set_aspect("equal", adjustable="box")
        ax.set_xlabel("x")
        ax.set_ylabel("y")
        if legend:
            ax.legend()
        return ax

    @classmethod
    def monoculture(cls, field: Field, variety: str) -> MixtureDesign:
        return cls(field=field, assignment=tuple([variety] * field.n_sites))

    @classmethod
    def random(
        cls,
        field: Field,
        counts: Mapping[str, int],
        *,
        seed: int | None = None,
    ) -> MixtureDesign:
        counts = {str(name): int(count) for name, count in counts.items()}
        if any(count < 0 for count in counts.values()):
            raise ValidationError("Variety counts cannot be negative.")
        if sum(counts.values()) != field.n_sites:
            raise ValidationError(
                f"Counts sum to {sum(counts.values())}, but field has {field.n_sites} sites."
            )
        values: list[str] = []
        for name, count in counts.items():
            values.extend([name] * count)
        rng = np.random.default_rng(seed)
        rng.shuffle(values)
        return cls(field=field, assignment=tuple(values))

    @classmethod
    def from_grid(cls, grid: Sequence[Sequence[str]], *, spacing: float = 1.0) -> MixtureDesign:
        array = np.asarray(grid, dtype=object)
        if array.ndim != 2:
            raise ValidationError("grid must be two-dimensional.")
        field = Field.rectangular(array.shape[0], array.shape[1], spacing=spacing)
        return cls(field=field, assignment=tuple(str(x) for x in array.ravel()))

    @classmethod
    def from_dataframe(
        cls,
        dataframe: pd.DataFrame,
        *,
        x: str = "x",
        y: str = "y",
        variety: str = "variety",
        site_id: str | None = "site_id",
    ) -> MixtureDesign:
        required = [x, y, variety]
        missing = [column for column in required if column not in dataframe.columns]
        if missing:
            raise ValidationError(f"Missing columns: {missing}")
        ids = None
        if site_id is not None and site_id in dataframe.columns:
            ids = tuple(dataframe[site_id].astype(str))
        field = Field.from_coordinates(
            dataframe[[x, y]].to_numpy(float),
            site_ids=ids,
        )
        return cls(field=field, assignment=tuple(dataframe[variety].astype(str)))

`plot(ax=None, *, marker_size=80, legend=True)`

Plot the planting assignment. Requires the optional viz extra.

Source code in src/cropmix/design.py

def plot(self, ax=None, *, marker_size: float = 80, legend: bool = True):
    """Plot the planting assignment. Requires the optional `viz` extra."""
    try:
        import matplotlib.pyplot as plt
    except ImportError as exc:  # pragma: no cover - optional dependency
        raise ImportError("Install plotting support with `pip install cropmix[viz]`.") from exc

    if ax is None:
        _, ax = plt.subplots()
    for variety in self.varieties:
        idx = self.variety_indices(variety)
        ax.scatter(self.field.x[idx], self.field.y[idx], s=marker_size, label=variety)
    if self.field.boundary is not None:
        boundary = np.vstack([self.field.boundary, self.field.boundary[0]])
        ax.plot(boundary[:, 0], boundary[:, 1], linewidth=1)
    ax.set_aspect("equal", adjustable="box")
    ax.set_xlabel("x")
    ax.set_ylabel("y")
    if legend:
        ax.legend()
    return ax