{ "cells": [ { "cell_type": "markdown", "id": "5212af16", "metadata": {}, "source": [ "# Simulating random point patterns with `pointpats.random`\n", "\n", "This notebook illustrates how to use the `pointpats.random` module to simulate\n", "random point patterns inside a study region (the *hull*).\n", "\n", "We will look at several families of random patterns:\n", "\n", "1. **Homogeneous Poisson** (`random.poisson`)\n", "2. **Normal cluster** (`random.normal`)\n", "3. **Poisson cluster (Neyman–Scott)** (`random.cluster_poisson`)\n", "4. **Normal cluster with random seeds** (`random.cluster_normal`)\n", "\n", "All examples use a simple square window as the hull:\n", "\n", "$$[0, 1] \\times [0, 1].$$\n" ] }, { "cell_type": "code", "execution_count": null, "id": "6003346e", "metadata": {}, "outputs": [], "source": [ "import matplotlib.pyplot as plt\n", "import numpy as np\n", "\n", "from pointpats import random as ppr # pointpats.random\n", "\n", "# Make results reproducible\n", "np.random.seed(12345)\n", "\n", "# Define a simple square hull as a bounding box:\n", "# [xmin, ymin, xmax, ymax]\n", "hull = np.array([0.0, 0.0, 1.0, 1.0])\n", "\n", "hull" ] }, { "cell_type": "markdown", "id": "11dc1585", "metadata": {}, "source": [ "## Helper function for plotting point patterns\n", "\n", "We'll use a small helper to visualize realizations of the random point processes." ] }, { "cell_type": "code", "execution_count": null, "id": "fd2889cf", "metadata": {}, "outputs": [], "source": [ "def plot_pattern(points, hull, ax=None, title=None):\n", " \"\"\"Plot a 2D point pattern inside a rectangular hull.\n", "\n", " Parameters\n", " ----------\n", " points : array-like, shape (n_points, 2)\n", " Coordinates of the points.\n", " hull : array-like, shape (4,)\n", " Bounding box [xmin, ymin, xmax, ymax].\n", " ax : matplotlib.axes.Axes, optional\n", " Axis to plot on.\n", " title : str, optional\n", " Title for the plot.\n", " \"\"\"\n", " points = np.asarray(points)\n", "\n", " if ax is None:\n", " fig, ax = plt.subplots(figsize=(4, 4))\n", "\n", " xmin, ymin, xmax, ymax = hull\n", " ax.scatter(points[:, 0], points[:, 1], s=10, alpha=0.7)\n", " ax.set_xlim(xmin, xmax)\n", " ax.set_ylim(ymin, ymax)\n", " ax.set_aspect(\"equal\", adjustable=\"box\")\n", " ax.set_xlabel(\"x\")\n", " ax.set_ylabel(\"y\")\n", " if title:\n", " ax.set_title(title)\n", "\n", " return ax" ] }, { "cell_type": "markdown", "id": "f05bca84", "metadata": {}, "source": [ "## 1. Homogeneous Poisson process (`random.poisson`)\n", "\n", "The **homogeneous Poisson point process** is the canonical model of\n", "*complete spatial randomness* (CSR):\n", "\n", "- Each point is independently and uniformly distributed in the hull.\n", "- The expected number of points is controlled by the **intensity**\n", " (points per unit area).\n", "\n", "A typical interface (check the installed `pointpats` version for details) allows usage patterns like:\n", "\n", "- `poisson(hull, size=n)` — simulate `n` points once.\n", "- `poisson(hull, intensity=lambda_, size=r)` — draw `r` *replications* from a Poisson\n", " process with intensity `lambda_` points per unit area.\n" ] }, { "cell_type": "code", "execution_count": null, "id": "870559d8", "metadata": {}, "outputs": [], "source": [ "# A single realization with exactly 100 points\n", "points_poisson_fixed = ppr.poisson(hull, size=100)\n", "\n", "points_poisson_fixed.shape" ] }, { "cell_type": "code", "execution_count": null, "id": "bb7f6f94", "metadata": {}, "outputs": [], "source": [ "fig, ax = plt.subplots(figsize=(4, 4))\n", "plot_pattern(\n", " points_poisson_fixed, hull, ax=ax, title=\"Homogeneous Poisson process (n = 100)\"\n", ")\n", "plt.show()" ] }, { "cell_type": "code", "execution_count": null, "id": "0ac04ea4", "metadata": {}, "outputs": [], "source": [ "# Simulate 4 replications with intensity λ = 200 points per unit area\n", "lambda_ = 200 # expected number of points in unit square\n", "n_replications = 4\n", "\n", "points_poisson_intensity = ppr.poisson(hull, intensity=lambda_, size=n_replications)\n", "\n", "points_poisson_intensity.shape" ] }, { "cell_type": "code", "execution_count": null, "id": "b0e48b36", "metadata": {}, "outputs": [], "source": [ "fig, axes = plt.subplots(2, 2, figsize=(6, 6))\n", "\n", "for i, ax in enumerate(axes.ravel()):\n", " plot_pattern(\n", " points_poisson_intensity[i],\n", " hull,\n", " ax=ax,\n", " title=f\"Poisson, λ={lambda_}, rep {i + 1}\",\n", " )\n", "\n", "plt.tight_layout()\n", "plt.show()" ] }, { "cell_type": "markdown", "id": "ff89ebf4", "metadata": {}, "source": [ "## 2. Normal cluster (`random.normal`)\n", "\n", "`random.normal` simulates points from a **bivariate normal distribution**\n", "truncated to the hull.\n", "\n", "A typical interface looks like:\n", "\n", "```python\n", "ppr.normal(hull, center=None, cov=None, size=None)\n", "```\n", "\n", "Key arguments:\n", "\n", "- `center`: 2D location of the cluster center. If `None`, often the centroid of the hull.\n", "- `cov`: covariance structure (scalar = iid variance, or 2×2 matrix).\n", "- `size`: number of points (and optionally replications).\n", "\n", "We'll start with a single tight cluster in the center of the window." ] }, { "cell_type": "code", "execution_count": null, "id": "c34bfe45", "metadata": {}, "outputs": [], "source": [ "# 200 points in a single bivariate normal cluster\n", "points_normal = ppr.normal(hull, size=200)\n", "\n", "points_normal.shape" ] }, { "cell_type": "code", "execution_count": null, "id": "7fbf7901", "metadata": {}, "outputs": [], "source": [ "fig, ax = plt.subplots(figsize=(4, 4))\n", "plot_pattern(\n", " points_normal, hull, ax=ax, title=\"Normal cluster (default center & spread)\"\n", ")\n", "plt.show()" ] }, { "cell_type": "code", "execution_count": null, "id": "a58f6a59", "metadata": {}, "outputs": [], "source": [ "# Three different covariance structures\n", "covariances = [\n", " 0.05, # scalar: isotropic variance\n", " np.array([[0.05, 0.0], [0.0, 0.01]]), # elongated along x\n", " np.array([[0.01, 0.0], [0.0, 0.05]]), # elongated along y\n", "]\n", "\n", "fig, axes = plt.subplots(1, 3, figsize=(12, 4))\n", "\n", "for cov, ax in zip(covariances, axes, strict=True):\n", " pts = ppr.normal(hull, size=300, cov=cov)\n", " plot_pattern(pts, hull, ax=ax, title=f\"cov =\\n{cov}\")\n", "\n", "plt.tight_layout()\n", "plt.show()" ] }, { "cell_type": "markdown", "id": "f74ce910", "metadata": {}, "source": [ "## 3. Poisson cluster process (`random.cluster_poisson`)\n", "\n", "`cluster_poisson` implements a simple **Neyman–Scott**–type cluster process:\n", "\n", "1. \"Seed\" points are drawn from a Poisson process.\n", "2. Around each seed, a small cloud of points is placed within a radius.\n", "\n", "A typical use looks like:\n", "\n", "```python\n", "ppr.cluster_poisson(\n", " hull,\n", " intensity=None,\n", " size=None,\n", " n_seeds=2,\n", " cluster_radius=None,\n", ")\n", "```\n", "\n", "Key arguments:\n", "\n", "- `n_seeds`: number of cluster centers.\n", "- `cluster_radius`: radius of each cluster. If `None`, it may default to a value\n", " based on distances between seeds.\n", "- `size`: controls how many points you simulate in total and how many replications.\n", "\n", "Here we simulate 300 points organized into a few clusters." ] }, { "cell_type": "code", "execution_count": null, "id": "f1137841", "metadata": {}, "outputs": [], "source": [ "n_points = 300\n", "n_replications = 1\n", "n_seeds = 4\n", "\n", "points_cluster_poisson = ppr.cluster_poisson(\n", " hull,\n", " size=(n_points, n_replications),\n", " n_seeds=n_seeds,\n", " # cluster_radius can be None (default) or a scalar / array\n", ")\n", "\n", "points_cluster_poisson.shape" ] }, { "cell_type": "code", "execution_count": null, "id": "3601664c", "metadata": {}, "outputs": [], "source": [ "fig, ax = plt.subplots(figsize=(4, 4))\n", "plot_pattern(\n", " points_cluster_poisson,\n", " hull,\n", " ax=ax,\n", " title=f\"Poisson cluster process (n={n_points}, seeds={n_seeds})\",\n", ")\n", "plt.show()" ] }, { "cell_type": "markdown", "id": "b43e4bc9", "metadata": {}, "source": [ "## 4. Normal clusters with random seeds (`random.cluster_normal`)\n", "\n", "`cluster_normal` builds clusters whose centers are themselves drawn from a\n", "Poisson process, but the points within clusters are drawn from a **normal**\n", "distribution around each seed:\n", "\n", "```python\n", "ppr.cluster_normal(hull, cov=None, size=None, n_seeds=2)\n", "```\n", "\n", "- `cov` controls the within-cluster spread.\n", "- `n_seeds` controls how many clusters you get.\n", "- `size` controls total number of points and replications.\n" ] }, { "cell_type": "code", "execution_count": null, "id": "7baf7061", "metadata": {}, "outputs": [], "source": [ "n_points = 300\n", "n_replications = 1\n", "n_seeds = 5\n", "\n", "points_cluster_normal = ppr.cluster_normal(\n", " hull,\n", " size=(n_points, n_replications),\n", " n_seeds=n_seeds,\n", " # cov=None, # uses a default based on distances between seeds\n", ")\n", "\n", "points_cluster_normal.shape" ] }, { "cell_type": "code", "execution_count": null, "id": "2d02eb84", "metadata": {}, "outputs": [], "source": [ "fig, ax = plt.subplots(figsize=(4, 4))\n", "plot_pattern(\n", " points_cluster_normal,\n", " hull,\n", " ax=ax,\n", " title=f\"Normal cluster process (n={n_points}, seeds={n_seeds})\",\n", ")\n", "plt.show()" ] }, { "cell_type": "markdown", "id": "f21340aa", "metadata": {}, "source": [ "## Recap\n", "\n", "In this notebook we have:\n", "\n", "- Used `pointpats.random.poisson` to simulate homogeneous Poisson\n", " point patterns under complete spatial randomness.\n", "- Used `pointpats.random.normal` to generate truncated bivariate normal clusters.\n", "- Used `pointpats.random.cluster_poisson` for Poisson cluster processes\n", " (Neyman–Scott–like).\n", "- Used `pointpats.random.cluster_normal` for clustered patterns with\n", " normally distributed clusters.\n", "\n", "These simulated patterns are useful as:\n", "\n", "- **Null models** for hypothesis testing (e.g., against observed patterns).\n", "- **Toy data** for teaching, examples, and algorithm development.\n", "\n", "You can adapt the hull, intensities, and covariance structures to match\n", "your own study regions and applications." ] } ], "metadata": { "kernelspec": { "display_name": "Python 3 (ipykernel)", "language": "python", "name": "python3" }, "language_info": { "codemirror_mode": { "name": "ipython", "version": 3 }, "file_extension": ".py", "mimetype": "text/x-python", "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", "version": "3.14.3" } }, "nbformat": 4, "nbformat_minor": 5 }