language: cn
model_unique_abbr: dbscan_clustering_sklearn_test
version: 1.0
identification:
  docker_image_name: dbscan_clustering:1.0-sklearn0.24.0
  model_name: DBSCAN聚类（矢量点-CSV）-test
  semantic: dbscan clustering
  description: 基于密度可达的典型聚类算法，将空间点对象无监督地划分为若干高密度的空间簇和噪声。
  category_application: 诊断型
  category_data:
  - 矢量点数据
  keywords:
  - 基于密度的空间聚类
  - 噪声
parameter_info:
  parameters:
  - arg_name: input
    is_single_en_dash: false
    param_type: input_data
    name: 空间点数据
    description: 待聚类的空间点数据文件，文件格式为csv，数据中需包含X、Y坐标列
    data_type: csv
    data_semantic: cluster data

  - arg_name: x_field
    is_single_en_dash: false
    param_type: param
    name: X坐标字段
    description: X坐标列在输入文件中的列名
    data_type: str
    data_semantic: x field
    param_switches:
    - switch_arg_name: input
      switch_arg_value_regex: csv$
      switch_arg_value_examples: [big_dataset.csv, small_dataset.csv]
    specification:
      default: x

  - arg_name: y_field
    is_single_en_dash: false
    param_type: param
    name: Y坐标字段
    description: Y坐标列在输入文件中的列名
    data_type: str
    data_semantic: y field
    param_switches:
    - switch_arg_name: input
      switch_arg_value_regex: csv$
      switch_arg_value_examples: [big_dataset.csv, small_dataset.csv]
    specification:
      default: y

  - arg_name: eps
    is_single_en_dash: false
    param_type: param
    name: 邻域半径
    description: 两个点不能属于同一簇的距离阈值。默认为空，若该值为空，则自适应计算计算密度值，并根据异常密度值计算相应的eps；若输入值，则需要输入大于0的float类型数值。
    is_required: false
    data_type: float
    data_semantic: neighborhood radius
    specification:
      range:
      - "(0,)"
  - arg_name: min_pts
    is_single_en_dash: false
    param_type: param
    name: 最小邻居数
    description: 生成簇的最小点数。默认为空，若该值为空，则自适应计算计算密度值，并根据异常密度值计算相应的min_pts；若输入值，则需要输入大于0的float类型数值。
    is_required: false
    data_type: int
    data_semantic: minimum points
    specification:
      range:
      - "(0,)"
  - arg_name: metric
    is_single_en_dash: false
    param_type: param
    name: 距离度量方法
    description: 点间距离的度量方法
    is_required: false
    data_type: enum
    data_semantic: metric algorithm
    specification:
      default: euclidean
      enum:
      - cityblock
      - cosine
      - euclidean
      - l1
      - l2
      - manhattan
  - arg_name: algorithm
    is_single_en_dash: false
    param_type: param
    name: 计算逐点距离和查找最近邻方法
    description: 用于计算逐点距离和查找最近邻的算法。‘brute’表示蛮力实现，‘kd_tree’表示KD树实现，‘ball_tree’表示的球树实现， ‘auto’则会在上面三种算法中做权衡，选择一个拟合最好的最优算法。
    is_required: false
    data_type: enum
    data_semantic: nearestNeighbors algorithm
    specification:
      default: auto
      enum:
      - auto
      - ball_tree
      - kd_tree
      - brute
  - arg_name: leaf_size
    is_single_en_dash: false
    param_type: param
    name: 最大叶子节点数
    description: 索引树最大叶子节点数。使用KD树或者球树时， 停止建子树的叶子节点数量的阈值。这个值越小，则生成的KD树或者球树就越大，层数越深，建树时间越长。当algorithm为‘auto’或‘brute’时，此参数无效。；若输入值，则需要输入大于0的float类型数值。
    is_required: false
    data_type: int
    data_semantic: nearestNeighbors search algorithm
    param_switches:
    - switch_arg_name: algorithm
      switch_arg_value_regex: tree$
      switch_arg_value_examples: [ball_tree, kd_tree]
    specification:
      default: 30
      range:
      - "(0,)"
  - arg_name: n_jobs
    is_single_en_dash: false
    param_type: param
    visible: false
    name: 并行计算数
    description: 并行计算数。如果为 1，则不使用并行；如果为 -1，则使用所有 CPU；对于n_jobs低于 -1，使用 (n_cpus + 1 + n_jobs)。例如 n_jobs = -2，使用n_cpus -1个CPU。
    is_required: false
    data_type: int
    data_semantic: the number of parallel jobs
    specification:
      default: -1
  - arg_name: output
    is_single_en_dash: false
    param_type: output_data
    name: 聚类结果
    description: 带有簇标签的聚类结果，结果保存为csv格式的文件。新增列名默认为label，若原数据中已有该列，则添加从序号1编号，如label1、label2...。聚类标签为1，2...，噪声标签为-1。
    data_type: csv
    data_semantic: cluster_result
  groups:
  - group_id: ixy
    group_name: 输入数据XY列
    group_param_arg_names:
    - input
    - x_field
    - y_field
  - group_id: tree_leaf
    group_name: 树叶子节点数
    group_param_arg_names:
    - algorithm
    - leaf_size
application:
  domain: 空间点聚类
  objective: 在具有噪声对象的空间点数据中发现任意形状的高密度空间簇
  dimension:
  - 二维
  mechanism: 将空间点对象邻域半径内邻居数量定义为密度，任选一个未被访问的空间点对象，若其密度大于指定阈值，则与其邻域对象密度相连为一个簇，迭代访问簇内其他未被访问对象，重复上述过程直到所有空间点对象均被访问完毕，最终提取所有密度相连的簇
operation:
  usage: 该算法需要四个参数，X坐标列，Y坐标列，聚类点之间允许的最大距离，生成簇的最小点数。
  exec_example:
  - docker run -v $(pwd):/data dbscan_clustering:1.0-sklearn0.24.0 --input /data/data.csv --output /data/clustering_result.csv
  - docker run -v $(pwd):/data dbscan_clustering:1.0-sklearn0.24.0 --input /data/data.csv --eps 1 --min_pts 5 --output /data/clustering_result.csv
  - docker run -v $(pwd):/data dbscan_clustering:1.0-sklearn0.24.0 --input /data/data.csv --eps 1 --min_pts 5 --metric cityblock --algorithm kd_tree --leaf_size 25 --output /data/clustering_result.csv
  output_display:
  - 针对聚类结果中label列，用不同颜色绘制不同标签的二维点数据。
  license:
  - sklearn-BSD
technique:
  language:
  - Python
  os:
  - Linux
  - Windows
  parallel:
  - multiprocessing
  hardware:
  - CPU
  dependencies:
  - name: scikit-learn
    version: 0.24.0
source:
  maintainer: Minghui Li
  organization: Central South University
  contact: 286381830@qq.com
  integrated_softwares:
  - name: scikit-learn
    version: 0.24.0
    license: BSD
  references:
  - "Ester, M., Kriegel, H. P., Sander, J., et al. 1996. A density-based algorithm for discovering clusters in large spatial databases with noise. Proceedings of the 2nd International Conference on Knowledge Discovery and Data Mining, 96(34) 226–231."
  - https://scikit-learn.org/stable/modules/generated/sklearn.cluster.DBSCAN.html#sklearn.cluster.DBSCAN
