shp: Spatially Homogeneous Pixels Identification

moraine.cli.shp 的命令（源码）；同样的函数在 Python 里以 mc.<name>(...) 调用（import moraine.cli as mc）。下面的帮助由 docstring 生成，与 moraine COMMAND --help 相同（docstring 为英文）。

命令	摘要
shp-test	SHP identification through hypothesis test, and the selection of the SHPs at the level alpha.
select-shp	Select SHP based on pvalue of SHP test.

shp-test

SHP identification through hypothesis test, and the selection of the SHPs at the level alpha.

moraine shp-test --rslc STR --is_shp STR --shp_num STR --az_half_win VALUE --r_half_win VALUE [--alpha VALUE] [--pvalue STR] [--method STR] [--chunks INT INT] [--cuda | --no-cuda] [--processes VALUE] [--n_workers VALUE] [--threads_per_worker VALUE]

参数	类型	默认值	说明
--rslc	str	必需	input rslc stack, shape (nlines, width, nimages)
--is_shp	str	必需	output True for the SHPs of each pixel, i.e. the pixels of its window whose p value is at least alpha, shape (nlines, width, 2az_half_win+1, 2r_half_win+1), bool
--shp_num	str	必需	output number of SHPs of each pixel, shape (nlines, width), int32
--az_half_win	int	必需	azimuth half window size
--r_half_win	int	必需	range half window size
--alpha	float	0.05	significance level of the test, in (0, 1): a pixel is an SHP of the centre pixel of its window when its p value is at least alpha; a larger alpha keeps fewer SHPs
--pvalue	str	None	output p value of the test between each pixel and the pixels in its window, same shape as is_shp, float32; needed only to select the SHPs again at another level with select-shp
--method	str	None	test method, only 'ks' (two-sample Kolmogorov-Smirnov) is implemented. Default: 'ks'
--chunks	tuple[int, int]	None	(azimuth, range) processing chunk size, same as rslc by default
--cuda	bool	False	if use cuda for processing, false by default
--processes		None	use processes (True) or threads (False) for the workers, only for cpu processing. Default: False
--n_workers		None	number of workers. Default: 1 for cpu, one per GPU for cuda
--threads_per_worker		None	tasks a worker runs at the same time. Default: 1

全局选项：--json、--traceback、--log FILE、-q / --quiet（约定）。

在 pipeline 文件中（examples/03_ds.toml，步骤 shp_test）：

[[step]]
name = "shp_test"                 # two sample KS test in a 7 x 27 window (about 100 m x 60 m on the ground), SHPs = p value >= alpha
run = "shp-test"
rslc = "raw/rslc.zarr"
az_half_win = 3
r_half_win = 13
is_shp = "ds/ras_is_shp.zarr"
shp_num = "ds/ras_shp_num.zarr"
alpha = 0.05                      # significance level; add pvalue = "ds/ras_pvalue.zarr" to keep the p values

在 Python 中：

import moraine.cli as mc
mc.shp_test(rslc, is_shp, shp_num, az_half_win, r_half_win, alpha=0.05, pvalue=None, method=None, chunks=None, cuda=False, processes=None, n_workers=None, threads_per_worker=None)

select-shp

Select SHP based on pvalue of SHP test.

moraine select-shp --pvalue STR --is_shp STR --shp_num STR [--alpha VALUE] [--chunks INT INT] [--processes | --no-processes] [--n_workers VALUE] [--threads_per_worker VALUE]

参数	类型	默认值	说明
--pvalue	str	必需	input pvalue of hypothesis test
--is_shp	str	必需	output bool array, True for SHPs, same shape as pvalue
--shp_num	str	必需	output number of SHPs of each pixel, shape (nlines, width), int32
--alpha	float	0.05	significance level of the test, in (0, 1): a pixel is an SHP of the centre pixel of its window when its p value is at least alpha, i.e. the test does not reject that both have the same distribution; a larger alpha keeps fewer SHPs
--chunks	tuple[int, int]	None	(azimuth, range) processing chunk size, same as pvalue by default
--processes		False	use processes for the workers instead of threads, the default is False
--n_workers		1	number of workers, the default is 1
--threads_per_worker		1	tasks a worker runs at the same time

全局选项：--json、--traceback、--log FILE、-q / --quiet（约定）。

在 pipeline 文件中（示例 pipeline 未使用此命令；只列必需参数）：

[[step]]
name = "select_shp"
run = "select-shp"
pvalue = "..."
is_shp = "..."
shp_num = "..."

在 Python 中：

import moraine.cli as mc
mc.select_shp(pvalue, is_shp, shp_num, alpha=0.05, chunks=None, processes=False, n_workers=1, threads_per_worker=1)

数组函数 mr.select_shp 对内存中的 numpy / cupy 数组做同样的事。