language: cn
model_unique_abbr: birch_clustering_sklearn
version: 1.0
identification:
  docker_image_name: birch_clustering:1.0-sklearn0.24.0
  model_name: Birch聚类
  semantic: birch 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: threshold
    is_single_en_dash: false
    param_type: param
    name: 阈值
    description: 叶节点每个CF的最大样本半径阈值。它决定了每个聚类特征里所有样本形成的超球体的半径阈值，threshold越小，则聚类特征树(CF Tree)的建立阶段的规模会越大，即BIRCH算法第一阶段所花的时间和内存会越多。
    is_required: false
    data_type: float
    data_semantic: threshold
    specification:
      default: 0.1
      range:
      - "(0,)"
  - arg_name: branching_factor
    is_single_en_dash: false
    param_type: param
    name: 分支因子
    description: 聚类特征树(CF Tree)里所有节点的最大聚类特征数。即CF Tree内部节点的最大CF数以及叶子节点的最大CF数。
    is_required: false
    data_type: int
    data_semantic: branching factor
    specification:
      default: 50
      range:
      - "(0,)"
  - arg_name: n_clusters
    is_single_en_dash: false
    param_type: param
    name: 聚类数量
    description: 填写将数据分为多少个类别，int类型。
    is_required: true
    data_type: int
    data_semantic: the number of clusters
    specification:
      range:
      - "(1,)"
  - arg_name: compute_labels
    is_single_en_dash: false
    param_type: param
    name: 计算标签
    description: 是否标示类别输出，默认为true。
    is_required: false
    data_type: bool
    data_semantic: compute labels
    specification:
      default: "true"

  - 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: xy
    group_name: 输入数据XY列
    group_param_arg_names:
    - input
    - x_field
    - y_field
application:
  domain: 空间点聚类
  objective: 超大规模数据集聚类
  dimension:
  - 二维
  mechanism: 综合了层次算法和迭代的重定位方法，将点与点之间的聚类，转换成为点与簇中心之间的聚类
operation:
  usage: 该算法需要三个参数，X坐标列，Y坐标列，聚类数量。
  exec_example:
  - docker run -v $(pwd):/data birch_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 birch_clustering:1.0-sklearn0.24.0 --input /data/data.csv --x_field x --y_field y  --threshold 0.1 --branching_factor False --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:
  - "Zhang, T., Ramakrishnan, R., Livny, M. 1996. BIRCH,an efficient data clustering method for very large databases. ACM SIGMOD Record, 25(2),103–114."
  - https://scikit-learn.org/stable/modules/generated/sklearn.cluster.Birch.html
