pyxccd.ccd module

pyxccd.ccd.cold_detect(dates, ts_b, ts_g, ts_r, ts_n, ts_s1, ts_s2, ts_t, qas, p_cg=0.99, conse=6, pos=1, output_cm=False, starting_date=0, n_cm=0, cm_output_interval=0, b_c2=True, gap_days=365.25, lam=20)[source]

running pixel-based COLD algorithm.

Parameters:

  • dates (numpy.ndarray) – 1d time series of ordinal dates of shape(n_obs,)

  • ts_b (numpy.ndarray) – 1d time series of blue band of shape(n_obs,)

  • ts_g (numpy.ndarray) – 1d time series of green band of shape(n_obs,)

  • ts_r (numpy.ndarray) – 1d time series of red band of shape(n_obs,)

  • ts_n (numpy.ndarray) – 1d time series of nir band of shape(n_obs,)

  • ts_s1 (numpy.ndarray) – 1d time series of swir1 band of shape(n_obs,)

  • ts_s2 (numpy.ndarray) – 1d time series of swir2 band of shape(n_obs,)

  • ts_t (numpy.ndarray) – 1d time series of thermal band of shape(n_obs,)

  • qas (numpy.ndarray) – 1d time series of QA cfmask band of shape(n_obs,). ‘0’ - clear; ‘1’ - water; ‘2’ - shadow; ‘3’ - snow; ‘4’ - cloud

  • p_cg (float) – probability threshold of change magnitude, by default 0.99

  • conse (int) – consecutive observation number, by default 6

  • pos (int) – position id of the pixel, by default 1

  • output_cm (bool) – ‘True’ means outputting change magnitude and change magnitude dates (OB-COLD), i.e., (cold_results, cm_outputs, cm_outputs_date); ‘False’ will output only cold_results

  • starting_date (int) – the starting date of the whole dataset to enable reconstruct CM_date, all pixels for a tile. should have the same date, only for output_cm is True. by default 0.

  • n_cm (int) – length of outputted change magnitude. Only output_cm == ‘True’. by default 0.

  • cm_output_interval (int) – temporal interval of outputting change magnitudes. Only output_cm == ‘True’. by default 0.

  • b_c2 (bool) – a temporal parameter to indicate if collection 2. C2 needs ignoring thermal band for valid pixel test due to the current low quality. by default True

  • gap_days (int) – define the day number of the gap year for determining i_dense. The COLD will skip the i_dense days to set the starting point of the model. Setting a large value (e.g., 1500) if the gap year is in the middle of the time range. by default 365.25.

  • lam (float) – The lamba parameter used for lasso fitting that controls the regularization of the regression model. When lambda is 0, it is OLS regression.For landsat-like images (i.e., range is [0, 10000]), lambda is suggested to be 20.

Returns:

If output_cm is False, a structured array of dtype = cold_rec_cg is returnd; if output_cm is True, a tuple (cold_results, cm_outputs, cm_outputs_date) will be returned

cold_results: numpy.ndarray

A structured array of dtype = cold_rec_cg

cm_outputs: numpy.ndarray

Change magnitude list, shape (n_cm,)

cm_outputs_date: numpy.ndarray

Change magnitude date list, shape (n_cm,)

Return type:

numpy.ndarray | (numpy.ndarray, numpy.ndarray, numpy.ndarray)

pyxccd.ccd.obcold_reconstruct(dates, ts_b, ts_g, ts_r, ts_n, ts_s1, ts_s2, ts_t, qas, break_dates, conse=6, pos=1, b_c2=True, lam=20)[source]

re-contructructing change records using break dates.

Parameters:

  • dates (numpy.ndarray) – 1d time series of ordinal dates of shape(n_obs,)

  • ts_b (numpy.ndarray) – 1d time series of blue band of shape(n_obs,)

  • ts_g (numpy.ndarray) – 1d time series of green band of shape(n_obs,)

  • ts_r (numpy.ndarray) – 1d time series of red band of shape(n_obs,)

  • ts_n (numpy.ndarray) – 1d time series of nir band of shape(n_obs,)

  • ts_s1 (numpy.ndarray) – 1d time series of swir1 band of shape(n_obs,)

  • ts_s2 (numpy.ndarray) – 1d time series of swir2 band of shape(n_obs,)

  • ts_t (numpy.ndarray) – 1d time series of thermal band of shape(n_obs,)

  • qas (numpy.ndarray) – 1d time series of QA cfmask band of shape(n_obs,). ‘0’ - clear; ‘1’ - water; ‘2’ - shadow; ‘3’ - snow; ‘4’ - cloud

  • break_dates (numpy.ndarray) – 1d time series of break dates obtained from other procedures such as obia

  • conse (int) – consecutive observation number, by default 6

  • pos (int) – position id of the pixel, by default 1

  • b_c2 (bool) – a temporal parameter to indicate if collection 2. C2 needs ignoring thermal band for valid pixel test due to the current low quality. by default True

  • lam (float) – The lamba parameter used for lasso fitting that controls the regularization of the regression model. When lambda is 0, it is OLS regression.For landsat-like images (i.e., range is [0, 10000]), lambda is suggested to be 20.

Returns:

cold_results: numpy.ndarray

A structured array of dtype = cold_rec_cg

Return type:

numpy.ndarray

pyxccd.ccd.sccd_detect(dates, ts_b, ts_g, ts_r, ts_n, ts_s1, ts_s2, qas, p_cg=0.99, conse=6, pos=1, b_c2=True, output_anomaly=False, anomaly_pcg=0.9, anomaly_conse=3, state_intervaldays=0.0, fitting_coefs=False, lam=20)[source]

Offline SCCD algorithm for processing historical time series.

Parameters:

  • dates (numpy.ndarray) – 1d time series of ordinal dates of shape(n_obs,)

  • ts_b (numpy.ndarray) – 1d time series of blue band of shape(n_obs,)

  • ts_g (numpy.ndarray) – 1d time series of green band of shape(n_obs,)

  • ts_r (numpy.ndarray) – 1d time series of red band of shape(n_obs,)

  • ts_n (numpy.ndarray) – 1d time series of nir band of shape(n_obs,)

  • ts_s1 (numpy.ndarray) – 1d time series of swir1 band of shape(n_obs,)

  • ts_s2 (numpy.ndarray) – 1d time series of swir2 band of shape(n_obs,)

  • qas (numpy.ndarray) – 1d time series of QA cfmask band of shape(n_obs,). ‘0’ - clear; ‘1’ - water; ‘2’ - shadow; ‘3’ - snow; ‘4’ - cloud

  • p_cg (float) – Probability threshold of change magnitude, by default 0.99

  • conse (int) – Consecutive observation number, by default 6. No more than 8.

  • pos (int) – Position id of the pixel, by default 1

  • b_c2 (bool) – A temporal parameter to indicate if collection 2. C2 needs ignoring thermal band for valid pixel test due to the current low quality. by default True

  • output_anomaly (bool) – If true, output anomaly breaks where a anomaly is an overdetection of break using conse 3 and threshold = anomaly_tcg, which overdetects anomalies to simulate the situation of NRT scenario and for training a retrospective model, by default False. Note that anomalys is a type of breaks that do not trigger model initialization, against structural breaks (i.e., normal breaks).

  • anomaly_pcg (float) – Change probability threshold for defining spectral anomalies, by default 0.90.

  • anomaly_conse (int) – Consecutive observation number to determine anomaly identification, by default 3. No more than 8.

  • state_intervaldays (float) – If larger than 0, output states at a day interval of state_intervaldays, by default 0.0 (meaning that no states will be outputted). For more details, refer to state-space models (e.g., http://www.scholarpedia.org/article/State_space_model)

  • fitting_coefs (bool) – If True, use curve fitting to get harmonic coefficients for the temporal segment, otherwise use the local coefficients from kalman filter, by default False.

  • lam (float) – The lamba parameter used for lasso fitting that controls the regularization of the regression model. When lambda is 0, it is OLS regression.For landsat-like images (i.e., range is [0, 10000]), lambda is suggested to be 20.

Returns:

If output_anomaly is False and b_output_state is False, sccdoutput will be returned (by default); if output_anomaly is False and b_output_state is True, (sccdoutput, states_info) will be returned; if output_anomaly is True, (sccdoutput, anomalys) will be returned

sccdoutput: SccdOutput

A namedtuple (position, rec_cg, min_rmse, nrt_mode, nrt_model, nrt_queue)

states_info: pd.DataFrame

A table of three state time series (trend, annual, semiannual) for six inputted spectral bands

anomalys: numpy.ndarray

A structured array of dtype = anomaly

Return type:

SccdOutput | (SccdOutput, pd.DataFrame) | (SccdOutput, numpy.ndarray)

pyxccd.ccd.sccd_update(sccd_pack, dates, ts_b, ts_g, ts_r, ts_n, ts_s1, ts_s2, qas, p_cg=0.99, conse=6, pos=1, anomaly_pcg=0.9, predictability_pcg=0.9, lam=20)[source]

SCCD online update for new observations

Parameters:

  • sccd_pack (SccdOutput) – The SCCD results outputted by the last process

  • dates (numpy.ndarray) – 1d new time series of ordinal dates of shape(n_obs,)

  • ts_b (numpy.ndarray) – 1d new time series of blue band of shape(n_obs,)

  • ts_g (numpy.ndarray) – 1d new time series of green band of shape(n_obs,)

  • ts_r (numpy.ndarray) – 1d new time series of red band of shape(n_obs,)

  • ts_n (numpy.ndarray) – 1d new time series of nir band of shape(n_obs,)

  • ts_s1 (numpy.ndarray) – 1d new time series of swir1 band of shape(n_obs,)

  • ts_s2 (numpy.ndarray) – 1d new time series of swir2 band of shape(n_obs,)

  • qas (numpy.ndarray) – 1d new time series of QA cfmask band of shape(n_obs,). ‘0’ - clear; ‘1’ - water; ‘2’ - shadow; ‘3’ - snow; ‘4’ - cloud

  • p_cg (float) – probability threshold of change magnitude, by default 0.99

  • conse (int) – consecutive observation number, by default 6

  • pos (int) – position id of the pixel, by default 1

  • anomaly_pcg (float) – change probability threshold for defining spectral anomalies, by default 0.90.

  • predictability_pcg (float) – probability threshold for predictability test. If not passed, the nrt_mode will return 11. by default 0.90.

  • lam (float) – The lamba parameter used for lasso fitting that controls the regularization of the regression model. When lambda is 0, it is OLS regression.For landsat-like images (i.e., range is [0, 10000]), lambda is suggested to be 20.

Returns:

A namedtuple (position, rec_cg, min_rmse, nrt_mode, nrt_model, nrt_queue)

Return type:

SccdOutput

pyxccd.ccd.sccd_identify(sccd_pack, dist_conse=6, p_cg=0.99, t_cg_singleband=-200, t_angle=45, transform_mode=False)[source]

identify disturbance date for the current monitoring model from SccdOutput

Parameters:

  • sccd_pack (SccdOutput) – S-CCD output

  • dist_conse (int) – Minimum consecutive anomaly number required to identify disturbance, by default 6

  • p_cg (float) – Change magnitude probability threshold to identify disturbance, by default 0.99

  • t_cg_singleband (float) – single-band change magnitude to identify greenning breaks, by default -200 see Eq. 10 in Zhu, Z., Zhang, J., Yang, Z., Aljaddani, A. H., Cohen, W. B., Qiu, S., & Zhou, C. (2020). Continuous monitoring of land disturbance based on Landsat time series. Remote Sensing of Environment, 238, 111116.

  • t_angle_scale100 (float) – Threshold for included angle (scale by 100), by default 45

  • transform_mode (bool) – Transform the mode to untested predictability once the change has been detected. Default isFalse

Returns:

(SccdOutput, int)

The return date is either 0 (no disturbance) or the ordinal date of disturbance occurrence

Return type:

tuple

pyxccd.ccd.cold_detect_flex(dates, ts_stack, qas, lam, p_cg=0.99, conse=6, pos=1, output_cm=False, starting_date=0, n_cm=0, cm_output_interval=0, gap_days=365.25, tmask_b1_index=1, tmask_b2_index=1)[source]

running pixel-based COLD algorithm for any band combination (flexible mode).

Parameters:

  • dates (numpy.ndarray) – 1d time series of ordinal dates of shape(n_obs,)

  • ts_stack (numpy.ndarray) – 2d array of shape (n_obs, nbands), horizontally stacked multispectral time series.

  • qas (numpy.ndarray) – 1d time series of QA cfmask band of shape(n_obs,). ‘0’ - clear; ‘1’ - water; ‘2’ - shadow; ‘3’ - snow; ‘4’ - cloud

  • lam (float) – The lamba parameter used for lasso fitting that controls the regularization of the regression model. When lambda is 0, it is OLS regression.For landsat-like images (i.e., range is [0, 10000]), lambda is suggested to be 20.

  • p_cg (float) – Probability threshold of change magnitude, by default 0.99

  • conse (int) – Consecutive observation number, by default 6

  • pos (int) – position id of the pixel, by default 1

  • output_cm (bool) – ‘True’ means outputting change magnitude and change magnitude dates (OB-COLD), i.e., (cold_results, cm_outputs, cm_outputs_date); ‘False’ will output only cold_results

  • starting_date (int) – The starting date of the whole dataset to enable reconstruct CM_date, all pixels for a tile should have the same date, only for output_cm is True. by default 0.

  • n_cm (int) – Length of outputted change magnitude. Only output_cm == ‘True’. by default 0.

  • cm_output_interval (int) – Temporal interval of outputting change magnitudes. Only output_cm == ‘True’. by default 0.

  • gap_days (int) – Define the day number of the gap year for determining i_dense. The COLD will skip the i_dense days to set the starting point of the model. Setting a large value (e.g., 1500) if the gap year is in the middle of the time range. by default 365.25.

  • tmask_b1_index (int) – The first band id for tmask. Started from 1. The default CCDC is 2 (green)

  • tmask_b2_index (int) – The second band id for tmask. Started from 1. The default CCDC is 5 (swir1)

Returns:

If output_cm is False, a structured array of dtype = cold_rec_cg is returnd; if output_cm is True, a tuple (cold_results, cm_outputs, cm_outputs_date) will be returned

cold_results: numpy.ndarray

A structured array of dtype = cold_rec_cg

cm_outputs: numpy.ndarray

Change magnitude list, shape (n_cm,)

cm_outputs_date: numpy.ndarray

Change magnitude date list, shape (n_cm,)

Return type:

numpy.ndarray | (numpy.ndarray, numpy.ndarray, numpy.ndarray)

pyxccd.ccd.sccd_detect_flex(dates, ts_stack, qas, lam, p_cg=0.99, conse=6, pos=1, b_c2=True, output_anomaly=False, anomaly_pcg=0.9, anomaly_conse=3, state_intervaldays=0.0, tmask_b1_index=1, tmask_b2_index=1, fitting_coefs=False, trimodal=False)[source]

Offline SCCD algorithm for processing historical time series for any band combination.

Parameters:

  • dates (numpy.ndarray) – 1d time series of ordinal dates of shape(n_obs,)

  • ts_stack (numpy.ndarray) – 2d array of shape (n_obs, nbands), horizontally stacked multispectral time series. The maximum band number is 10..

  • qas (numpy.ndarray) – 1d time series of QA cfmask band of shape(n_obs,). ‘0’ - clear; ‘1’ - water; ‘2’ - shadow; ‘3’ - snow; ‘4’ - cloud

  • lam (float) – The lamba parameter used for lasso fitting that controls the regularization of the regression model. When lambda is 0, it is OLS regression.For landsat-like images (i.e., range is [0, 10000]), lambda is suggested to be 20.

  • p_cg (float) – Probability threshold of change magnitude, by default 0.99

  • conse (int) – Consecutive observation number, by default 6

  • pos (int) – Position id of the pixel, by default 1

  • b_c2 (bool) – A temporal parameter to indicate if collection 2. C2 needs ignoring thermal band for valid pixel test due to the current low quality. by default True

  • output_anomaly (bool) – If true, output anomaly breaks where a anomaly is an overdetection of break using conse 3 and threshold = anomaly_tcg, which overdetects anomalies to simulate the situation of NRT scenario and for training a retrospective model, by default False. Note that anomalys is a type of breaks that do not trigger model initialization, against structural breaks (i.e., normal breaks).

  • anomaly_pcg (float) – Change probability threshold for defining spectral anomalies anomalys, by default 0.90.

  • anomaly_conse (int) – Consecutive observation number to determine anomaly identification, by default 3

  • state_intervaldays (float) – If larger than 0, output states at a day interval of state_intervaldays, by default 0.0 (meaning that no states will be outputted). For more details, refer to state-space models (e.g., http://www.scholarpedia.org/article/State_space_model)

  • fitting_coefs (bool) – If True, use curve fitting to get harmonic coefficients for the temporal segment, otherwise use the local coefficients from kalman filter, by default False.

  • tmask_b1_index (int) – The first band id for tmask. Started from 1. The default CCDC is 2 (green)

  • tmask_b2_index (int) – The second band id for tmask. Started from 1. The default CCDC is 5 (swir1)

  • trimodal (bool) – indicate if trimodal component (the period is four months) is added into the temporal coefficients. If true, the harmonic models will be 8-coefs; if false, the harmonic models will be 6-coefs;

Returns:

  • SccdOutput | (SccdOutput, pd.DataFrame)

  • If b_output_state is False, sccdoutput will be returned (by default);

  • if b_output_state is True, (sccdoutput, states_info) will be returned; –

    sccdoutput: SccdOutput

    A namedtuple (position, rec_cg, min_rmse, nrt_mode, nrt_model, nrt_queue)

    states_info: pd.DataFrame

    A table of three state time series (trend, annual, semiannual) for nbands inputted spectral bands

pyxccd.ccd.sccd_update_flex(sccd_pack, dates, ts_stack, qas, lam, p_cg=0.99, conse=6, pos=1, b_c2=True, anomaly_pcg=0.9, predictability_pcg=0.9, tmask_b1_index=1, tmask_b2_index=1, trimodal=False)[source]

SCCD online update for new observations for any band combination

Parameters:

  • sccd_pack (namedtuple)

  • dates (numpy.ndarray) – 1d new time series of ordinal dates of shape(n_obs,)

  • ts_stack (numpy.ndarray) – 2d array of shape (n_obs,), horizontally stacked multispectral time series. The maximum band number is 10.

  • qas (numpy.ndarray) – 1d new time series of QA cfmask band of shape(n_obs,). ‘0’ - clear; ‘1’ - water; ‘2’ - shadow; ‘3’ - snow; ‘4’ - cloud

  • lam (float) – The lamba parameter used for lasso fitting that controls the regularization of the regression model. When lambda is 0, it is OLS regression.For landsat-like images (i.e., range is [0, 10000]), lambda is suggested to be 20.

  • p_cg (float) – Probability threshold of change magnitude, by default 0.99

  • conse (int) – Consecutive observation number, by default 6

  • pos (int) – Position id of the pixel, by default 1

  • b_c2 (bool) – A temporal parameter to indicate if collection 2. C2 needs ignoring thermal band for valid pixel test due to the current low quality. by default True

  • anomaly_pcg (float) – Change probability threshold for defining spectral anomalies /anomaly, by default 0.90.

  • predictability_pcg (float) – Probability threshold for predictability test. If not passed, the nrt_mode will return 11. by default 0.90.

  • trimodal (bool) – indicate if trimodal component (the period is four months) is added into the temporal coefficients. If true, the harmonic models will be 8-coefs; if false, the harmonic models will be 6-coefs;

Returns:

A namedtuple (position, rec_cg, min_rmse, nrt_mode, nrt_model, nrt_queue)

Return type:

SccdOutput