pyxccd.utils module

pyxccd.utils.convert_short_date_to_calendar_date(short_date: int) → date

Convert a short date (number of days since a base date) to a calendar date.

Parameters:

short_date (int) – The number of days added to a base date (723742) to calculate the calendar date.

Returns:

The corresponding calendar date.

Return type:

date

pyxccd.utils.rio_loaddata(path: str) → ndarray

load raster dataset as numpy array

Parameters:

path (str) – path of the input raster

Return type:

np.ndarray

pyxccd.utils.get_block_y(block_id: int, n_block_x: int) → int

get block pos in y axis (started from 1)

Parameters:

• block_id (int) – The id of the block to be processed

• n_block_x (int) – Total number of blocks at x axis

Returns:

current block id at y axis (start from 1)

Return type:

int

pyxccd.utils.get_block_x(block_id: int, n_block_x: int) → int

get block pos at x axis (started from 1)

Parameters:

• block_id (int) – The id of the block to be processed

• n_block_x (int) – Total number of blocks at x axis

Returns:

current block pos at x axis (start from 1)

Return type:

int

pyxccd.utils.get_col_index(pos: int, n_cols, current_block_x, block_width) → int

get column index in a block

Parameters:

• pos (int) – The position of a pixel, i.e., i_row * n_cols + i_col + 1

• n_cols (int) – The number of columns

• current_block_x (int) – The current block id at y axis

• block_width (int) – block width

pyxccd.utils.get_row_index(pos, n_cols, current_block_y, block_height) → int

Parameters:

• pos (int) – The position of a pixel, i.e., i_row * n_cols + i_col + 1

• n_cols (int) – The number of columns

• current_block_y (int) – The current block id at y axis

• block_height (int) – block height

pyxccd.utils.assemble_cmmaps(dataset_info: DatasetInfo, result_path: str, cmmap_path: str, starting_date: int, n_cm_maps: int, prefix: str, cm_output_interval: int, clean: bool = True)

reorganized block-based change magnitudes into a series of maps

Parameters:

• config (dict) – pyxccd config dict

• result_path (str) – the path where block-based CM intermediate files are

• cmmap_path (str) – the path to save the new map-based output

• starting_date (int) – the starting date of the dataset

• n_cm_maps (int) – the number of change magnitude outputted per pixel

• prefix (str) – choose from ‘CM’, ‘CM_date’, ‘CM_direction’

• clean (bool) – if True, clean tmp files

pyxccd.utils.get_rowcol_intile(id: int, block_width: int, block_height: int, block_x: int, block_y: int)

Calculate row and col in original images based on pos index and block location

Parameters:

• id (int) – id of the pixel (i.e., i_row * n_cols + i_col). Note starting from 0

• block_width (int) – the width of each block

• block_height (int) – the height of each block

• block_x (int) – block location at x direction

• block_y (int) – block location at y direction

Returns:

return (original_row, original_col), i.e., row and col number (starting from 1) in original image (e.g., Landsat ARD 5000*5000)

Return type:

(int, int)

pyxccd.utils.get_id_inblock(pos: int, block_width: int, block_height: int, n_cols: int)

pixel id in the block, starting from 0

Parameters:

• pos (int) – position id of a pixel, i.e., i_row * n_cols + i_col + 1

• block_width (int) – the width of the block

• block_height (int) – the width of the height

• n_cols (int) – the number of the culimn

Returns:

pixel id, i.e., i_row * n_cols + i_col

Return type:

int

pyxccd.utils.get_time_now(tz)

get datetime for now

Parameters:

tz – The input time zone

Returns:

datatime format of current time

Return type:

datetime

pyxccd.utils.get_doy(ordinal_date: int) → str

get doy from ordinal date

Parameters:

• ordinal_date (int) – a ordinal date (MATLAB-format ordinal date)

• Returns

• ——-

• str – day of year

pyxccd.utils.assemble_array(array_list: list, n_block_x: int) → ndarray

Assemble a list of block-based array to a bigger array that aligns with the dimension of an ARD tile

Parameters:

• array_list (list) – a list of np.ndarray

• n_block_x (int) – block number at x axis

Returns:

an array [nrows, ncols]

Return type:

np.ndarray

pyxccd.utils.read_data(path: str) → ndarray

Load a sample file containing acquisition days and spectral values. The first column is assumed to be the day number, subsequent columns correspond to the day number. This improves readability of large datasets.

Parameters:

path (str) – the path of csv

Return type:

np.ndarray

pyxccd.utils.save_nrtfiles(out_folder: str, outfile_prefix: str, sccd_pack: SccdOutput, data_ext: DataFrame)

save nrt files into local for debug purpose

Parameters:

• out_folder (str) – The folder to svae results

• outfile_prefix (str) – prefix for saved files

• sccd_pack (SccdOutput) – SCCD output

• data_ext (pd.DataFrame) – observation as pandas dataframe

pyxccd.utils.save_obs2csv(out_path: str, data: DataFrame)

save observation dataframe to a local csv

Parameters:

• out_path (str) – the path for saving csv

• data (pd.DataFrame) – data to be outputed

pyxccd.utils.unindex_sccdpack(sccd_pack_single: SccdOutput) → list

remove index of sccdpack to save memory

Parameters:

sccd_pack_single (SccdOutput) – sccd output

Returns:

a list for five SccdOutput components

Return type:

list

pyxccd.utils.index_sccdpack(sccd_pack_single) → SccdOutput

convert a list of SccdOutput components back to namedtuple SccdOutput

Parameters:

sccd_pack_single (list) – A list of SccdOutput components

Returns:

sccd output

Return type:

SccdOutput

Raises:

Exception – The element number of sccd_pack_single is not five

pyxccd.utils.save_1band_fromrefimage(array: ndarray, out_path: str, ref_image_path=None, dtype=None)

save an array into the local as tif, using the georeference from a refimage

Parameters:

• array (np.ndarray) – Inputted array to be converted

• out_path (str) – Path for the output

• ref_image_path (str, optional) – Path for the reference image to copy georeference info, by default None

• dtype (_type_, optional) – str or numpy.dtype, optional. The data type for bands. For example: uint8 or rasterio.uint16.

pyxccd.utils.coefficient_matrix(date: int, num_coefficients: int) → ndarray

Generate cos and sin variables for Fourier transform function

Parameters:

• date (int) – Inputted ordinal date

• num_coefficients (int) – Number of variables to be outputted, i.e., the length of the matrix as return

Return type:

np.ndarray

pyxccd.utils.predict_ref(coefs: ndarray, date: int, num_coefficients: int = 6) → int

predicting a single-band reflectance using harmonic coefficients for a date

Parameters:

• coefs (np.ndarray) – 1-d array for harmonic coefficients

• date (int) – ordinal date for the inputted date

• num_coefficients (int, optional) – the number of coefs, by default 6

Returns:

the predicted reflectance

Return type:

int

pyxccd.utils.generate_rowcolimage(ref_image_path: str, out_path: str)

a function to convert the reference image to index image (starting from 1, e.g., the first pixel is 100001), which has the same rows and columns as the reference image

Parameters:

• ref_image_path (str) – Path of the reference image

• out_path (str) – Path of the outputted image

pyxccd.utils.calculate_sccd_cm(sccd_pack: SccdOutput) → float

compute median change magnitude for the current anomalies at the tail

Parameters:

sccd_pack (SccdOutput) – sccd output

Returns:

computed as the median values for the current anomaly_conse change magnitudes

Return type:

float

pyxccd.utils.class_from_dict(data_class, dict_var: dict)

convert dictionary to dataclass following the declaration of the dataclass

Parameters:

• data_class – Declare for dataclass

• dict_var (dict) – Inputted dictionary

Return type:

dataclass

pyxccd.utils.rio_warp(input_path: str, output_path: str, template_path: str)

warp a raster from a template file

Parameters:

• input_path (str) – path of inputted raster

• output_path (str) – path of outputted path

• template_path (str) – path of template path

pyxccd.utils.modeby(input_array: ndarray, index_array: ndarray) → list

calculate modes of input_array groupped by index_array.

Parameters:

• input_array (np.ndarray) – input array to calculate

• index_array (np.ndarray) – the object array, where the same id indicates the pixel for the same object

Returns:

a list of mode value for each object, following ascending order of unique id. modified from: https://stackoverflow.com/questions/49372918/group-numpy-into-multiple-sub-arrays-using-an-array-of-values

Return type:

list

pyxccd.utils.mode_median_by(input_array_mode: ndarray, input_array_median: ndarray, index_array: ndarray) → tuple

_summary_

Parameters:

• input_array_mode (np.ndarray) – input array for calculating mode

• input_array_median (np.ndarray) – input array for calculating median

• index_array (np.ndarray) – the array for indicating objects. The pixels in the same object have the same ids

Returns:

a list of mode value and a list of median value for each object

Return type:

(list, list)

pyxccd.utils.getcategory_cold(cold_plot: ndarray, i_curve: int, t_c: float = -200.0) → int

an empirical way to get break category for COLD algorithm

Parameters:

• cold_plot (np.ndarray) – Cold result for a single pixel, a structured array of dtype = cold_rec_cg

• i_curve (int) – Curve number to be classified

• t_c (float, optional) – The threshold to be used, by default -200.0

Returns:

break category

1 - land disturbance

2 - regrowth

3 - aforestation

Return type:

int

pyxccd.utils.getcategory_sccd(sccd_plot: ndarray, i_curve: int, t_c: float = -200.0) → int

an empirical way to get break category for COLD algorithm

Parameters:

• sccd_plot (np.ndarray) – sccd offline result for a single pixel, a structured array of dtype = rec_cg

• i_curve (int) – Curve number to be classified

• t_c (float, optional) – The threshold to be used, by default -200.0

Returns:

break category

1 - land disturbance

2 - regrowth

3 - aforestation

Return type:

int

pyxccd.utils.extract_features(cold_plot: ndarray, band: int, ordinal_day_list: list, nan_val: int = 0, feature_outputs: list = ['a0', 'a1', 'b1']) → list

generate features for classification based on a plot-based rec_cg and a list of days to be predicted

Parameters:

• cold_plot (np.ndarray) – A structured array of cold_rec_cg

• band (int) – Band index, started from 0, i.e., index 0 is band 1, index 1 is band 2, etc

• ordinal_day_list (list) – A list of ordinal day to extract a0, a0 = intercept + slope * a1 / 10000

• nan_val (int) – The default values assigned to feature output, by default 0

• feature_outputs (list, optional) – Indicate which features to be outputted. They must be within [a0, c1, a1, b1,a2, b2, a3, b3, rmse], by default [“a0”, “a1”, “b1”]

Returns:

a list of 1-d array. The length of list is len(feature_outputs); the length of 1-d array is len(ordinal_day_list)

Return type:

A list

Raises:

ValueError – The outputted feature must be in [a0, c1, a1, b1,a2, b2, a3, b3, cv, rmse]

pyxccd.utils.convert_datesince1982(date: int) → Timestamp

_summary_

Parameters:

date (int) – ordinal date

Returns:

_description_

Return type:

pd.Timestamp