Skip to content

MaidenheadPandas module

MaidenheadPandas

Source code in vgridpandas/maidenheadpandas.py 
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
@pd.api.extensions.register_dataframe_accessor("maidenhead")
class MaidenheadPandas:
    def __init__(self, df: DataFrame):
        self._df = df

    # maidenhead API
    # These methods simply mirror the Vgrid maidenhead API and apply maidenhead functions to all rows

    def latlon2maidenhead(
        self,
        resolution: int,
        lat_col: str = "lat",
        lon_col: str = "lon",
        set_index: bool = False,
    ) -> AnyDataFrame:
        """Adds maidenhead ID to (Geo)DataFrame.

        pd.DataFrame: uses `lat_col` and `lon_col` (default `lat` and `lon`)
        gpd.GeoDataFrame: uses `geometry`

        Assumes coordinates in epsg=4326.

        Parameters
        ----------
        resolution : int
            maidenhead resolution
        lat_col : str
            Name of the latitude column (if used), default 'lat'
        lon_col : str
            Name of the longitude column (if used), default 'lon'
        set_index : bool
            If True, the columns with maidenhead ID is set as index, default 'True'

        Returns
        -------
        (Geo)DataFrame with maidenhead IDs added
        """

        if not isinstance(resolution, int) or resolution not in range(1, 5):
            raise ValueError("Resolution must be an integer in range [1, 4]")

        if isinstance(self._df, gpd.GeoDataFrame):
            lons = self._df.geometry.x
            lats = self._df.geometry.y
        else:
            lons = self._df[lon_col]
            lats = self._df[lat_col]

        maidenhead_ids = [
            latlon_to_maidenhead(lat, lon, resolution) for lat, lon in zip(lats, lons)
        ]

        # maidenhead_col = self._format_resolution(resolution)
        maidenhead_col = MAIDENHEAD_COL
        assign_arg = {maidenhead_col: maidenhead_ids, f"{maidenhead_col}_res": resolution}
        df = self._df.assign(**assign_arg)
        if set_index:
            return df.set_index(maidenhead_col)
        return df

    def maidenhead2geo(self, maidenhead_col: str = None) -> GeoDataFrame:
        """Add geometry with MAIDENHEAD geometry to the DataFrame."""
        if maidenhead_col is not None:
            if maidenhead_col not in self._df.columns:
                raise ValueError(f"Column '{maidenhead_col}' not found in DataFrame")
            ids = self._df[maidenhead_col]
        else:
            if MAIDENHEAD_COL not in self._df.columns:
                raise ValueError(f"Column '{MAIDENHEAD_COL}' not found in DataFrame")
            ids = self._df[MAIDENHEAD_COL]
        return dggs_ids_to_geodataframe(self._df, ids, maidenhead_to_geo)

    def linetrace(self, resolution: int, explode: bool = False) -> AnyDataFrame:
        """Maidenhead cell representation of a (Multi)LineString traced along its vertices.

        Uses the same walk as ``vgrid.conversion.vector2dggs.vector2maidenhead.polyline2maidenhead``.
        """
        result = self._df.apply(
            lambda row: list(linetrace(row.geometry, resolution)), axis=1
        )
        if not explode:
            return self._df.assign(**{MAIDENHEAD_COL: result})
        result = result.explode().to_frame(MAIDENHEAD_COL)
        return self._df.join(result)

    def maidenheadbin(
        self,
        resolution: int,
        agg: str = "count",
        numeric_col: str = None,
        category_col: str = None,
        lat_col: str = "lat",
        lon_col: str = "lon",
    ) -> GeoDataFrame:
        """
        Bin points into maidenhead cells and compute statistics.
        """
        maidenhead_col = MAIDENHEAD_COL
        df = self.latlon2maidenhead(resolution, lat_col, lon_col)
        result = aggregate_bin(df, maidenhead_col, agg, numeric_col, category_col)
        return result.maidenhead.maidenhead2geo(maidenhead_col=maidenhead_col)

latlon2maidenhead(resolution, lat_col='lat', lon_col='lon', set_index=False)

Adds maidenhead ID to (Geo)DataFrame.

pd.DataFrame: uses lat_col and lon_col (default lat and lon) gpd.GeoDataFrame: uses geometry

Assumes coordinates in epsg=4326.

Parameters

resolution : int maidenhead resolution lat_col : str Name of the latitude column (if used), default 'lat' lon_col : str Name of the longitude column (if used), default 'lon' set_index : bool If True, the columns with maidenhead ID is set as index, default 'True'

Returns

(Geo)DataFrame with maidenhead IDs added

Source code in vgridpandas/maidenheadpandas.py 
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
def latlon2maidenhead(
    self,
    resolution: int,
    lat_col: str = "lat",
    lon_col: str = "lon",
    set_index: bool = False,
) -> AnyDataFrame:
    """Adds maidenhead ID to (Geo)DataFrame.

    pd.DataFrame: uses `lat_col` and `lon_col` (default `lat` and `lon`)
    gpd.GeoDataFrame: uses `geometry`

    Assumes coordinates in epsg=4326.

    Parameters
    ----------
    resolution : int
        maidenhead resolution
    lat_col : str
        Name of the latitude column (if used), default 'lat'
    lon_col : str
        Name of the longitude column (if used), default 'lon'
    set_index : bool
        If True, the columns with maidenhead ID is set as index, default 'True'

    Returns
    -------
    (Geo)DataFrame with maidenhead IDs added
    """

    if not isinstance(resolution, int) or resolution not in range(1, 5):
        raise ValueError("Resolution must be an integer in range [1, 4]")

    if isinstance(self._df, gpd.GeoDataFrame):
        lons = self._df.geometry.x
        lats = self._df.geometry.y
    else:
        lons = self._df[lon_col]
        lats = self._df[lat_col]

    maidenhead_ids = [
        latlon_to_maidenhead(lat, lon, resolution) for lat, lon in zip(lats, lons)
    ]

    # maidenhead_col = self._format_resolution(resolution)
    maidenhead_col = MAIDENHEAD_COL
    assign_arg = {maidenhead_col: maidenhead_ids, f"{maidenhead_col}_res": resolution}
    df = self._df.assign(**assign_arg)
    if set_index:
        return df.set_index(maidenhead_col)
    return df

linetrace(resolution, explode=False)

Maidenhead cell representation of a (Multi)LineString traced along its vertices.

Uses the same walk as vgrid.conversion.vector2dggs.vector2maidenhead.polyline2maidenhead.

Source code in vgridpandas/maidenheadpandas.py 
 97
 98
 99
100
101
102
103
104
105
106
107
108
def linetrace(self, resolution: int, explode: bool = False) -> AnyDataFrame:
    """Maidenhead cell representation of a (Multi)LineString traced along its vertices.

    Uses the same walk as ``vgrid.conversion.vector2dggs.vector2maidenhead.polyline2maidenhead``.
    """
    result = self._df.apply(
        lambda row: list(linetrace(row.geometry, resolution)), axis=1
    )
    if not explode:
        return self._df.assign(**{MAIDENHEAD_COL: result})
    result = result.explode().to_frame(MAIDENHEAD_COL)
    return self._df.join(result)

maidenhead2geo(maidenhead_col=None)

Add geometry with MAIDENHEAD geometry to the DataFrame.

Source code in vgridpandas/maidenheadpandas.py 
85
86
87
88
89
90
91
92
93
94
95
def maidenhead2geo(self, maidenhead_col: str = None) -> GeoDataFrame:
    """Add geometry with MAIDENHEAD geometry to the DataFrame."""
    if maidenhead_col is not None:
        if maidenhead_col not in self._df.columns:
            raise ValueError(f"Column '{maidenhead_col}' not found in DataFrame")
        ids = self._df[maidenhead_col]
    else:
        if MAIDENHEAD_COL not in self._df.columns:
            raise ValueError(f"Column '{MAIDENHEAD_COL}' not found in DataFrame")
        ids = self._df[MAIDENHEAD_COL]
    return dggs_ids_to_geodataframe(self._df, ids, maidenhead_to_geo)

maidenheadbin(resolution, agg='count', numeric_col=None, category_col=None, lat_col='lat', lon_col='lon')

Bin points into maidenhead cells and compute statistics.

Source code in vgridpandas/maidenheadpandas.py 
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
def maidenheadbin(
    self,
    resolution: int,
    agg: str = "count",
    numeric_col: str = None,
    category_col: str = None,
    lat_col: str = "lat",
    lon_col: str = "lon",
) -> GeoDataFrame:
    """
    Bin points into maidenhead cells and compute statistics.
    """
    maidenhead_col = MAIDENHEAD_COL
    df = self.latlon2maidenhead(resolution, lat_col, lon_col)
    result = aggregate_bin(df, maidenhead_col, agg, numeric_col, category_col)
    return result.maidenhead.maidenhead2geo(maidenhead_col=maidenhead_col)

linetrace(geometry, resolution)

Trace a (Multi)LineString with Maidenhead cells (same walk as polyline2maidenhead).

Source code in vgridpandas/maidenheadpandas.py 
18
19
20
21
22
def linetrace(geometry: MultiLineOrLine, resolution: int) -> Iterator[str]:
    """Trace a (Multi)LineString with Maidenhead cells (same walk as ``polyline2maidenhead``)."""
    rows = polyline2maidenhead(geometry, resolution, include_properties=False)
    for row in rows:
        yield row[MAIDENHEAD_COL]