leaf_engine.utils ================= .. py:module:: leaf_engine.utils Submodules ---------- .. toctree:: :maxdepth: 1 /autoapi/leaf_engine/utils/batch/index /autoapi/leaf_engine/utils/excel/index /autoapi/leaf_engine/utils/h3/index /autoapi/leaf_engine/utils/maps/index /autoapi/leaf_engine/utils/s3/index /autoapi/leaf_engine/utils/shapely/index /autoapi/leaf_engine/utils/stats/index /autoapi/leaf_engine/utils/uuid/index Attributes ---------- .. autoapisummary:: leaf_engine.utils.DISTANCE_UNITS leaf_engine.utils.EARTH_RADIUS_IN_MILES leaf_engine.utils.GEOMETRY_ROUNDING_PRECISION leaf_engine.utils.H3_POLYFILL_BUFFER leaf_engine.utils.H3_RESOLUTION Functions --------- .. autoapisummary:: leaf_engine.utils.geometry_to_h3_indices leaf_engine.utils.geometry_to_lat_lon leaf_engine.utils.get_geometry_diameter leaf_engine.utils.get_polygon_diameter leaf_engine.utils.get_ulid leaf_engine.utils.get_uuid leaf_engine.utils.h3_index_to_geometry leaf_engine.utils.h3_index_to_lat_lon leaf_engine.utils.h3_indices_to_geometry leaf_engine.utils.haversine leaf_engine.utils.is_uuid leaf_engine.utils.lat_lon_to_geometry leaf_engine.utils.lat_lon_to_h3_index leaf_engine.utils.mode leaf_engine.utils.points_to_geometry leaf_engine.utils.polygon_to_h3_indices leaf_engine.utils.round_geometry leaf_engine.utils.union_geometries Package Contents ---------------- .. py:function:: geometry_to_h3_indices(geometry: Union[str, shapely.geometry.Polygon], resolution: int = H3_RESOLUTION) -> Iterable .. py:function:: geometry_to_lat_lon(geometry_string: str) -> tuple Returns a lat-lon tuple from a geometry string. :param geometry_string: Geometry string. :type geometry_string: str :returns: Lat-lon tuple. :rtype: tuple .. py:function:: get_geometry_diameter(geometry: str) -> float Computes the maximum distance between any two points in a geometry string. :param geometry: Shapely Polygon string. :type geometry: str :returns: Maximum distance between geometry points. :rtype: float .. py:function:: get_polygon_diameter(polygon: shapely.geometry.Polygon) -> float Computes the maximum distance between any two points in a Polygon. :param polygon: Shapely polygon. :type polygon: Polygon :returns: Maximum distance between polygon points. :rtype: float .. py:function:: get_ulid(*args) -> str Returns ULID for arbitrary set of arguments. ULIDs are computed as a timestamp encoding + some random bytes. See here for more info: https://blog.daveallie.com/ulid-primary-keys. Calling this function with the same arguments returns the same ULID value. Attempts to implement ULID as currently implemented in Postgres - see here: https://bitbucket.org/leaflogistics/migrations/src/production/archive/setup/extensions/generate_ulid.sql ``` SELECT (lpad(to_hex(floor(extract(epoch FROM clock_timestamp()) * 1000)::bigint), 12, '0') || encode(gen_random_bytes(10), 'hex'))::uuid; ``` :returns: ULID string. :rtype: str .. py:function:: get_uuid(*args) -> str Generates a random UUID4. lru_cache decorator makes calls with the same args return the same UUID. Args must be hashable. >>> get_uuid(1, "a") >>> df[column].apply(get_uuid, 'RANDOM_ARG') .. py:function:: h3_index_to_geometry(h3_index: str, as_string=False) -> Union[str, shapely.geometry.Polygon] .. py:function:: h3_index_to_lat_lon(h3_index: str) -> Tuple[float, float] .. py:function:: h3_indices_to_geometry(indices: Iterable, as_string: bool = False) -> Union[str, shapely.geometry.Polygon] Converts a set of H3 indices to shapely Polygon or WKT. Raises an exception if the conversion produces a MultiPolygon instead of contiguous Polygon. :param indices: Set of H3 indices. :type indices: Iterable :param as_string: Return WKT instead of Polygon object. Defaults to False. :type as_string: bool, optional :returns: Polygon or WKT. :rtype: Union[str, Polygon] .. py:function:: haversine(a, b) Computes the great circle distance between two points. :param a: [lon,lat] :param b: [lon,lat] :returns: Distance in miles between a,b .. py:function:: is_uuid(value: Union[str, uuid.UUID], version=4) -> bool Returns True if value is valid UUID. :param value: String or UUID object. :type value: Union[str, uuid.UUID] :param version: UUID version. Defaults to 4. :type version: int, optional :returns: Value is UUID. :rtype: bool .. py:function:: lat_lon_to_geometry(lat: float, lon: float) -> str .. py:function:: lat_lon_to_h3_index(lat: float, lon: float, resolution=H3_RESOLUTION) -> str .. py:function:: mode(series: pandas.Series) -> Any Returns the mode of a Series as a single value. :param series: Series of values. :type series: pd.Series :returns: Most frequent value, if multiple values have the same frequency, the first one in natural sorting order. :rtype: Any .. py:function:: points_to_geometry(lat_lon_records: Iterable) -> shapely.geometry.Polygon Converts lat-lon tuples to (x, y) euclidean coordinate pairs. :param lat_lon_records: Iterable of lat-lon tuples. :type lat_lon_records: Iterable :returns: Convex hull of polygon described by points. :rtype: Polygon .. py:function:: polygon_to_h3_indices(polygon: shapely.geometry.Polygon, resolution=H3_RESOLUTION) .. py:function:: round_geometry(geometry_string: str, rounding_precision: int = GEOMETRY_ROUNDING_PRECISION) -> str Rounds geometry coordinates to 5 decimal places. This reduces the size of geometry strings and makes them usable as spatial indices when comparing them to geometries returned by the analytics API. This is necessary because geometries returned by the API have lower precision than the geometries we work with here. Note that this does NOT simplify the geometries (i.e., it does not reduce the number of points in the geometry), just reduces unnecessary precision in point coordinates. The @lru_cache decorator is used to cache calls to this functions in-memory. .. py:function:: union_geometries(geometries: List[str], rounding_precision: int = GEOMETRY_ROUNDING_PRECISION) -> str .. py:data:: DISTANCE_UNITS :value: 'miles' .. py:data:: EARTH_RADIUS_IN_MILES :value: 3961.0 .. py:data:: GEOMETRY_ROUNDING_PRECISION :value: 5 .. py:data:: H3_POLYFILL_BUFFER .. py:data:: H3_RESOLUTION :value: 5