language: cn
model_unique_abbr: k_means_clustering_sklearn
version: 1.0
identification:
  docker_image_name: k_means_clustering:1.0-sklearn0.24.0
  model_name: KMeans聚类（矢量点-CSV）
  semantic: k-means 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]
  - 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]
  - arg_name: n_clusters
    is_single_en_dash: false
    param_type: param
    name: 聚类数量
    description: 聚类形成的簇个数，整数型数值，最小值为2。
    data_type: int
    data_semantic: number of clusters
    specification:
      default: 5
      range:
      - "(1,)"
  - arg_name: init
    is_single_en_dash: false
    param_type: param
    name: 聚类中心初始化方法
    description: 为k-均值聚类选择初始聚类中心方法。‘k-means++’：智能地选择初始聚类中心进行k均值聚类；‘random’：随机选择初始聚类中心进行k均值聚类。
    data_type: enum
    data_semantic: Method for initial cluster centers
    specification:
      default: k-means++
      enum:
      - k-means++
      - random
  - arg_name: max_iter
    is_single_en_dash: false
    param_type: param
    name: 最大迭代次数
    description: 单次运行的k-means算法的最大迭代次数，整数型数值，建议填写值为300。
    data_type: int
    data_semantic: max iter
    specification:
      default: 300
      range:
      - "(0,)"
  - arg_name: tol
    is_single_en_dash: false
    param_type: param
    name: 容差
    description: 连续两次迭代之间的聚类中心的差异阈值，以声明收敛。float型数值，建议填写0.0001。
    data_type: float
    data_semantic: tolerance
    specification:
      default: 1e-4
      range:
      - "(0,)"
  - arg_name: algorithm
    is_single_en_dash: false
    param_type: param
    name: Kmeans算法
    description: K-means要使用的算法。经典的EM式算法是“full”的；对于具有定义良好的簇的数据，“elkan”变化更为有效。
    data_type: enum
    data_semantic: algorithm to use
    specification:
      default: auto
      enum:
      - elkan
      - auto
      - full
  - arg_name: output
    is_single_en_dash: false
    param_type: output_data
    name: 聚类结果
    description: 带有簇标签的聚类结果，结果保存为csv文件。聚类标签为0，1，2...。。新增列名默认为label，若原数据中已有该列，则添加从序号1编号，如label1、label2...。
    data_type: csv
    data_semantic: cluster_result
  groups:
  - group_id: ixy
    group_name: 输入数据XY列
    group_param_arg_names:
    - input
    - x_field
    - y_field
application:
  domain: 空间点聚类
  objective: 对空间点数据进行聚类划分
  dimension:
  - 二维
  mechanism: 随机选取k个空间点对象作为初始簇中心，通过“距簇中心最近”原则将所有地理空间对象分配给最近的簇，据此更新各簇中心位置，迭代上述过程直到满足终止条件
operation:
  usage: 该算法需要三个参数，X坐标列(x field)，Y坐标列(y field)，聚类数量(number of clusters)。
  exec_example:
  - docker run -v $(pwd):/data k_means_clustering:1.0-sklearn0.24.0 --input /data/data.csv --x_field x --y_field y --output /data/clustering_result.csv
  - docker run -v $(pwd):/data k_means_clustering:1.0-sklearn0.24.0 --input /data/data.csv --x_field x --y_field y --n_clusters 3 --init  random --output /data/clustering_result.csv
  output_display:
  - 针对聚类结果中label列，用不同颜色绘制不同标签的二维点数据。
  license:
  - sklearn-BSD
technique:
  language:
  - Python
  os:
  - Linux
  - Windows
  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:
  - "MacQueen, J. 1967. Some methods for classification and analysis of multivariate observations. Proceedings of the 5th Berkeley Symposium on Mathematical Statistics and Probability, 1(14),281–297."
  - https://scikit-learn.org/stable/modules/generated/sklearn.cluster.KMeans.html#sklearn.cluster.KMeans
