0
# GeoPandas
1

2
GeoPandas is a comprehensive Python library that extends pandas functionality to handle geographic and geospatial data operations. It provides GeoSeries and GeoDataFrame classes as subclasses of pandas Series and DataFrame, enabling users to work with shapely geometry objects and perform geometric operations directly within the familiar pandas data manipulation framework.
3

4
## Package Information
5

6
- **Package Name**: geopandas
7
- **Language**: Python  
8
- **Installation**: `pip install geopandas`
9
- **Documentation**: https://geopandas.org
10

11
## Core Imports
12

13
```python
14
import geopandas as gpd
15
```
16

17
Common imports for working with geometry data:
18

19
```python
20
import geopandas as gpd
21
import pandas as pd
22
from shapely.geometry import Point, Polygon, LineString
23
```
24

25
## Basic Usage
26

27
```python
28
import geopandas as gpd
29
import pandas as pd
30
from shapely.geometry import Point
31

32
# Create a GeoDataFrame from points
33
geometry = [Point(xy) for xy in zip([-1, 0, 1], [1, 0, -1])]
34
df = pd.DataFrame({'City': ['City A', 'City B', 'City C']})
35
gdf = gpd.GeoDataFrame(df, geometry=geometry)
36

37
# Read geospatial data from file
38
world = gpd.read_file(gpd.datasets.get_path('naturalearth_lowres'))
39
cities = gpd.read_file(gpd.datasets.get_path('naturalearth_cities'))
40

41
# Basic geospatial operations
42
world_area = world.geometry.area
43
world_centroid = world.geometry.centroid
44
world_bounds = world.total_bounds
45

46
# Coordinate reference system transformations
47
world_utm = world.to_crs('EPSG:3857')  # Web Mercator projection
48

49
# Spatial joins
50
cities_in_countries = gpd.sjoin(cities, world, how='left', predicate='within')
51

52
# Create a simple plot
53
world.plot(figsize=(10, 6))
54
```
55

56
## Architecture
57

58
GeoPandas extends the pandas ecosystem with geospatial capabilities:
59

60
- **GeoDataFrame**: Main data structure extending pandas DataFrame with geometry column support and spatial operations
61
- **GeoSeries**: Series-like structure for holding geometry objects with spatial methods and properties
62
- **GeometryArray**: Extension array for efficient storage and manipulation of geometry data
63
- **CRS (Coordinate Reference System)**: Management of spatial reference systems and coordinate transformations
64
- **Spatial Index**: Performance optimization for spatial queries using spatial indexing
65

66
This design provides seamless integration with pandas workflows while adding comprehensive geospatial functionality through shapely geometric objects, coordinate system management, and spatial file I/O capabilities.
67

68
## Capabilities
69

70
### Core Data Structures
71

72
GeoDataFrame and GeoSeries classes that extend pandas functionality with geometry column support, spatial properties, and coordinate reference system management.
73

74
```python { .api }
75
class GeoDataFrame(DataFrame):
76
    def __init__(data=None, index=None, columns=None, dtype=None, copy=None, geometry=None, crs=None): ...
77
    
78
class GeoSeries(Series):
79
    def __init__(data=None, index=None, crs=None, **kwargs): ...
80
```
81

82
[Core Data Structures](./core-data-structures.md)
83

84
### File I/O Operations
85

86
Reading and writing various geospatial file formats including Shapefile, GeoJSON, GeoPackage, Parquet, and database connections.
87

88
```python { .api }
89
def read_file(filename, **kwargs): ...
90
def read_parquet(path, **kwargs): ...
91
def read_feather(path, **kwargs): ...
92
def read_postgis(sql, con, **kwargs): ...
93
def list_layers(filename): ...
94
```
95

96
[File I/O Operations](./file-io.md)
97

98
### Coordinate Reference Systems
99

100
CRS management and coordinate transformations enabling work with different spatial reference systems and projections.
101

102
```python { .api }
103
def set_crs(crs, allow_override=False, inplace=False): ...
104
def to_crs(crs, **kwargs): ...
105
def estimate_utm_crs(datum_name='WGS 84'): ...
106
```
107

108
[Coordinate Reference Systems](./coordinate-systems.md)
109

110
### Geometric Operations
111

112
Spatial analysis and geometric computations including buffering, simplification, area calculations, and spatial predicates.
113

114
```python { .api }
115
def buffer(distance, resolution=16, **kwargs): ...
116
def simplify(tolerance, preserve_topology=True): ...
117
def area(): ...
118
def length(): ...
119
def centroid(): ...
120
def boundary(): ...
121
def convex_hull(): ...
122
def envelope(): ...
123
```
124

125
[Geometric Operations](./geometric-operations.md)
126

127
### Spatial Relationships
128

129
Spatial joins, overlays, and relationship testing between geometric objects including intersection, union, and containment operations.
130

131
```python { .api }
132
def sjoin(left_df, right_df, how='inner', predicate='intersects', lsuffix='left', rsuffix='right', **kwargs): ...
133
def sjoin_nearest(left_df, right_df, how='inner', max_distance=None, lsuffix='left', rsuffix='right', **kwargs): ...
134
def overlay(df1, df2, how='intersection', keep_geom_type=None, make_valid=True): ...
135
def clip(gdf, mask, keep_geom_type=False, sort=False): ...
136
```
137

138
[Spatial Relationships](./spatial-relationships.md)
139

140
### Visualization
141

142
Static and interactive mapping capabilities for creating publication-quality maps and exploratory data visualizations.
143

144
```python { .api }
145
def plot(ax=None, figsize=None, color=None, edgecolor=None, **kwargs): ...
146
def explore(color=None, marker_type='marker', tiles='OpenStreetMap', **kwargs): ...
147
```
148

149
[Visualization](./visualization.md)
150

151
### Testing Utilities
152

153
Assertion functions and version information utilities for testing geospatial data structures and debugging dependency issues.
154

155
```python { .api }
156
def assert_geoseries_equal(left, right, **kwargs): ...
157
def assert_geodataframe_equal(left, right, **kwargs): ...
158
def show_versions(): ...
159
```
160

161
[Testing Utilities](./testing-utilities.md)