Skip to content

GitLab

Commit 611ebfa6 authored by Joseph Siddons's avatar Joseph Siddons
Browse files

Merge "main" into "10-improve-documentation"

parent 8e9bae21
Pipeline #267678 failed with stages
in 38 seconds
Hide whitespace changes
Inline Side-by-side
Showing with 46 additions and 25 deletions
GeoSpatialTools/octtree.py
View file @ 611ebfa6
"""
Constuctors for OctTree classes that can decrease the number of comparisons
Constructors for OctTree classes that can decrease the number of comparisons
for detecting nearby records for example. This is an implementation that uses
Haversine distances for comparisons between records for identification of
neighbours.
......
GeoSpatialTools/quadtree.py
View file @ 611ebfa6
"""
Constuctors for QuadTree classes that can decrease the number of comparisons
Constructors for QuadTree classes that can decrease the number of comparisons
for detecting nearby records for example. This is an implementation that uses
Haversine distances for comparisons between records for identification of
neighbours.
......
GeoSpatialTools/record.py
View file @ 611ebfa6
......@@ -11,7 +11,7 @@ Classes prefixed by "SpaceTime" include a temporal dimension and should be used
with OctTree classes.
"""
from typing import List, Optional
from typing import Optional
from datetime import datetime
from .utils import LatitudeError
from .distance_metrics import haversine
......
docs/Documentation.pdf
View file @ 611ebfa6
No preview for this file type
docs/Documentation.tex
View file @ 611ebfa6
......@@ -64,7 +64,7 @@
\title{GeoSpatialTools}
\date{Mar 07, 2025}
\date{Mar 14, 2025}
\release{0.11.2}
\author{NOC Surface Processes}
\newcommand{\sphinxlogo}{\vbox{}}
......@@ -1236,7 +1236,7 @@ time\sphinxhyphen{}complexity of these query operations is \(O(\log(n))\), the s
\sphinxAtStartPar
Typically, it is assumed that the data uses a cartesian coordinate system, so comparisons between boundaries and query
shapes utilise cartesian geometry and euclidean distances. The implementation of Quadtree within this library, the
\sphinxcode{\sphinxupquote{QuadTree}} class, utilises the Haversine distance as a metric for indentifying records within the queried region.
\sphinxcode{\sphinxupquote{QuadTree}} class, utilises the Haversine distance as a metric for identifying records within the queried region.
This allows the Quadtree to account for the spherical geometry of the Earth. Boundary checks with query regions also
account for the wrapping of longitude at \sphinxhyphen{}180, 180 degrees.
......@@ -1244,7 +1244,7 @@ account for the wrapping of longitude at \sphinxhyphen{}180, 180 degrees.
The \sphinxcode{\sphinxupquote{QuadTree}} object is defined by a bounding box, i.e. boundaries at the western, eastern, southern, and northern edges of
the data that will be inserted into the \sphinxcode{\sphinxupquote{QuadTree}}. Additionally, a capacity and maximum depth can be provided. If the
capacity is exceeded whilst inserting records the \sphinxcode{\sphinxupquote{QuadTree}} will divide and new records will be inserted into the appropriate
child \sphinxcode{\sphinxupquote{QuadTree}}. The maxium depth is the maximum height of the \sphinxcode{\sphinxupquote{QuadTree}}, if capacity is also specified then this will be
child \sphinxcode{\sphinxupquote{QuadTree}}. The maximum depth is the maximum height of the \sphinxcode{\sphinxupquote{QuadTree}}, if capacity is also specified then this will be
overridden if the \sphinxcode{\sphinxupquote{QuadTree}} is at this depth, and the \sphinxcode{\sphinxupquote{QuadTree}} will not divide.
......@@ -1326,7 +1326,7 @@ with a \sphinxcode{\sphinxupquote{Ellipse}} using \sphinxcode{\sphinxupquote{Qua
\section{quadtree Module}
\label{\detokenize{quadtree:module-GeoSpatialTools.quadtree}}\label{\detokenize{quadtree:quadtree-module}}\index{module@\spxentry{module}!GeoSpatialTools.quadtree@\spxentry{GeoSpatialTools.quadtree}}\index{GeoSpatialTools.quadtree@\spxentry{GeoSpatialTools.quadtree}!module@\spxentry{module}}
\sphinxAtStartPar
Constuctors for QuadTree classes that can decrease the number of comparisons
Constructors for QuadTree classes that can decrease the number of comparisons
for detecting nearby records for example. This is an implementation that uses
Haversine distances for comparisons between records for identification of
neighbours.
......@@ -1584,14 +1584,14 @@ divisions are at the longitude midpoint, the latitude midpoint, and the datetime
\sphinxAtStartPar
The implementation of Octtree within this library, the \sphinxcode{\sphinxupquote{OctTree}} class, utilises the Haversine distance as a metric
for indentifying records within the queried region. This allows the Octtree to account for the spherical geometry of the
for identifying records within the queried region. This allows the Octtree to account for the spherical geometry of the
Earth. Boundary checks with query regions also account for the wrapping of longitude at \sphinxhyphen{}180, 180 degrees.
\sphinxAtStartPar
The \sphinxcode{\sphinxupquote{OctTree}} object is defined by a bounding box in space and time, i.e. boundaries at the western, eastern,
southern, and northern edges as well as the start and end datetimes of the data that will be inserted into the \sphinxcode{\sphinxupquote{OctTree}}.
Additionally, a capacity and maximum depth can be provided. If the capacity is exceeded whilst inserting records the
\sphinxcode{\sphinxupquote{OctTree}} will divide and new records will be inserted into the appropriate child \sphinxcode{\sphinxupquote{OctTree}}. The maxium depth is the
\sphinxcode{\sphinxupquote{OctTree}} will divide and new records will be inserted into the appropriate child \sphinxcode{\sphinxupquote{OctTree}}. The maximum depth is the
maximum height of the \sphinxcode{\sphinxupquote{OctTree}}, if capacity is also specified then this will be overridden if the \sphinxcode{\sphinxupquote{OctTree}} is at this
depth, and the \sphinxcode{\sphinxupquote{OctTree}} will not divide.
......@@ -1695,7 +1695,7 @@ with a \sphinxcode{\sphinxupquote{SpaceTimeEllipse}} using \sphinxcode{\sphinxup
\section{octtree Module}
\label{\detokenize{octtree:module-GeoSpatialTools.octtree}}\label{\detokenize{octtree:octtree-module}}\index{module@\spxentry{module}!GeoSpatialTools.octtree@\spxentry{GeoSpatialTools.octtree}}\index{GeoSpatialTools.octtree@\spxentry{GeoSpatialTools.octtree}!module@\spxentry{module}}
\sphinxAtStartPar
Constuctors for OctTree classes that can decrease the number of comparisons
Constructors for OctTree classes that can decrease the number of comparisons
for detecting nearby records for example. This is an implementation that uses
Haversine distances for comparisons between records for identification of
neighbours.
......@@ -2076,7 +2076,7 @@ A Haverine distance implementation of a balanced KDTree.
\sphinxAtStartPar
This implementation is a \_balanced\_ KDTree, each leaf node should have the
same number of points (or differ by 1 depending on the number of points
the KDTree is intialised with).
the KDTree is initialised with).
\sphinxAtStartPar
The KDTree partitions in each of the lon and lat dimensions alternatively
......@@ -2095,7 +2095,7 @@ internally.
\item {}
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{max\_depth}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} The maximium depth of the KDTree. The leaf nodes will have depth no
\sphinxstyleliteralstrong{\sphinxupquote{max\_depth}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} The maximum depth of the KDTree. The leaf nodes will have depth no
larger than this value. Leaf nodes will not be created if there is
only 1 point in the branch.
......@@ -2388,7 +2388,7 @@ Get lon, and lat from cartesian coordinates.
\sphinxlineitem{Return type}
\sphinxAtStartPar
\DUrole{sphinx_autodoc_typehints-type}{\sphinxcode{\sphinxupquote{tuple}}{[}\sphinxcode{\sphinxupquote{float}}, \sphinxcode{\sphinxupquote{float}}{]}}
\DUrole{sphinx_autodoc_typehints-type}{\sphinxcode{\sphinxupquote{Tuple}}{[}\sphinxcode{\sphinxupquote{float}}, \sphinxcode{\sphinxupquote{float}}{]}}
\sphinxlineitem{Returns}
\sphinxAtStartPar
......@@ -2713,7 +2713,7 @@ Utility functions. Including Error classes and Warnings.
{\sphinxbfcode{\sphinxupquote{\DUrole{k}{exception}\DUrole{w}{ }}}\sphinxcode{\sphinxupquote{GeoSpatialTools.utils.}}\sphinxbfcode{\sphinxupquote{DateWarning}}}
\pysigstopsignatures
\sphinxAtStartPar
Warnning for Datetime Value
Warning for Datetime Value
\end{fulllineitems}
......
docs/octtree.rst
View file @ 611ebfa6
......@@ -12,13 +12,13 @@ Whilst the Quadtree divides into 4 children after the capacity is reached, the O
divisions are at the longitude midpoint, the latitude midpoint, and the datetime midpoint of the boundary.
The implementation of Octtree within this library, the ``OctTree`` class, utilises the Haversine distance as a metric
for indentifying records within the queried region. This allows the Octtree to account for the spherical geometry of the
for identifying records within the queried region. This allows the Octtree to account for the spherical geometry of the
Earth. Boundary checks with query regions also account for the wrapping of longitude at -180, 180 degrees.
The ``OctTree`` object is defined by a bounding box in space and time, i.e. boundaries at the western, eastern,
southern, and northern edges as well as the start and end datetimes of the data that will be inserted into the ``OctTree``.
Additionally, a capacity and maximum depth can be provided. If the capacity is exceeded whilst inserting records the
``OctTree`` will divide and new records will be inserted into the appropriate child ``OctTree``. The maxium depth is the
``OctTree`` will divide and new records will be inserted into the appropriate child ``OctTree``. The maximum depth is the
maximum height of the ``OctTree``, if capacity is also specified then this will be overridden if the ``OctTree`` is at this
depth, and the ``OctTree`` will not divide.
......
docs/quadtree.rst
View file @ 611ebfa6
......@@ -15,14 +15,14 @@ time-complexity of these query operations is :math:`O(\log(n))`, the space-compl
Typically, it is assumed that the data uses a cartesian coordinate system, so comparisons between boundaries and query
shapes utilise cartesian geometry and euclidean distances. The implementation of Quadtree within this library, the
``QuadTree`` class, utilises the Haversine distance as a metric for indentifying records within the queried region.
``QuadTree`` class, utilises the Haversine distance as a metric for identifying records within the queried region.
This allows the Quadtree to account for the spherical geometry of the Earth. Boundary checks with query regions also
account for the wrapping of longitude at -180, 180 degrees.
The ``QuadTree`` object is defined by a bounding box, i.e. boundaries at the western, eastern, southern, and northern edges of
the data that will be inserted into the ``QuadTree``. Additionally, a capacity and maximum depth can be provided. If the
capacity is exceeded whilst inserting records the ``QuadTree`` will divide and new records will be inserted into the appropriate
child ``QuadTree``. The maxium depth is the maximum height of the ``QuadTree``, if capacity is also specified then this will be
child ``QuadTree``. The maximum depth is the maximum height of the ``QuadTree``, if capacity is also specified then this will be
overridden if the ``QuadTree`` is at this depth, and the ``QuadTree`` will not divide.
Documentation
......
notebooks/octtree.ipynb
View file @ 611ebfa6
......@@ -68,7 +68,12 @@
"N = 16_000\n",
"lons = pl.int_range(-180, 180, eager=True)\n",
"lats = pl.int_range(-90, 90, eager=True)\n",
"dates = pl.datetime_range(datetime(1900, 1, 1, 0), datetime(1900, 1, 31, 23), interval=\"1h\", eager=True)\n",
"dates = pl.datetime_range(\n",
" datetime(1900, 1, 1, 0),\n",
" datetime(1900, 1, 31, 23),\n",
" interval=\"1h\",\n",
" eager=True,\n",
")\n",
"\n",
"lons_use = lons.sample(N, with_replacement=True).alias(\"lon\")\n",
"lats_use = lats.sample(N, with_replacement=True).alias(\"lat\")\n",
......@@ -102,7 +107,11 @@
"# _df[\"lat\"].shuffle(),\n",
"# _df[\"datetime\"].shuffle(),\n",
"# _df[\"uid\"].shuffle(),\n",
"# ]).with_columns(pl.concat_str([pl.col(\"uid\"), pl.lit(f\"{i:03d}\")]).alias(\"uid\"))\n",
"# ]).with_columns(\n",
"# pl.concat_str(\n",
"# [pl.col(\"uid\"), pl.lit(f\"{i:03d}\")]\n",
"# ).alias(\"uid\")\n",
"# )\n",
"# df = df.vstack(df2)\n",
"# df.shape\n",
"# df"
......@@ -113,7 +122,7 @@
"id": "c7bd16e0-96a6-426b-b00a-7c3b8a2aaddd",
"metadata": {},
"source": [
"## Intialise the OctTree Object"
"## Initialise the OctTree Object"
]
},
{
......@@ -123,7 +132,13 @@
"metadata": {},
"outputs": [],
"source": [
"otree = OctTree(Rectangle(-180, 180, -90, 90, datetime(1900, 1, 1, 0), datetime(1900, 1, 31, 23)), capacity = 10, max_depth = 25)"
"otree = OctTree(\n",
" Rectangle(\n",
" -180, 180, -90, 90, datetime(1900, 1, 1, 0), datetime(1900, 1, 31, 23)\n",
" ),\n",
" capacity=10,\n",
" max_depth=25,\n",
")"
]
},
{
......@@ -284,13 +299,19 @@
"metadata": {},
"outputs": [],
"source": [
"dts = pl.datetime_range(datetime(1900, 1, 1), datetime(1900, 2, 1), interval=\"1h\", eager=True, closed=\"left\")\n",
"dts = pl.datetime_range(\n",
" datetime(1900, 1, 1),\n",
" datetime(1900, 2, 1),\n",
" interval=\"1h\",\n",
" eager=True,\n",
" closed=\"left\",\n",
")\n",
"N = dts.len()\n",
"lons = 180 - 360 * np.random.rand(N)\n",
"lats = 90 - 180 * np.random.rand(N)\n",
"lats = 90 - 180 * np.random.rand(N)\n",
"test_df = pl.DataFrame({\"lon\": lons, \"lat\": lats, \"datetime\": dts})\n",
"test_recs = [Record(*r) for r in test_df.rows()]\n",
"dt = timedelta(days = 1)\n",
"dt = timedelta(days=1)\n",
"dist = 350"
]
},
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment