Package: pycold
PYCOLDA Python library for COntinuous monitoring of Land Disturbance (COLD) and its extension algorithms at the speed of C languageThe base algorithms were mostly written using C wrapped in Python, and
have been verified withMATLAB version. The C codes of the package were partially modified fromC-CCDCdeveloped by USGS.This library provides:Original COntinuous monitoring of Land Disturbance (COLD): a upgraded CCDC algorithm proposed by Dr.Zhe Zhu for offline satellite-based time-series analysisStochastic Continuous Change Detection (S-CCD, a near real-time and short-memory implementation of COLD)Object-based COLD (OB-COLD), integrating spatial information into COLD by using a ‘change object’ viewThe recent applications of S-CCD and OB-COLD could be found inCONUS Land Watcher1. Pre-workClone github repo to your local code directory for the first use:gitclonehttps://github.com/GERSL/pycold.gitOr you call pull the recent repo if you want to update the existing
pycold repo:gitpullorigindevel:devel2. InstallationThe steps to install this library in development mode are consolidated
into a single script:run_developer_setup.sh.  On debian-based systems,
this will install all of the developer requirements and ensure you are setup
with a working opencv-python-headless and gdal Python modules, as well as other
requirements and then it will compile and install pycold in editable
development mode.The following is an overview of these details and alternative choices that
could be made.2.1 Install Required LibrariesThe ZLIB, GSL libraries are required.For Ubuntu/Debian systems, they can be installed via:sudoapt-getupdatesudoapt-getinstallbuild-essential-ysudoapt-getinstallzlib1g-dev-ysudoapt-getinstallgfortran-ysudoapt-getinstalllibgsl-dev-yOn CentOS systems run:sudoapt-getinstallgccgcc-c++make-ysudoapt-getinstallzlib-devel-ysudoapt-getinstallgcc-gfortran-y# Yum provides an gsl 1.5, but we need 2.7
# sudo apt-get install gsl-devel -ycurlhttps://ftp.gnu.org/gnu/gsl/gsl-2.7.1.tar.gz>gsl.tar.gz&&tarxfvgsl.tar.gz&&cdgsl-2.7.1&&./configure--prefix=/usr--disable-static&&make&&makeinstall2.2 Compile and Install PYCOLDThe following instructure assume you are inside a Python virtual environment
(e.g. via conda or pyenv).# Install required packagespipinstall-rrequirements.txtNote that in all cases gdal will need to be manually installed.  The following
step will install GDAL from acustom pypi servercontaining precompiled wheels.# Install GDAL (note-this must be done manually)pipinstall-rrequirements/gdal.txtAdditionally, to access thecv2module, pycold will require eitheropencv-pythonoropencv-python-headless, which are mutually exclusive.
This is exposed as optional dependencies in the package via either “graphics”
or “headless” extras.  Headless mode is recommended as it is more compatible
with other libraries. These can be obtained manually via:pipinstall-rrequirements/headless.txt# XOR (choose only one!)pipinstall-rrequirements/graphics.txtOption 1: Install in development modeFor details on installing in development mode see thedeveloper install instructions.We note that all steps in the above document and other minor details are
consolidated in therun_developer_setup.shscript.Option 2: Build and install a wheelScikit-build will invoke CMake and build everything. (you may need to
remove any existing_skbuilddirectory).python-mbuild--wheel.Then you can pip install the wheel (the exact path will depend on your system
and version of python).pipinstalldist/pycold-0.1.0-cp38-cp38-linux_x86_64.whlYou can also use thebuild_wheels.shscript to invoke cibuildwheel to
produce portable wheels that can be installed on different than they were built
on. You must have docker and cibuildwheel installed to use this.Option 3: build standalone binaries with CMake by itself (recommended
for C development)mkdir-pbuildcdbuildcmake..makeOption 4: Use a docker image.This repo provides dockerfiles that illustrate a reproduceable method for
compling and installing PYCOLD. Seedockerfiles/README.rstfor details.3. Using pycold for pixel-based processingCOLD:frompycoldimportcold_detectcold_result=cold_detect(dates,blues,greens,reds,nirs,swir1s,swir2s,thermals,qas)S-CCD:# require offline processing for the first timefrompycoldimportsccd_detect,sccd_updatesccd_pack=sccd_detect(dates,blues,greens,reds,nirs,swir1s,swir2s,thermals,qas)# then use sccd_pack to do recursive and short-memory NRT updatesccd_pack_new=sccd_update(sccd_pack,dates,blues,greens,reds,nirs,swir1s,swir2s,thermals,qas)Q&AQ1: Has pycold been verified with original Matlab codes?Re: yes, multiple rounds of verification have been done. Comparison
based on two testing tiles shows that pycold and Matlab version have
smaller than <2% differences for breakpoint detection and <2%
differences for harmonic coefficients; the accuracy of pycold was also
tested against the same reference dataset used in the original COLD
paper (Zhu et al., 2020), and pycold reached the same accuracy (27%
omission and 28% commission) showing that the discrepancy doesn’t hurt
accuracy. The primary source for the discrepancy is mainly from the
rounding: MATLAB uses float64 precision, while pycold chose float32 to
save the run-time computing memory and boost efficiency.Q2: how much time for production of a tile-based disturbance map (5000*5000 pixels) using pycold?Re: I tested it in UCONN HPC environment (200 EPYC7452 cores): for
processing a 40-year Landsat ARD tile (1982-2021), the stacking
typically takes 15 mins; per-pixel COLD processing costs averagely 1
hour; exporting maps needs 7 mins.4. CitationsIf you make use of the algorithms in this repo (or to read more about them),
please cite (/see) the relevant publications from the following list:[COLD]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.[S-CCD]Ye, S., Rogan, J., Zhu, Z., & Eastman, J. R. (2021). A near-real-time
approach for monitoring forest disturbance using Landsat time series:
Stochastic continuous change detection.Remote Sensing of Environment,252, 112167.[OB-COLD] Ye, S., Zhu, Z., & Cao, G., (2022). Object-based continuous monitoring
of land disturbance. Remote Sensing of Environment (in revision)