API Reference

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

from jaxa.earth import je

This API package for Python has developed to utillize 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.

Example

# 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()

`FeatureCollection`

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

Returns:

Type	Description
	A `FeatureCollection` class object which has a properry of `feature_collection`.
	the object's properties are set to None by default.

Attributes:

Name	Type	Description
`feature_collection`	`dict`	The property is updated after the method `read` is executed. The default value is None.

Example

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

`read(path)`

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

Parameters:

Name	Type	Description	Default
`path`	`str`	The absolute path to the user's geojson location.	required

Returns:

Type	Description
	A `FeatureCollection` class object which stores updated `feature_collection` property

Example

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

`select(keywords=[])`

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 are selected.

Parameters:

Name	Type	Description	Default
`keywords`	`list`	keywords list of your preferred words.	`[]`

Returns:

Name	Type	Description
`list`		geojson features selected by keywords

Example

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

`ImageCollectionList`

The class, ImageCollectionList gets and filters collection's catalog json depending on user input keywords.

Parameters:

Name	Type	Description	Default
`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 security risk.	`None`

Returns:

Type	Description
	An `ImageCollectionList` class object which has properties of `stac_collections`.

Example

# 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=[])`

The method, filter_name filter collection's catalog json from collection's id depending on user input keywords.

Parameters:

Name	Type	Description	Default
`keywords`	`list`	keywords of request.	`[]`

Returns:

Type	Description
	filtered collections and filtered bands

Example

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

`ImageCollection`

The class, ImageCollection gets selected collection's catalog json data from JAXA Earth database. When you use the class's method, you can acquire collection's raster images depending on query such as date limit, resolution, bounds and band.

Parameters:

Name	Type	Description	Default
`collection`	`str`	Name of the selected collection. If not specified, "JAXA.EORC_ALOS.PRISM_AW3D30.v3.2_global" is used.	`None`
`stac_cog_url`	`str`	Users can set valid stac cog url to `stac_cog_url`.	`None`
`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 security risk.	`None`

Returns:

Type	Description
	An `ImageCollection` class object which has properties of `stac_date`,
	`stac_ppu` , `stac_bounds` , `stac_band` and `raster`.
	All properties of the object are set to Noe by default.

Attributes:

Name	Type	Description
`stac_date`	A ``Stac`` class object	The default value is None. The updated property is 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`.
`stac_ppu`	A ``Stac`` class object	The default value is None. The updated property is 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`.
`stac_bounds`	A ``Stac`` class object	The default value is None. The updated property is 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`.
`stac_band`	A ``Stac`` class object	The default value is None. The updated property is 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`.
`raster`	A ``Raster`` class object	The default value is None. The updated property is set after the method, `get_images`. The updated `Raster` class object property has properties of `img` , `latlim` and `lonlim`.

Example

# 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_date(dlim=[])`

The method, filter_date filters collection's catalog json by the user query of date limit. If no input is given, default date lim parameter is set as ["2021-01-01T00:00:00","2021-12-31T23:59:59"]. The property of stac_date
is updated after the method.

Parameters:

Name	Type	Description	Default
`date_lim`	`list`	date limits of minimum date, maximum date.	required

Returns:

Type	Description
	An `ImageCollection` class object that stores updated `stac_date` property

Note

If normal products are specified for multiple years, the same products is returned for multiple years .

Example

# 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=None)`

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

Parameters:

Name	Type	Description	Default
`ppu`	`float`	ppu input.	`None`

Returns:

Type	Description
	An `ImageCollection` class object that stores updated `stac_ppu` property

Note

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

Example

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

`filter_bounds(bbox=None, geoj=None)`

The method, filter_bounds filters collection's catalog json by the 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 is selected. In QGIS environment, appropriate area is selected with no input. The property of stac_bounds is updated after the method.

Parameters:

Name	Type	Description	Default
`bbox`	`list`	bounding box input.	`None`
`geoj`	`dict`	geojson input	`None`

Returns:

Type	Description
	An `ImageCollection` class object that stores updated `stac_bounds` property

Note

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

Example

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

`select(band=None)`

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

Parameters:

Name	Type	Description	Default
`band`	`str`	band of asset	`None`

Returns:

Type	Description
	An `ImageCollection` class object that stores updated `stac_band` property

Note

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

Example

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

`get_images()`

The method, get_images gets collection's images depending on the user's queries of date limit, resolution, bounds and band. The property of raster will be updated after the method. In addition to this, region of interest area of raster images will be returned.

Returns:

Type	Description
	An `ImageCollection` class object that stores updated `raster` property

Note

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

Example

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

`ImageProcess`

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

Parameters:

Name	Type	Description	Default
`data`	`object`	`ImageCollection` class object which contains updated `raster` property. Note: The `ImageCollection` object must have correct `raster` property.	required

Returns:

Type	Description
	An `ImageProcess` class object with updated property

Attributes:

Name	Type	Description
`raster`	A ``Raster`` class object	The default value is same as inputed `ImageCollection` class object's `raster` property. The property is updated after executing methods of the `ImageProcess` class object, such as `mask_images` , `diff_images` and `calc_temporal_stats`.
`timeseries`	`dict`	The default value is None. The property is updated after executing methods of the `ImageProcess` class object, such as `calc_spatial_stats`. The updated property has five keys and values such as "mean", "std", "min", "max" and "median".

Example

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

`mask_images(mask, method_query='values_equal', values=[0, 1])`

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

Parameters:

Name	Type	Description	Default
`mask`	`class`	`ImageCollection` class object that has updated `raster` property which is used as masking data. Note: The shape of the mask (including resolution) must be the same as the data.	required
`method_query`	`dict`	"range" or "values_equal" or "bits_equal". The default method is "values_equal". "range" is used when users would like to extract a specific range of values and mask values outside the range. The data type of float is acceptable as a "range" mask. "values_equal" is used when users would like to extract only certain bit values of pixels and mask other bit values of pixels. The data type of float is acceptable. Typically, land cover products is used as "values_equal" mask. "bits_equal" is used when users would like to extract only certain values of pixels and mask other bit values of pixels. The data type of float is not acceptable as a mask. Typically, quality assurance products is used as a "bits_equal" mask.	`'values_equal'`
`values`	`list`	user query of values list. if you set type_query as "range", please set two values, 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. The default value is [0,1].	`[0, 1]`

Returns:

Type	Description
	An `ImageProcess` class object that stores the updated `raster` property

Example

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

`diff_images(ref)`

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

Parameters:

Name	Type	Description	Default
`ref`	`object`	`ImageCollection` class object that has updated `raster` property which is used as ref data. Note: The shape of the ref (including resolution) must be the same as the data.	required

Returns:

Type	Description
	An `ImageProcess` class object that stores the updated `raster` property

Example

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

`calc_temporal_stats(method_query='mean')`

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

Parameters:

Name	Type	Description	Default
`method_query`	`dict`	"mean" or "max" or "min" or "std" or "median". The default is "mean".	`'mean'`

Returns:

Type	Description
	An `ImageProcess` class object that stores the updated `raster` property

Example

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

`calc_spatial_stats()`

The method, calc_spatial_stats calculate spatial statistics.

Returns:

Type	Description
	An `ImageProcess` class object that stores updated `timeseries` property.
	The updated property has five keys and values such as "mean", "std", "min", "max" and
	"median".

Example

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

`show_images(cmap=None, clim=[], output='show')`

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

Parameters:

Name	Type	Description	Default
`cmap`	`str`	query of colormap name. User can choose "ndvi","turbo" and "spectral". The default is "turbo".	`None`
`clim`	`list`	query of color range (optional).	`[]`
`output`	`str`	query of output method. User can choose "show" or "png_buffer".	`'show'`

Returns:

Type	Description
	An `ImageProcess` class object

Example

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

`show_images_qgis(cmap=None, clim=[])`

The method, show_images_qgis shows images in qgis.

Parameters:

Name	Type	Description	Default
`cmap`	`str`	query of colormap name. User can choose "ndvi","turbo" and "spectral". Default is "turbo".	`None`
`clim`	`list`	query of color range (optional).	`[]`

Returns:

Type	Description
	An `ImageProcess` class object

Note

Attention! This method is only valid in QGIS environment.

Example

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

`show_spatial_stats(ylim=[], output='show')`

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

Parameters:

Name	Type	Description	Default
`ylim`	`list`	query of color range (optional)	`[]`
`output`	`str`	query of output method. User can choose "show" or "png_buffer".	`'show'`

Returns:

Type	Description
	An `ImageProcess` class object

Note

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

Example

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