language: cn
model_unique_abbr: csu_workflow_mode2_clusters
version: 1.0
identification:
  docker_image_name: csu_workflow_mode2_clusters:3.0
  model_name: Geo-SOM时空聚类与分区
  semantic: mode2_clusters
  description: 利用GeoSOM算法实现站点或者点位置的时空聚类与分区。通过整合地理空间信息与时间序列数据，模型有效捕捉站点的空间和时序特征。GeoSOM算法通过自组织特征映射（SOM）技术，结合地理约束，精准识别站点之间的相似性和差异性，实现对复杂环境变量的高效聚类与分区。
  category_application: 预测型
  category_data:
  - 矢量点数据
  keywords:
  - 时空聚类
  - Geo-Som
  - 聚类分区
parameter_info:
  parameters:
  - arg_name: train_data_folder
    is_single_en_dash: false
    param_type: input_data
    name: 数据集文件夹
    description: 输入的是一个包含目标变量以及相关特征历史数据集的文件夹。数据以csv文件的格式进行保存。每个文件包含某个时间段某地区所有点的位置信息以及各类数据信息，这些信息包含在每个csv文件的列名中，示例：station_id,feature1,feature2,feature3,target,x,y。
    data_type: csv
    data_semantic: train_data_folder

  - arg_name: best_arg
    is_single_en_dash: false
    param_type: input_data
    name: 最佳的阈值结果
    description: 输出最佳的阈值结果文件，保存的文件格式为json。
    data_type: json
    data_semantic: best_arg

  - arg_name: variable
    is_single_en_dash: false
    param_type: param
    name: 自变量或者特征名称
    description: 选取数据集中自变量或者特征列名，使用英文逗号隔开，填写示例：feature1,feature2,feature3
    data_type: str
    data_semantic: variable
    specification: #选填。参数规格
      default: u10,v10,t2m,sp,tp,AQI,PM10,NO2,CO,O3,SO2

  - arg_name: air_quality
    is_single_en_dash: false
    param_type: param
    name: 待预测的目标变量
    description: 需要预测的目标变量，如：target。
    data_type: str
    data_semantic: air quatity index that needs to be predicted
    specification:
      default: PM2.5

  - arg_name: geo_coord
    is_single_en_dash: false
    param_type: param
    name: 站点或者位置的地理坐标
    description: 选取数据集中站点或者位置的地理坐标列名，使用英文逗号隔开，填写示例： x,y
    data_type: str
    data_semantic: geo_coord
    specification:
      default: x,y

  - arg_name: X
    is_single_en_dash: false
    param_type: param
    name: 聚类分区的行数
    description: 用于聚类的行数。
    data_type: int
    data_semantic: number of rows for clustering
    specification:
      default: 2

  - arg_name: Y
    is_single_en_dash: false
    param_type: param
    name: 聚类分区的列数
    description: 用于聚类的列数。
    data_type: int
    data_semantic: number of columns for clustering
    specification:
      default: 2

  - arg_name: N_epoch
    is_single_en_dash: false
    param_type: param
    name: GeoSOM算法迭代次数
    description: GeoSOM算法的迭代次数。
    data_type: int
    data_semantic: number of iterations for the GeoSOM algorithm
    specification:
      default: 100

  - arg_name: k
    is_single_en_dash: false
    param_type: param
    name: 地理邻域大小参数
    description: 用于确定地理邻域大小的参数，根据具体的地理坐标系进行填写。这个参数的意义是在多大的半径范围内进行搜索邻居，默认值为100。
    data_type: int
    data_semantic: parameter to determine the size of the geographical neighborhood
    specification:
      default: 100

  - arg_name: sigma
    is_single_en_dash: false
    param_type: param
    name: 初始邻域大小阈值
    description: 用于确定邻域大小的初始阈值，在训练初期，定义了与获胜节点（即最佳匹配单元）一起更新的节点范围。这个范围会随着训练的进行逐渐减小，默认值为1.5。
    data_type: float
    data_semantic: initial threshold to determine the size of the neighborhood
    specification:
      default: 1.5

  - arg_name: cluster_result
    is_single_en_dash: false
    param_type: output_data
    name: 聚类分区结果
    description: 输出聚类分区结果文件，文件中有一列"region"，里面的数值代表每个点所属的聚类分区。文件格式csv。
    data_type: csv
    data_semantic: cluster_result

  - arg_name: iVariables
    is_single_en_dash: false
    param_type: output_data
    name: 各分区中的最优自变量和权重结果
    description: 输出各分区中的最优自变量和权重结果文件，文件格式json。
    data_type: json
    data_semantic: iVariables
application:
  domain: Geo-SOM时空聚类与分区
  objective: 利用GeoSOM算法实现空气站点的时空聚类与分区。通过整合地理空间信息与时间序列数据，模型有效捕捉空气质量监测站点的空间和时序特征。。
  dimension:
  - 多维
  mechanism: 使用GeoSOM算法进行聚类分区
operation:
  usage: 该算法需要十二个参数，数据集文件夹，最佳的阈值结果，自变量或者特征名称，待预测的目标变量，站点或者位置的地理坐标，聚类行数，聚类列数，GeoSOM算法迭代次数，地理邻域大小参数，初始邻域大小阈值，区域结果输出，各分区中的最优自变量和权重结果。
  exec_example:
  - docker run -v $(pwd):/data mode2_clusters:1.0 --train_data_folder /data/data/ --input_best_arg /data/best_arg.json --variable u10 v10 t2m sp tp AQI PM10 NO2 CO O3 SO2 --air_quality PM2.5 --geo_coord x y --X 2 --Y 2 --N_epoch 100 --k 100 --sigma 1.5 --output_cluster /data/clusters.csv --output_iVariables /data/iVariables.json
  output_display:
  - 不需要绘制可视化图表。
  license:
  - BSD
technique:
  language:
  - Python
  os:
  - Linux
  - Windows
  dependencies:
  - name: pandas
    version: 1.3.3
  - name: numpy
    version: 1.21.2
  - name: scikit-learn
    version: 0.24.2
source:
  maintainer: Yixun Liu
  organization: Central South University
  contact: 1907269689@qq.com
  integrated_softwares:
  - name: pandas
    version: 1.3.3
    license: BSD
  - name: numpy
    version: 1.21.2
    license: BSD
  - name: scikit-learn
    version: 0.24.2
    license: BSD
  references:
  - https://scikit-learn.org/stable/modules/generated/sklearn.linear_model.LinearRegression.html