API Reference

jaxa.earth.je module

This API package for Python was developed for the utilization of various earth observation data held by JAXA. By using this API, you can easily acquire and process data without worrying about the specifications, sensors, resolution, etc. of each satellite data.

je module contains four classes : FeatureCollection, ImageCollectionList, ImageCollection, ImageProcess.

# Usage example

# Import module
from jaxa.earth import je

# Read geojson
geoj_path = "gadm36_JPN_0.geojson"
geoj = je.FeatureCollection().read(geoj_path).select([])

# Get images
data_out = je.ImageCollection("JAXA.EORC_ALOS.PRISM_AW3D30.v3.2_global")\
             .filter_date(["2021-01-01T00:00:00","2022-01-01T00:00:00"])\
             .filter_resolution(20)\
             .filter_bounds(geoj[0])\
             .select("DSM")\
             .get_images()

# Process and show images
img = je.ImageProcess(data_out)\
        .show_images()\
        .calc_spatial_stats()\
        .show_spatial_stats()

class jaxa.earth.je.FeatureCollection

Bases: object

The FeatureCollection class is used to read a feature collection and select features of geojson data from your computer.

Returns: A FeatureCollection class object which has a propery of feature_collection. the object’s all properties is set to None as default.

feature_collection

The property is updated after the method read is executed. Default value is None.

Type: dict

# Usage example: Aquire feature collection data
geoj_path = "C:\MyData\gadm36_JPN_1.geojson"
geoj = je.FeatureCollection().read(geoj_path).select(["Tokyo"])

read(path: str)

The method read read the inputed path’s geojson data as feature collection.

Parameters: path (str) – User’s geojson data location’s absolute path
Returns: A FeatureCollection class object that stores updated feature_collection property

# Usage example: Read geojson data as feature collection
data_path = "C:\MyData\MyArea.geojson"
data_fc   = je.FeatureCollection.read(data_path)

select(keywords: list = [])

The method select filter the inputed feature collection’s data in properties by keywords. The Default is blank list, so all features of feature collection is selected.

Parameters: keywords (list) – keywords list of your prefered word
Returns: geojson features selected by keywords

# Usage example: Select feature from geojson's feature collection
geojson = data_fc.select(["Japan","Tokyo"])

class jaxa.earth.je.ImageCollection(collection: Optional[str] = None, ssl_verify: Optional[bool] = None)

Bases: object

The class, ImageCollection gets selected collection’s catalog json data from JAXA Earth database. If you use the class’s method, users can aquire collection’s raster images depend on query such as date limit, resolution, bounds, band.

Parameters

collection (str) – Selected collection’s name. If no input, “JAXA.EORC_ALOS.PRISM_AW3D30.v3.2_global” will be used.
ssl_verify (bool) –
Users can set valid ssl certification process to True or False. The default is True.

Note

Setting the value to False can be a serucity risk.

Returns

An ImageCollection class object which has properties of stac_date, stac_ppu , stac_bounds , stac_band and raster. The object’s all properties is set to None as default.

stac_date

Default value is None. The updated property will be set after the method, filter_date. The updated property has four properties such as query , url , id and json. The object is used as input to the method filter_resolution.

Type: An Stac class object

stac_ppu

Default value is None. The updated property will be set after the method, filter_resolution. The updated property has three properties such as query , url and json. The object is used as input to the method filter_bounds.

Type: An Stac class object

stac_bounds

Default value is None. The updated property will be set after the method, filter_bounds. The updated property has three properties such as query , url and json. The object is used as input to the method select.

Type: An Stac class object

stac_band

Default value is None. The updated property will be set after the method, select. The updated property has two properties such as query and url. The object is used as input to the method get_images.

Type: An Stac class object

raster

Default value is None. The updated property will be set after the method, get_images. The updated Raster class object property has properties of img , latlim and lonlim.

Type: An Raster class object

# Usage example: Get image
data_out = je.ImageCollection("JAXA.EORC_ALOS.PRISM_AW3D30.v3.2_global")\
             .filter_date(["2021-01-01T00:00:00","2023-01-31T00:00:00"])\
             .filter_resolution(20)\
             .filter_bounds([-180,-90,180,90])\
             .select("DSM")\
             .get_images()

filter_bounds(bbox: Optional[list] = None, geoj: Optional[dict] = None)

The method, filter_bounds filters collection’s catalog json by user query of bounds or geojson. If you input both of bbox and geoj, geoj is used to detect bounding box. If you don’t input neither of them, maximum bounding box will be selected. In QGIS environment, appropriate area will be selected with no input. Property of stac_bounds will be updated after the method.

Parameters

bbox (list) – bounding box input.
geoj (dict) – geojson input

Returns

An ImageCollection class object that stores updated stac_bounds property

Note

Attention! you have to use method filter_resolution before the method.

# Usage example: Filter ImageCollection by bbox of geojson
bbox = [120,20,150,50]
data_ic3 = data_ic2.filter_bounds(bbox)

filter_date(dlim: list = [])

The method, filter_date filters collection’s catalog json by user query of date limit. If no inputs, defaulut date lim parameter is set as [“2021-01-01T00:00:00”,”2021-12-31T23:59:59”]. Property of stac_date will be updated after the method.

Parameters: date_lim (list) – date limits of minimum date, maximum date.
Returns: An ImageCollection class object that stores updated stac_date property

# Usage example: Filter ImageCollection by date limit
date_lim = ["2021-01-01T00:00:00","2022-01-01T00:00:00"]
data_ic1 = data_ic0.filter_date(date_lim)

filter_resolution(ppu: Optional[float] = None)

The method, filter_resolution filters collection’s catalog json by user query of resolution of ppu (Pixels Per Unit). Unit means one degree in epsg 4326, 32786m in epsg 3995. If no input, minimum value or appropriate value (only in QGIS) is set. Property of stac_ppu will be updated after the method.

Parameters: ppu (float) – ppu input.
Returns: An ImageCollection class object that stores updated stac_ppu property

Note

Attention! you have to use method filter_date before the method.

# Usage example: Filter ImageCollection by ppu
ppu = 20
data_ic2 = data_ic1.filter_resolution(ppu)

get_images()

The method, get_images gets collection’s images depend on the user querys of date limit, resolution, bounds, band. Property of raster will be updated after the method. In addition to this, regeon of interest area of raster images will be returned.

Returns: An ImageCollection class object that stores updated raster property

Note

Attention! you have to use method filter_band before the method.

# Usage example: Get Image depend on user's query.
data_out0 = data_ic4.get_images()

select(band: Optional[str] = None)

The method, select selects collection’s catalog json by user query of band. If you don’t input band, the first band will be selected. Property of stac_band will be updated after the method.

Parameters: band (str) – band of asset
Returns: An ImageCollection class object that stores updated stac_band property

Note

Attention! you have to use method filter_bounds before the method.

# Usage example: Filter ImageCollection by band
band = "DSM"
data_ic4 = data_ic3.filter_band(band)

class jaxa.earth.je.ImageCollectionList(ssl_verify: Optional[bool] = None)

Bases: object

The class, ImageCollectionList get and filter colletion’s catalog json depend on user input keywords.

Parameters

ssl_verify (bool) –

Users can set valid ssl certification process to True or False. The default is True.

Note

Setting the value to False can be a serucity risk.

Returns

An ImageCollectionList class object which has properties of stac_collections.

# Usage example: Get collection's name and band
keywords = ["LST","_half-month"]
collections,bands = je.ImageCollectionList(ssl_verify=False)\
                      .filter_name(keywords=keywords)

filter_name(keywords: list = [])

The method, filter_name filter colletion’s catalog json from collection’s id depend on user input keywords.

Parameters: keywords (list) – keywords of request.
Returns: filtered collections and filtered bands

# Usage example: Get collection's name and band
key = ["LST","_half-month"]
collections,bands = je.ImageCollectionList()\
                      .filter_name(keywords=key)

class jaxa.earth.je.ImageProcess(data)

Bases: object

The class, ImageProcess execute various process by using inputed ImageCollecion class objects. If you use ImageProcess class method, users can process and get images such as masking images, differencial images, calculated temporal/spatial statistics. In addition to the processing, It’s possible to show images or timeseries graph.

Parameters

data (object) –

ImageCollection class object which contains updated raster property

Note

Attention! ImageCollection class object must have correct raster property.

Returns

An ImageProcess class object with updated property

raster

Default value is same as inputed ImageCollection class object’s raster property. The property will be updated after ImageProcess class object’s method execution such as mask_images , diff_images and calc_temporal_stats.

Type: An Raster class object

timeseries

Default value is None. The property will be updated after ImageProcess class object’s method execution such as calc_spatial_stats. Updated property has five keys and values such as “mean”, “std”, “min”, “max”, “median”.

Type: dict

# Usage example: Process and show images
img = je.ImageProcess(data_out0)\
        .show_images()\
        .calc_spatial_stats()\
        .show_spatial_stats()

calc_spatial_stats()

The method, calc_spatial_stats calculate spatial statistics.

Returns: An ImageProcess class object that stores updated timeseries property. Updated property has five keys and values such as “mean”, “std”, “min”, “max”, “median”.

# Usage example: Calculate spatial stats of data_ip0
data_s_stats = data_ip0.calc_spatial_stats()

calc_temporal_stats(method_query: str = 'mean')

The method, calc_temporal_stats calculate temporal statistics by user inputed query of method_query.

Parameters: method_query (dict) – “mean” or “max” or “min” or “std” or “median”. Default is “mean”.
Returns: An ImageProcess class object that stores updated raster property

# Usage example: Calculate temporal stats of data_ip0
data_t_stats = data_ip0.calc_temporal_stats("mean")

diff_images(ref)

The method, diff_images take difference by user inputed query of ref.

Parameters

ref (object) –

ImageCollection class object that has updated raster property which is used as ref data.

Note

Attention! ref’s shape (including resolution) must be same as data.

Returns

An ImageProcess class object that stores updated raster property

# Usage example: Differential data(data_out0-data_out1)
data_diff = data_ip0.diff_images(data_out1)

mask_images(mask, method_query: str = 'values_equal', values: float = [0, 1])

The method, mask_images masks by using mask, type_query, values.

Parameters

mask (class) –
ImageCollection class object that has updated raster property which is used as masking data.

Note

Attention! mask’s shape (including resolution) must be same as data.
method_query (dict) –
“range” or “values_equal” or “bits_equal”. Default method is “values_equal”.

”range” is used if users would like to extract specific range of values and masks out of range values. Data type of float is acceptable as “range” mask.

”values_equal” is used if users would like to extract specific values pixels only and other values pixels are masked. Data type of float is acceptable. Typically, land cover products will be used as “values_equal” mask.

”bits_equal” is used if users would like to extract specific bit values pixels only and other bit values pixels are masked. Data type of float is not acceptable as mask. Typically, quality assuarance products will be used as “bits_equal” mask.
values (list) – user query of values list. if you set type_query as “range”, please set values as two values list as minimum and maximum. If “values_equal”, you can set multiple values list as you like. If “bits_equal”, you can set bit values 0 or 1 as bit values which begins from zero bit. Default values is [0,1].

Returns

An ImageProcess class object that stores updated raster property

# Usage example: Mask data_out0 by data_out1
data_masked = data_ip0.mask_images(data_out1,"range",[0,100])

show_images(cmap: Optional[str] = None, clim: list = [])

The method, show_images shows images of raster property. If multiple date’s image is set, the method shows all of images.

Parameters

cmap (str) – query of colormap name. User can choose “ndvi”,”turbo”, “spectral”. Default is “turbo”.
clim (list) – query of color range (optional).

Returns

An ImageProcess class object

# Usage example: Show images of data_ip0
data_ip0.show_images()

show_images_qgis(cmap: Optional[str] = None, clim: list = [])

The method, show_images_qgis shows images in qgis.

Parameters

cmap (str) – query of colormap name. User can choose “ndvi”,”turbo”, “spectral”. Default is “turbo”.
clim (list) – query of color range (optional).

Returns

An ImageProcess class object

Note

Attention! This method is only valid in QGIS environment.

# Usage example: Show images of data_ip0 in qgis
data_ip0.show_images_qgis()

show_spatial_stats(ylim: list = [])

The method, show_spatial_stats shows graph of calclation result of the method calc_spatial_stats.

Parameters: ylim (list) – query of color range (optional)
Returns: An ImageProcess class object

Note

Attention! you should use the method calc_spatial_stats before the method.

# Usage example: Show graph of calclation result of the method calc_spatial_stats
data_s_stats.show_spatial_stats()