pansism / downscale-satellitelst

A python class for enhancing the spatial resolution of satellite-derived Land Surface Temperatures (LST) using statistical downscaling.

downscale-satelliteLST

A python class for enhancing the spatial resolution of Land Surface Temperature (LST) raster data using statistical downscaling.

Description

This class implements the typical workflow of a statistical downscaling scheme for enhancing the spatial resolution of satellite-derived Land Surface Temperatures (LST). It uses GDAL to perform the resampling of the raster data and scikit-learn to build the regression models, by stacking a Random Forest, a Ridge and a SVM into an ensemble regressor.

Input Data:

1. LST: A single raster dataset with one or more bands (each band is a LST image).
2. Predictors: A single raster dataset with one or more bands (each band is a predictor).

The class does not require the two raster datasets to have the same SRS and Bounding Box. The only requirement is the predictors to be within the bounds of the LST data.

Class checks before downscaling the LST data:

If a LST band misses more than 40% of its pixels, then this band is discarded and no model is built. In addition, if a model achieves a R2 that is lower than 0.5, it is also discarded. These two thresholds can be changed using the setters SetMissingPxlsThreshold() and SetR2Threshold(), respectively.

Output:

A dictionary with the Downscaled LST (DLST) data of all the non-discarded models. The spatial resolution and the SRS of the output data is that of the predictors.

To save the DLST data as a raster dataset use the class method SaveDLSTasGeotiff() and provide a savename (the savepath is the workdir).

Usage

from osgeo import gdal
from DownscaleSatelliteLST import DownscaledLST     # Import the class

# Make an instance of the class
data = DownscaledLST(
        LST=gdal.Open("inputLST.tif"),				 
        predictors=gdal.Open("LSTpredictors.tif"),   
        LST_noDataVal=-1000,						
        predictors_noDataVal=-1000,		
        workdir="./DLST_save_folder",
        )

# Change the number of parallel jobs to 4 (the default value is 1; to use all cores use -1)
data.SetNumberOfJobs(4)

# Change the R^2 threshold for discarding a model (the default value is 0.5)
data.SetR2Threshold(0.6)

# Downscale the LST data and apply the residual correction.
DLST = data.ApplyDownscaling(residual_corr=True)

# Get a list with the LST bands that have been downscaled.
# LST bands that miss more than 40% of their pixels 
# and regression models that achieve a R^2 below the
# R2-threshold are discarded.
bands = data.GetDLSTBandIndices(indexing_from_1=False)

# Save a report with the scores of all the non-discarded models
# The report is saved in workdir
data.GenerateReport()

# Export the DLST data as a compressed Geotiff file
# The geotiff file is saved in workdir 
data.SaveDLSTasGeotiff(savename="DLST.tif")

For a working example check the folder example.

Things to keep in mind:

• The recommended datatype for the input rasters is float.
• If the LST or the predictors contain any water bodies or clouds, then these pixels should be NoData.
• All the NoData pixels should have the same NoData value.
• The class builds a "global" regression model for each LST band. Hence, it should be used with data that cover an area of limited extent, e.g. a city with its surroundings.
• If the predictors are gapless, the algorithm will generate DLST data and for the cloud-covered areas. Handle them with caution.

To Do

• Add a class for preparing the predictors.
• Add unittests

License

This project is licensed under the MIT License - see the LICENSE file for details.

References

If you use this class please cite the following:

@phdthesis{Sismanidis2018PhD,
    author = {Sismanidis, Panagiotis},
    pages  = {154},
    school = {National Technical University of Athens},
    title  = {{Applying Computational Methods for Processing Thermal Satellite Images of Urban Areas}},
    type   = {PhD Dissertation},
    year   = {2018},
    doi    = {10.26240/heal.ntua.3048}
}

@inproceedings{sismanidis2019AGU,
    author    = {Sismanidis, Panagiotis and Keramitsoglou, Iphigenia and Hulley, Glynn C and Kiranoudis, Christos T},
    title     = {{Enhancing the spatial resolution of diurnal LST from geostationary satellites}},
    booktitle = {AGU Fall Meeting Abstracts},
    year      = {2019},
    volume    = {2019},
    month     = {dec},
    eid       = {GC44C--02},
    pages     = {GC44C--02},
    adsurl    = {https://ui.adsabs.harvard.edu/abs/2019AGUFMGC44C..02S},
}

downscale-satellitelst's Issues

PERSIANN precipitation data downscaling

Hello
I want use PERSIANN precipitation data for Hydrology simulation.
Before this I want downscale input data.
can I use your scripts for this?

about data

Could you tell me how this predictor was made，please

Example script throws error

Hi. First, thanks for writing this class. Unfortunately when I try to run the example script (example_using_SEVIRI_data.py),

%Run example_using_SEVIRI_data.py

I encounter the following. I am using version 1.1.0 of your code with Python 3.9.5.

Warning 1: LSALST_20180819_Athens_15min.tif: TIFFReadDirectory:Sum of Photometric type-related color channels and ExtraSamples doesn't match SamplesPerPixel. Defining non-color channels as ExtraSamples.
Warning 1: TIFFReadDirectory:Sum of Photometric type-related color channels and ExtraSamples doesn't match SamplesPerPixel. Defining non-color channels as ExtraSamples.

Downscaling started at:   21/01/2022, 12:56

SETTINGS
========
Residual Correction:           True
R2-threshold:                  0.5
Missing pxls threshold:        40.0%
Train/test size split:         0.7/0.3
Parallel jobs:                 1
Hyperarameter tuning trials:   60

Building the regression models.
  Processing band 0:
Traceback (most recent call last):
  File "/home/pramit/Downloads/downscale-satelliteLST-1.1.0/example/example_using_SEVIRI_data.py", line 45, in <module>
    main()
  File "/home/pramit/Downloads/downscale-satelliteLST-1.1.0/example/example_using_SEVIRI_data.py", line 32, in main
    data.ApplyDownscaling(residual_corr=True)
  File "/home/pramit/Downloads/downscale-satelliteLST-1.1.0/example/DownscaleSatelliteLST.py", line 246, in ApplyDownscaling
    normal_transformer = QuantileTransformer(len(y)//2, "normal", random_state=self.SEED).fit(X)
TypeError: __init__() takes 1 positional argument but 3 positional arguments (and 1 keyword-only argument) were given

Given that Python is not my go-to language, it would be of much help if you could please point out if I am doing something wrong. Thanks!

when i test use example tif, a warning appeared

Warning 1: TIFFReadDirectory:Sum of Photometric type-related color channels and ExtraSamples doesn't match SamplesPerPixel. Defining non-color channels as ExtraSamples.

i don't know what caused this warning, which will make an impact on the result?

and you provided a predictor sample file "LST_predictors_100m.tif" as referrence downscaling background, if i want to downscale to another scales,i must provide the corresponding referrence files,which may be hard to provide sometimes.

Padding on the bottom and right edges of result

Hi,

The code runs perfectly on my own dataset consisting of principal components of several predictors and a low-resolution LST image.

%Run example_using_SEVIRI_data.py

Downscaling started at:   01/02/2022, 15:52

SETTINGS
========
Residual Correction:           True
R2-threshold:                  0.0
Missing pxls threshold:        40.0%
Train/test size split:         0.7/0.3
Parallel jobs:                 1
Hyperarameter tuning trials:   60

Building the regression models.
  Processing band 0:
    Tuning the random forest hyperparameters...   Done [CV R2 score = 0.54]
    Tuning the ridge hyperparameters...           Done [CV R2 score = 0.48]
    Tuning the svr hyperparameters...             Done [CV R2 score = 0.35]
/home/pramit/.local/lib/python3.9/site-packages/sklearn/linear_model/_coordinate_descent.py:647: ConvergenceWarning: Objective did not converge. You might want to increase the number of iterations, check the scale of the features or consider increasing regularisation. Duality gap: 1.408e-02, tolerance: 1.181e-02
  model = cd_fast.enet_coordinate_descent(
    The R2 score of the ensemble model is: 0.56   PASS

Models that passed the checks: 1/1

Downscaling the corresponding LST bands...
Downscaling LST band 0:   [#########################] 100.00% 

Downscaling completed in: 222.5 sec
Writing to GeoTiff...     Done
Generating report...      Done
LST bands that have been downscaled:
[0]

However, the result exhibits a padding effect on the bottom and right edges only that looks like a frame, as visible in the screenshot below. No such artefacts exist in any of the inputs to the model.

The width of this "frame" is different at the two edges. Could it be because of the warning that was raised? I look forward to your opinion on this and a possible solution will, of course, be lovely. Thanks in advance!

What is the every bands of the predictors.tif meaning?

Hello!Thanks for your nice work!
I have a question that what is the every bands of the predictors.tif meaning,I guess NDVI and DEM data maybe in it, but I don't the others. Could you please give me an answer?Also, where can I find the class reference paper to read?
Best wishes to you!

.