自定义分析工具

在 FlexDMO 平台中，您可以在实验模块（Experiment module）通过自定义分析工具来根据实验结果分析算法的性能表现和优化效果。分析工具是平台的重要组成部分，它能够对算法运行结果进行全面的统计分析、性能评估和可视化处理，为用户提供详细的算法性能报告和科学的决策支持。

自定义分析工具允许您根据特定的研究需求和分析目标，实现个性化的算法评估方法。无论是收敛性分析、多样性评估、还是统计假设检验，您都可以通过自定义分析工具来进行分析。本文档将详细介绍如何实现自定义分析工具，包括目录结构创建、配置文件设置、核心实现方法以及在平台中的集成使用。

1. 创建分析工具目录结构

首先，在 results_output/ 目录下创建您的分析工具目录，例如 MIGD_table（统计不同算法的MIGD指标）：

results_output/MIGD_table/
  ├── main.py         # 分析工具主实现文件
  ├── param.json      # 分析工具参数配置文件

2. 分析工具参数配置文件 (param.json)

参数配置文件用于定义分析工具的参数，这些参数将被平台读取并显示在参数设置界面中，供用户在使用分析工具时调整：

参数类型说明

参数类型	说明	界面表现	使用场景
file_paths	多文件/文件夹选择	提供"Select Files"和"Select Directory"按钮	选择多个实验结果文件或结果目录
string	字符串输入	文本输入框，支持默认值	算法名称、参数值等
file_path	单文件选择	文件选择对话框	选择单个结果文件或指定输出路径

参数配置示例

{
    "input": [
        {
            "name": "input_paths",
            "type": "file_paths"
        },
        {
            "name": "your_algorithm",
            "type": "string"
        },
        {
            "name": "n",
            "type": "string",
            "default": "5,10"
        },
        {
            "name": "tau",
            "type": "string",
            "default": "10,20"
        }
    ],
    "output": [
        {
            "name": "output_path",
            "type": "file_path"
        }
    ]
}

NOTE

• 配置文件中的参数将在分析执行时传递给分析代码
• default 字段为可选，用于设置参数的默认值

3. 分析工具实现 (main.py)

分析工具的主实现文件需要包含一个名为 run 的函数，该函数将被平台调用来执行分析。函数应该接受一个参数：

• config: 从 param.json 读取的配置字典，包含输入输出路径和其他参数

NOTE

框架工作原理说明

• 平台会自动读取 param.json 中定义的参数，并将用户在界面中设置的值传递给 run 函数的 config 参数
• 对于 file_paths 类型的参数，框架会自动遍历用户选择的文件夹，找出所有结果文件并存储在一个列表中
• 因此 config["input_paths"] 获取到的是具体的文件路径列表，而不是文件夹路径
• config 字典的键名对应 param.json 中 input 和 output 数组里每个参数的 name 字段

基础模板

def run(config):
    """
    执行分析的主函数
    
    参数:
        config (dict): 从param.json读取的配置字典
                      包含: input_paths, output_path, your_algorithm等
    """
    # 获取配置参数 (对应param.json中的参数name字段)
    input_paths = config["input_paths"]        # 对应param.json中name为"input_paths"的file_paths类型参数
    output_path = config["output_path"]        # 对应param.json中name为"output_path"的file_path类型参数  
    your_algorithm = config.get("your_algorithm", "")  # 对应param.json中name为"your_algorithm"的string类型参数
    n = config.get("n", "5,10")              # 对应param.json中name为"n"的string类型参数，默认值"5,10"
    tau = config.get("tau", "10,20")         # 对应param.json中name为"tau"的string类型参数，默认值"10,20"
    
    # 注意：input_paths是一个文件路径列表，框架已经帮您找出了所有结果文件
    print(f"待分析的文件数量: {len(input_paths)}")
    
    # 初始化结果存储结构
    results = {}
    
    # 处理输入文件
    for result in load_result_from_files(input_paths):
        # 提取实验信息
        settings = result.get('settings', {})
        algorithm_name, problem_name = extract_basic_info(settings)
        
        # 计算指标值
        metric_value = calculate_metric(result['runtime_populations'])
        
        # 存储结果
        store_result(results, algorithm_name, problem_name, metric_value)
    
    # 生成分析报告
    output_file = generate_analysis_report(results, output_path)
    
    print(f"Analysis completed. Results saved to: {output_file}")

代码解释

第9-14行：参数读取部分

• 从 config 字典中获取 param.json 定义的各项参数
• 每个参数的键名对应配置文件中的 name 字段
• 使用 config.get() 方法可以设置默认值，避免参数缺失时报错

第21-22行：文件加载部分

• load_result_from_files(input_paths) 是框架提供的文件加载函数
• 该函数会遍历 input_paths 列表中的所有文件路径
• 每次迭代返回一个包含实验结果数据的字典，通常包含 settings 和 runtime_populations 等字段

TIP

实验结果数据字典的详细结构说明请参见：information 数据结构说明

第23-30行：数据处理过程

• 从每个结果文件中提取实验设置信息（算法名、问题名等）
• 基于 runtime_populations 数据计算性能指标
• 将计算结果存储到结果数据结构中
• 这个过程会对所有输入文件重复执行，收集完整的分析数据

第32-35行：结果输出部分

• generate_analysis_report() 函数负责将收集到的分析数据生成最终报告
• 报告通常保存为Excel、HTML、PDF等格式，便于用户查看和分享
• 函数返回生成的报告文件路径，平台会据此为用户提供下载链接
• 最后输出分析完成的提示信息，包含保存路径

4. 快速开始模板

按照以下步骤，您可以快速创建自己的分析工具：

步骤1：创建目录和文件

在 results_output/ 目录下创建您的分析工具目录：

results_output/你的分析工具名称/
  ├── main.py
  ├── param.json

步骤2：配置参数文件 (param.json)

复制以下模板并根据需要修改：

{
    "input": [
        {
            "name": "input_paths",
            "type": "file_paths"
        },
        {
            "name": "target_algorithm",
            "type": "string",
            "default": ""
        },
        {
            "name": "metric_type",
            "type": "string",
            "default": "MIGD"
        }
    ],
    "output": [
        {
            "name": "output_path",
            "type": "file_path"
        }
    ]
}

步骤3：实现分析逻辑 (main.py)

复制以下模板并填写TODO部分：

import numpy as np
import pandas as pd
from utils.file_utils import load_result_from_files
from utils.metrics import calculate_MIGD, calculate_MHV  # 根据需要导入指标函数


def run(config):
    """
    分析工具主函数
    """
    # 1. 读取配置参数
    input_paths = config["input_paths"]
    output_path = config["output_path"]
    target_algorithm = config.get("target_algorithm", "")
    metric_type = config.get("metric_type", "MIGD")
    
    print(f"开始分析 {len(input_paths)} 个文件...")
    
    # 2. 初始化结果存储
    results = {}
    
    # 3. 处理每个结果文件
    for result in load_result_from_files(input_paths):
        # 3.1 提取基本信息
        settings = result.get('settings', {})
        algorithm_name = settings.get('search_algorithm_class', 'Unknown')
        problem_name = settings.get('problem_class', 'Unknown')
        
        # 3.2 过滤条件（可选）
        # TODO: 根据需要添加过滤逻辑，例如：
        # if target_algorithm and target_algorithm not in algorithm_name:
        #     continue
            
        # 3.3 计算指标
        runtime_populations = result.get('runtime_populations', {})
        
        # TODO: 在这里实现您的指标计算逻辑
        # 示例：
        # if metric_type == "MIGD":
        #     metric_value = calculate_MIGD(runtime_populations)
        # elif metric_type == "MHV":
        #     metric_value = calculate_MHV(runtime_populations)
        # else:
        #     metric_value = 您的自定义指标计算
        
        # 3.4 存储结果
        # TODO: 将计算结果存储到results字典中
        # 建议格式：key = f"{algorithm_name}_{problem_name}"
    
    # 4. 生成报告
    # TODO: 处理收集到的results数据，生成分析报告
    # 建议：
    # - 计算统计量（均值、标准差、最值等）
    # - 保存为Excel、CSV或其他格式
    # - 返回输出文件路径
    
    print(f"分析完成！结果保存至: {output_path}")
    return output_path

步骤4：自定义修改

根据您的需求修改以下部分：

1. 参数配置：在 param.json 中添加或修改参数
2. 指标计算：在 main.py 的TODO部分实现您的指标计算逻辑
3. 结果格式：修改报告生成的数据结构和输出格式
4. 辅助函数：添加您需要的辅助函数

步骤5：测试

完成实现后，在平台的实验模块中选择您的分析工具进行测试。

TIP

• 复制模板后，请修改标记 TODO 的部分
• 参数名称要与 param.json 中的 name 字段保持一致
• 建议先用简单的测试数据验证功能

WARNING

• 文件路径要使用正斜杠 / 或使用 os.path.join()
• 处理大量文件时注意内存使用
• 添加适当的错误处理确保程序稳定性