geeViz.gee2Pandas¶

Take data from GEE to Pandas and back

geeViz.gee2Pandas facilitates converting GEE objects to tabular formats that work well in more common packages such as Pandas.

Functions

`dfToJSON`(dbf, outJsonFilename)	Converts a DBF file to a JSON file.
`df_to_geojson`(df[, properties, ...])	Converts a Pandas DataFrame to a GeoJSON object.
`extractPointImageValues`(ee_image, pt[, ...])	Extracts values from a GEE image at a specific point.
`extractPointValuesToDataFrame`(ee_object, pt)	Extracts values from a GEE object at a specific point and converts them to a Pandas DataFrame.
`featureCollection_to_csv`(featureCollection, ...)	Converts a GEE FeatureCollection to a CSV file.
`featureCollection_to_json`(featureCollection, ...)	Converts a Google Earth Engine (GEE) FeatureCollection to a JSON file.
`geeToLocalZonalStats`(zones, raster, output_csv)	Computes zonal statistics in GEE and saves the results to a local CSV file.
`imageArrayPixelToDataFrame`(img, pt[, scale, ...])	Converts pixel values from an image array to a Pandas DataFrame.
`robust_featureCollection_to_df`(featureCollection)	Converts a GEE FeatureCollection to a Pandas DataFrame.
`setDFTitle`(df, title)	Sets a title for a Pandas DataFrame.
`tableToFeatureCollection`(table_path[, ...])	Converts a table to a GEE FeatureCollection.

geeViz.gee2Pandas.featureCollection_to_json(featureCollection, output_json_name, overwrite=False, maxNumberOfFeatures=5000)[source]¶

Converts a Google Earth Engine (GEE) FeatureCollection to a JSON file.

If the output JSON file already exists and overwrite is False, the function reads the existing file. Otherwise, it converts the FeatureCollection to JSON and writes it to the specified file.

Parameters:

featureCollection (ee.FeatureCollection) – The GEE FeatureCollection to convert.
output_json_name (str) – The path to the output JSON file.
overwrite (bool, optional) – Whether to overwrite the existing file. Defaults to False.
maxNumberOfFeatures (int, optional) – Maximum number of features to include. Defaults to 5000.

Returns:

The JSON representation of the FeatureCollection.

Return type:

dict

Example

>>> from geeViz.gee2Pandas import featureCollection_to_json
>>> fc = ee.FeatureCollection("TIGER/2018/States").limit(10)
>>> output_json = "states.json"
>>> json_data = featureCollection_to_json(fc, output_json, overwrite=True)
>>> print(json_data)

geeViz.gee2Pandas.featureCollection_to_csv(featureCollection, output_csv_name, overwrite=False)[source]¶

Converts a GEE FeatureCollection to a CSV file.

If the output CSV file already exists and overwrite is False, the function skips the conversion. Otherwise, it converts the FeatureCollection to a Pandas DataFrame and writes it to a CSV file.

Parameters:

featureCollection (ee.FeatureCollection) – The GEE FeatureCollection to convert.
output_csv_name (str) – The path to the output CSV file.
overwrite (bool, optional) – Whether to overwrite the existing file. Defaults to False.

Example

>>> from geeViz.gee2Pandas import featureCollection_to_csv
>>> fc = ee.FeatureCollection("TIGER/2018/States").limit(10)
>>> output_csv = "states.csv"
>>> featureCollection_to_csv(fc, output_csv, overwrite=True)

geeViz.gee2Pandas.robust_featureCollection_to_df(featureCollection, sep='___')[source]¶

Converts a GEE FeatureCollection to a Pandas DataFrame.

Handles the 5000-feature limit by slicing the FeatureCollection into manageable chunks. This function is memory-intensive and may fail for complex operations.

Parameters:

featureCollection (ee.FeatureCollection) – The GEE FeatureCollection to convert.
sep (str, optional) – Separator for nested property names. Defaults to “___”.

Returns:

The resulting DataFrame.

Return type:

pandas.DataFrame

Example

>>> from geeViz.gee2Pandas import robust_featureCollection_to_df
>>> fc = ee.FeatureCollection("TIGER/2018/States").limit(10)
>>> df = robust_featureCollection_to_df(fc)
>>> print(df.head())

geeViz.gee2Pandas.geeToLocalZonalStats(zones, raster, output_csv, reducer=<ee.reducer.Reducer object>, scale=None, crs=None, transform=None, tileScale=4, overwrite=False, maxNumberOfFeatures=5000)[source]¶

Computes zonal statistics in GEE and saves the results to a local CSV file.

Parameters:

zones (ee.FeatureCollection) – The zones over which to compute statistics.
raster (ee.Image) – The raster image to analyze.
output_csv (str) – The path to the output CSV file.
reducer (ee.Reducer, optional) – The reducer to apply. Defaults to ee.Reducer.first().
scale (float, optional) – The scale in meters for the analysis. Defaults to None.
crs (str, optional) – The coordinate reference system. Defaults to None.
transform (list, optional) – The affine transform. Defaults to None.
tileScale (int, optional) – Tile scale for computation. Defaults to 4.
overwrite (bool, optional) – Whether to overwrite the existing file. Defaults to False.
maxNumberOfFeatures (int, optional) – Maximum number of features to include. Defaults to 5000.

Example

>>> from geeViz.gee2Pandas import geeToLocalZonalStats
>>> zones = ee.FeatureCollection("TIGER/2018/States").limit(5)
>>> raster = ee.Image("USGS/NLCD/NLCD2016").select("landcover")
>>> output_csv = "zonal_stats.csv"
>>> geeToLocalZonalStats(zones, raster, output_csv, scale=30, overwrite=True)

geeViz.gee2Pandas.df_to_geojson(df, properties=None, geometry_type_fieldname='geometry.type', geometry_coordinates_fieldname='geometry.coordinates')[source]¶

Converts a Pandas DataFrame to a GeoJSON object.

Assumes point location geometry. Adapted from: https://notebook.community/captainsafia/nteract/applications/desktop/example-notebooks/pandas-to-geojson

Parameters:

df (pandas.DataFrame) – The DataFrame to convert.
properties (list, optional) – List of property column names to include. Defaults to None.
geometry_type_fieldname (str, optional) – Column name for geometry type. Defaults to “geometry.type”.
geometry_coordinates_fieldname (str, optional) – Column name for geometry coordinates. Defaults to “geometry.coordinates”.

Returns:

The GeoJSON object.

Return type:

dict

Example

>>> import pandas as pd
>>> from geeViz.gee2Pandas import df_to_geojson
>>> data = {
...     "geometry.type": ["Point", "Point"],
...     "geometry.coordinates": ['[-65.8491, 18.2233]', '[-66.1057, 18.4655]'],
...     "name": ["Location1", "Location2"],
... }
>>> df = pd.DataFrame(data)
>>> geojson = df_to_geojson(df)
>>> print(geojson)

geeViz.gee2Pandas.tableToFeatureCollection(table_path, properties=None, dateCol=None, groupByColumns=None, mode=None, geometry_type_fieldname='geometry.type', geometry_coordinates_fieldname='geometry.coordinates')[source]¶

Converts a table to a GEE FeatureCollection.

Supports Excel, CSV, and Pickle input table formats.

Parameters:

table_path (str) – Path to the input table.
properties (list, optional) – List of property column names to include. Defaults to None.
dateCol (str, optional) – Column name for date. Defaults to None.
groupByColumns (list, optional) – Columns to group by. Defaults to None.
mode (str, optional) – Input table format. Defaults to None.
geometry_type_fieldname (str, optional) – Column name for geometry type. Defaults to “geometry.type”.
geometry_coordinates_fieldname (str, optional) – Column name for geometry coordinates. Defaults to “geometry.coordinates”.

Returns:

The resulting FeatureCollection.

Return type:

ee.FeatureCollection

Example

>>> from geeViz.gee2Pandas import tableToFeatureCollection
>>> table_path = "locations.csv"
>>> fc = tableToFeatureCollection(table_path, mode="csv")
>>> print(fc.getInfo())

geeViz.gee2Pandas.dfToJSON(dbf, outJsonFilename)[source]¶

Converts a DBF file to a JSON file.

Parameters:

dbf (str) – Path to the DBF file.
outJsonFilename (str) – Path to the output JSON file.

Returns:

The JSON representation of the DBF file.

Return type:

dict

Example

>>> from geeViz.gee2Pandas import dfToJSON
>>> dbf_path = "data.dbf"
>>> json_path = "data.json"
>>> json_data = dfToJSON(dbf_path, json_path)
>>> print(json_data)

geeViz.gee2Pandas.setDFTitle(df, title)[source]¶

Sets a title for a Pandas DataFrame.

Parameters:

df (pandas.DataFrame) – The DataFrame to modify.
title (str) – The title to set.

Returns:

The styled DataFrame.

Return type:

pandas.io.formats.style.Styler

Example

>>> import pandas as pd
>>> from geeViz.gee2Pandas import setDFTitle
>>> data = {"A": [1, 2], "B": [3, 4]}
>>> df = pd.DataFrame(data)
>>> styled_df = setDFTitle(df, "Sample DataFrame")
>>> print(styled_df)

geeViz.gee2Pandas.imageArrayPixelToDataFrame(img, pt, scale=None, crs=None, transform=None, title=None, index=None, columns=None, bandName=None, reducer=<ee.reducer.Reducer object>, arrayImage=None)[source]¶

Converts pixel values from an image array to a Pandas DataFrame.

Parameters:

img (ee.Image) – The image to extract values from.
pt (ee.Geometry.Point) – The point location.
scale (float, optional) – The scale in meters for the analysis. Defaults to None.
crs (str, optional) – The coordinate reference system. Defaults to None.
transform (list, optional) – The affine transform. Defaults to None.
title (str, optional) – Title for the DataFrame. Defaults to None.
index (list, optional) – Index for the DataFrame. Defaults to None.
columns (list, optional) – Columns for the DataFrame. Defaults to None.
bandName (str, optional) – Band name for array images. Defaults to None.
reducer (ee.Reducer, optional) – Reducer to apply. Defaults to ee.Reducer.first().
arrayImage (bool, optional) – Whether the image is an array image. Defaults to None.

Returns:

The resulting DataFrame.

Return type:

pandas.DataFrame

Example

>>> from geeViz.gee2Pandas import imageArrayPixelToDataFrame
>>> img = ee.Image([1, 2, 3])
>>> pt = ee.Geometry.Point([-65.8491, 18.2233])
>>> df = imageArrayPixelToDataFrame(img, pt, scale=30)
>>> print(df)

geeViz.gee2Pandas.extractPointImageValues(ee_image, pt, scale=None, crs=None, transform=None, reducer=<ee.reducer.Reducer object>, includeNonSystemProperties=False, includeSystemProperties=True)[source]¶

Extracts values from a GEE image at a specific point.

Parameters:

ee_image (ee.Image) – The image to extract values from.
pt (ee.Geometry.Point) – The point location.
scale (float, optional) – The scale in meters for the analysis. Defaults to None.
crs (str, optional) – The coordinate reference system. Defaults to None.
transform (list, optional) – The affine transform. Defaults to None.
reducer (ee.Reducer, optional) – Reducer to apply. Defaults to ee.Reducer.first().
includeNonSystemProperties (bool, optional) – Whether to include non-system properties. Defaults to False.
includeSystemProperties (bool, optional) – Whether to include system properties. Defaults to True.

Returns:

The extracted values.

Return type:

ee.Dictionary

Example

>>> from geeViz.gee2Pandas import extractPointImageValues
>>> img = ee.Image([1, 2, 3])
>>> pt = ee.Geometry.Point([-65.8491, 18.2233])
>>> values = extractPointImageValues(img, pt, scale=30)
>>> print(values.getInfo())

geeViz.gee2Pandas.extractPointValuesToDataFrame(ee_object, pt, scale=None, crs=None, transform=None, title=None, index=None, columns=None, bandName=None, reducer=<ee.reducer.Reducer object>, includeNonSystemProperties=False, includeSystemProperties=True)[source]¶

Extracts values from a GEE object at a specific point and converts them to a Pandas DataFrame.

Parameters:

ee_object (ee.Image or ee.ImageCollection) – The GEE object to extract values from.
pt (ee.Geometry.Point) – The point location.
scale (float, optional) – The scale in meters for the analysis. Defaults to None.
crs (str, optional) – The coordinate reference system. Defaults to None.
transform (list, optional) – The affine transform. Defaults to None.
title (str, optional) – Title for the DataFrame. Defaults to None.
index (list, optional) – Index for the DataFrame. Defaults to None.
columns (list, optional) – Columns for the DataFrame. Defaults to None.
bandName (str, optional) – Band name for array images. Defaults to None.
reducer (ee.Reducer, optional) – Reducer to apply. Defaults to ee.Reducer.first().
includeNonSystemProperties (bool, optional) – Whether to include non-system properties. Defaults to False.
includeSystemProperties (bool, optional) – Whether to include system properties. Defaults to True.

Returns:

The resulting DataFrame.

Return type:

pandas.DataFrame

Example

>>> from geeViz.gee2Pandas import extractPointValuesToDataFrame
>>> img = ee.Image([1, 2, 3])
>>> pt = ee.Geometry.Point([-65.8491, 18.2233])
>>> df = extractPointValuesToDataFrame(img, pt, scale=30)
>>> print(df)