pygeokit 0.1.0__tar.gz

pygeokit-0.1.0/LICENSE

@@ -0,0 +1,25 @@
+MIT License
+
+Copyright (c) 2026 A. Osinkin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+The bundled data files (src/pygeokit/data) are derived from GeoNames
+(https://www.geonames.org) and are licensed under CC BY 4.0
+(https://creativecommons.org/licenses/by/4.0/).

pygeokit-0.1.0/PKG-INFO

@@ -0,0 +1,95 @@
+Metadata-Version: 2.4
+Name: pygeokit
+Version: 0.1.0
+Summary: Offline geo features from lat/lon: country, cities, capitals, city types, distances, density, city structure
+Author: A. Osinkin
+License-Expression: MIT
+Keywords: geo,features,geonames,machine learning,latitude,longitude
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: pandas
+Requires-Dist: scipy
+Requires-Dist: scikit-learn
+Provides-Extra: h3
+Requires-Dist: h3; extra == "h3"
+Dynamic: license-file
+
+# pygeokit
+
+Offline geo features from latitude / longitude for tabular ML: country, nearest and
+main city, capitals, city types and sizes, distances, density of neighbours, ring /
+sector / multi-core city structure, grids, and a few urban-economics formulas
+(Reilly, Huff, Zipf). The city data is bundled, so nothing is downloaded at run time.
+
+```
+pip install pygeokit
+```
+
+Depends only on `numpy`, `pandas`, `scipy`, `scikit-learn`. `h3` is optional (`hex_cell`).
+
+## Quick start
+
+```python
+import pygeokit as gk
+
+gk.help()                                   # cheat sheet (in Russian)
+
+X, cat = gk.make_X(df, "lat", "lon")        # ready matrix + categorical columns
+model = CatBoostRegressor(cat_features=cat).fit(X, y)
+
+feats = gk.get_features(df, lat_col="lat", lon_col="lon")   # reference features only
+
+gk.get_country(55.75, 37.62)                # 'RU'
+gk.get_capital("RU")                        # {'name': 'Moscow', 'lat': ..., ...}
+gk.get_main_city(lat, lon)                  # biggest city within 60 km
+gk.get_city_type(lat, lon)                  # capital / region_center / ... + size class
+gk.haversine(lat1, lon1, lat2, lon2)        # km
+```
+
+## What is inside
+
+| Group | Functions |
+|---|---|
+| Ready matrix for CatBoost | `make_X`, `cat_columns` |
+| Everything at once | `get_features` |
+| Cities and countries | `get_country`, `get_country_info`, `get_capital`, `get_nearest_city`, `get_main_city`, `get_city_type`, `dist_to_capital`, `load_cities`, `load_countries` |
+| Distances | `haversine`, `manhattan`, `bearing`, `to_km`, `travel_minutes` |
+| Your own points | `dist_to_nearest`, `count_within` |
+| Density / neighbours | `neighbor_features`, `oof_neighbor_features` (leak-free target stats) |
+| City structure | `find_centers`, `center_features`, `multi_center_features`, `city_shape` (ring / sector / multi-core heuristic) |
+| Grids and validation | `grid_cell`, `hex_cell`, `spatial_groups`, `group_stats` |
+| Urban economics | `city_gravity`, `huff_probabilities`, `reilly_breakpoint`, `zipf_expected` |
+
+`city_type` comes from the GeoNames feature code: `PPLC` capital, `PPLA` region
+center, `PPLA2` district center, `PPLA3/4/5` local center, `PPLX` city section,
+everything else settlement. `size_class`: tiny < 10k, small < 50k, medium < 100k,
+big < 250k, large < 1M, million.
+
+`get_country` returns the country of the nearest city, so points right on a border
+or far out at sea can get the neighbouring country.
+
+## Leak-free neighbour target features
+
+```python
+tr_f = gk.oof_neighbor_features(train.lat, train.lon, y)                 # train rows
+te_f = gk.neighbor_features(test.lat, test.lon, train.lat, train.lon, values=y)
+```
+
+## Building from source
+
+The data files are not stored in the repository. Build them once:
+
+```
+python tools/build_data.py      # downloads GeoNames dumps (~12 MB)
+python -m pytest tests          # tests use a tiny fake data set
+python -m build
+```
+
+Set `PYGEOKIT_DATA_DIR` to use your own data directory.
+
+## Data and license
+
+Code: MIT. City and country data: [GeoNames](https://www.geonames.org), licensed
+under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/).

pygeokit-0.1.0/README.md

@@ -0,0 +1,77 @@
+# pygeokit
+
+Offline geo features from latitude / longitude for tabular ML: country, nearest and
+main city, capitals, city types and sizes, distances, density of neighbours, ring /
+sector / multi-core city structure, grids, and a few urban-economics formulas
+(Reilly, Huff, Zipf). The city data is bundled, so nothing is downloaded at run time.
+
+```
+pip install pygeokit
+```
+
+Depends only on `numpy`, `pandas`, `scipy`, `scikit-learn`. `h3` is optional (`hex_cell`).
+
+## Quick start
+
+```python
+import pygeokit as gk
+
+gk.help()                                   # cheat sheet (in Russian)
+
+X, cat = gk.make_X(df, "lat", "lon")        # ready matrix + categorical columns
+model = CatBoostRegressor(cat_features=cat).fit(X, y)
+
+feats = gk.get_features(df, lat_col="lat", lon_col="lon")   # reference features only
+
+gk.get_country(55.75, 37.62)                # 'RU'
+gk.get_capital("RU")                        # {'name': 'Moscow', 'lat': ..., ...}
+gk.get_main_city(lat, lon)                  # biggest city within 60 km
+gk.get_city_type(lat, lon)                  # capital / region_center / ... + size class
+gk.haversine(lat1, lon1, lat2, lon2)        # km
+```
+
+## What is inside
+
+| Group | Functions |
+|---|---|
+| Ready matrix for CatBoost | `make_X`, `cat_columns` |
+| Everything at once | `get_features` |
+| Cities and countries | `get_country`, `get_country_info`, `get_capital`, `get_nearest_city`, `get_main_city`, `get_city_type`, `dist_to_capital`, `load_cities`, `load_countries` |
+| Distances | `haversine`, `manhattan`, `bearing`, `to_km`, `travel_minutes` |
+| Your own points | `dist_to_nearest`, `count_within` |
+| Density / neighbours | `neighbor_features`, `oof_neighbor_features` (leak-free target stats) |
+| City structure | `find_centers`, `center_features`, `multi_center_features`, `city_shape` (ring / sector / multi-core heuristic) |
+| Grids and validation | `grid_cell`, `hex_cell`, `spatial_groups`, `group_stats` |
+| Urban economics | `city_gravity`, `huff_probabilities`, `reilly_breakpoint`, `zipf_expected` |
+
+`city_type` comes from the GeoNames feature code: `PPLC` capital, `PPLA` region
+center, `PPLA2` district center, `PPLA3/4/5` local center, `PPLX` city section,
+everything else settlement. `size_class`: tiny < 10k, small < 50k, medium < 100k,
+big < 250k, large < 1M, million.
+
+`get_country` returns the country of the nearest city, so points right on a border
+or far out at sea can get the neighbouring country.
+
+## Leak-free neighbour target features
+
+```python
+tr_f = gk.oof_neighbor_features(train.lat, train.lon, y)                 # train rows
+te_f = gk.neighbor_features(test.lat, test.lon, train.lat, train.lon, values=y)
+```
+
+## Building from source
+
+The data files are not stored in the repository. Build them once:
+
+```
+python tools/build_data.py      # downloads GeoNames dumps (~12 MB)
+python -m pytest tests          # tests use a tiny fake data set
+python -m build
+```
+
+Set `PYGEOKIT_DATA_DIR` to use your own data directory.
+
+## Data and license
+
+Code: MIT. City and country data: [GeoNames](https://www.geonames.org), licensed
+under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/).

pygeokit-0.1.0/pyproject.toml

@@ -0,0 +1,24 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pygeokit"
+version = "0.1.0"
+description = "Offline geo features from lat/lon: country, cities, capitals, city types, distances, density, city structure"
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{name = "A. Osinkin"}]
+keywords = ["geo", "features", "geonames", "machine learning", "latitude", "longitude"]
+dependencies = ["numpy", "pandas", "scipy", "scikit-learn"]
+
+[project.optional-dependencies]
+h3 = ["h3"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+pygeokit = ["data/*.csv", "data/*.csv.gz"]

pygeokit-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

pygeokit-0.1.0/src/pygeokit/__init__.py

@@ -0,0 +1,19 @@
+"""pygeokit - offline geo features from latitude / longitude.
+
+    import pygeokit as gk
+    gk.help()                       # cheat sheet
+    feats = gk.get_features(df, lat_col="lat", lon_col="lon")
+"""
+from ._help import help
+from .core import (
+    bearing, cat_columns, center_features, city_shape, city_gravity, count_within, dist_to_capital,
+    dist_to_nearest, find_centers, get_capital, get_city_type, get_country,
+    get_country_info, get_features, get_main_city, get_nearest_city, grid_cell,
+    group_stats, haversine, hex_cell, huff_probabilities, load_cities,
+    load_countries, make_X, manhattan, multi_center_features, neighbor_features,
+    oof_neighbor_features, reilly_breakpoint, spatial_groups, to_km,
+    travel_minutes, zipf_expected,
+)
+
+__version__ = "0.1.0"
+__all__ = [n for n in dir() if not n.startswith("_")]

pygeokit-0.1.0/src/pygeokit/_help.py

@@ -0,0 +1,83 @@
+HELP = r"""
+pygeokit  -  шпаргалка            import pygeokit as gk;  gk.help()
+Везде: lat = широта, lon = долгота (в градусах). Принимаются числа, массивы, Series.
+Расстояния в км. Подробности по функции: help(gk.get_features)
+
+== ГОТОВЫЙ X ДЛЯ CATBOOST ==================================================
+X_tr, cat = gk.make_X(train.drop(columns=["target"]), "lat", "lon")
+X_te, _   = gk.make_X(test, "lat", "lon", ref=train)   # плотность считать по train
+model = CatBoostRegressor(cat_features=cat).fit(X_tr, y)
+  возвращает ДВЕ вещи: X и список категориальных колонок.
+  X = копия твоего X + все гео-признаки (справочник, положение в городе,
+  ячейки сетки, плотность точек). Таргет не используется, утечки нет.
+
+== ВСЁ СРАЗУ (только справочные признаки) ==================================
+feats = gk.get_features(df, lat_col="lat", lon_col="lon")   # ~30 признаков
+df = pd.concat([df, feats], axis=1)
+  страна, регион, ближайший город, главный город рядом (население, тип, размер,
+  ранг в стране), расстояния до столицы / центра региона / города 100к / 1 млн,
+  число городов и население в 10/50/100 км, "притяжение" крупных городов.
+  Текстовые колонки -> в cat_features CatBoost.
+
+== СПРАВОЧНИК ГОРОДОВ И СТРАН =============================================
+gk.get_country(lat, lon)            -> 'RU'            (код страны)
+gk.get_country_info('RU')           -> dict (столица, население, площадь, ...)
+gk.get_capital('RU')                -> dict name/lat/lon/population
+gk.get_nearest_city(lat, lon, min_population=0, k=1, types=None)
+gk.get_main_city(lat, lon, radius_km=60)   # самый крупный город в радиусе
+gk.get_city_type(lat, lon)          -> city_type + size_class
+     city_type : capital / region_center / district_center / local_center /
+                 settlement / city_section
+     size_class: tiny <10k, small <50k, medium <100k, big <250k, large <1M, million
+gk.dist_to_capital(lat, lon)
+gk.load_cities(min_population=0), gk.load_countries()      # сырые таблицы
+
+== РАССТОЯНИЯ =============================================================
+gk.haversine(lat1, lon1, lat2, lon2)   # км по сфере
+gk.manhattan(...)                      # "по кварталам"
+gk.bearing(...)                        # направление, 0=север, 90=восток
+gk.to_km(lat, lon)                     # -> x,y в км (для KMeans/HDBSCAN/евклида)
+gk.travel_minutes(km, mode="walk")     # walk 5 км/ч, bike 15, car 30
+     15-минутный город: пешком 15 мин ~ 1.25 км
+
+== СВОИ ТОЧКИ (метро, магазины, конкуренты) ===============================
+gk.dist_to_nearest(lat, lon, ref_lat, ref_lon, k=1)
+gk.count_within(lat, lon, ref_lat, ref_lon, radius_km=1.25)
+
+== ПЛОТНОСТЬ И СОСЕДИ =====================================================
+gk.neighbor_features(lat, lon)                       # сколько точек рядом
+gk.neighbor_features(lat, lon, ref_lat, ref_lon, values=v)   # + sum/mean/std v
+  !!! если values = таргет:
+tr_f = gk.oof_neighbor_features(tr.lat, tr.lon, y)           # трейн, без утечки
+te_f = gk.neighbor_features(te.lat, te.lon, tr.lat, tr.lon, values=y)   # тест
+
+== УСТРОЙСТВО ГОРОДА (кольца / секторы / несколько ядер) ==================
+c = gk.find_centers(lat, lon, weight=turnover, n_centers=3)   # ядра по данным
+gk.center_features(lat, lon, c.lat[0], c.lon[0])   # расстояние, кольцо, сектор
+gk.multi_center_features(lat, lon, c)              # до каждого ядра + ближайшее
+  центр из справочника:  m = gk.get_main_city(lat, lon)
+                         gk.center_features(lat, lon, m.lat.values, m.lon.values)
+
+  тип города из лекции (кольцевой / секторный / несколько ядер), ЭВРИСТИКА:
+gk.city_shape(lat, lon, weight=None, group=city_id)   # строка на город:
+     shape = ring / sector / multi_core + elongation, core2_ratio, core_sep, ...
+
+== СЕТКИ И ВАЛИДАЦИЯ ======================================================
+gk.grid_cell(lat, lon, size_km=1)      # id квадрата -> категориальный признак
+gk.hex_cell(lat, lon, res=8)           # H3 (нужен pip install h3)
+gk.spatial_groups(lat, lon, size_km=50)  # groups для GroupKFold
+gk.group_stats(df, by="cell", value="amount")   # n, sum, mean(ср. чек), median...
+
+== ЭКОНОМИКА ГОРОДОВ ======================================================
+gk.city_gravity(lat, lon)                    # притяжение крупных городов
+gk.huff_probabilities(dist, attractiveness)  # вероятность выбрать каждый центр
+gk.reilly_breakpoint(dist_ab, pop_a, pop_b)  # граница зон притяжения A и B
+gk.zipf_expected(largest_pop, rank)          # закон Ципфа: pop = max / rank
+
+Данные: GeoNames (geonames.org), лицензия CC BY 4.0.
+"""
+
+
+def help():
+    """Print the cheat sheet (in Russian)."""
+    print(HELP)