Label Studio 时间序列标注模板：从 TimeSeries 标签配置、多格式数据导入到结果导出

Label Studio 时间序列标注模板从 TimeSeries 标签配置、多格式数据导入到结果导出【免费下载链接】label-studioLabel Studio is a multi-type data labeling and annotation tool with standardized output format项目地址: https://gitcode.com/GitHub_Trending/la/label-studio时间序列标注是传感器数据分析、异常检测、行为识别等 ML 任务的关键前置环节。本文以 Label Studio 官方通用时间序列标注模板 time_series.md 为核心系统讲解TimeSeries/TimeSeriesLabels/Channel标签的完整配置、CSV / TSV / JSON 三种输入格式的导入方式、标注结果的 JSON 结构并深入到前端编辑器源码与仓库内置模板帮助读者从零搭建可用的时间序列标注项目并理解其底层运行机制。模板定位一套适用于任意时间序列数据的通用标注方案官方模板页time_series.md开篇即点明其定位Label any type of time series data using this generic template即通过一套通用配置覆盖多变量multivariate与简单时间序列的标注需求。模板的核心交互是标注员在时间序列图上拖拽选择一段时间范围并为其打上预设标签如Run/Walk从而生成带时间起止的区间标注结果。在 Label Studio 开源仓库中这一模板并非孤立存在label_studio/annotation_templates/time-series-analysis/目录下内置了 5 个可直接使用的相关模板time-series-forecasting/config.xml时间序列预测outliers-anomaly-detection/config.xml离群点与异常检测activity-recognition/config.xml活动识别change-point-detection/config.xml变化点检测signal-quality/config.xml信号质量评估这些模板都是在通用TimeSeriesTimeSeriesLabels基础上组合Choices等标签扩展而来的本文将从最基础的通用配置讲起。基础标注配置多变量时间序列示例官方模板给出的最简项目配置如下来自 time_series.mdView TimeSeriesLabels namelabel toNamets Label valueRun/ Label valueWalk/ /TimeSeriesLabels TimeSeries namets valueTypeurl value$csv_url timeColumntime Channel columnsensorone / Channel columnsensortwo / /TimeSeries /View这份配置只有三层结构却完成了时间序列标注的全部要素View所有标注配置必须包裹在 View 标签中它是整个标注界面labeling config的根容器。TimeSeriesLabels控制标签control tag负责画区域 打标签。它的toNamets通过名称关联到下方的TimeSeries对象标签。TimeSeries对象标签object tag负责展示数据。valueTypeurl表示数据源是任务 JSON 中某字段指向的 CSV 文件 URLvalue$csv_url指明该字段名timeColumntime指定 CSV 中用作 X 轴时间轴的列内部的Channel columnsensorone /声明要绘制的数据通道列。对应这份配置的输入 CSV 长这样time,sensorone,sensortwo 0,10,20 1,20,30 2,30,40任务数据则形如[ { data: { csv_url: http://example.com/path/to/file.csv } } ]。关于导入细节可参考 How to import your data。组件关联关系TimeSeriesLabels与TimeSeries之间通过toName/name参数建立关联TimeSeriesLabels的toName必须等于某个TimeSeries的name。从源码看这一关联在前端编辑器中被严格管理TimeSeries.jsx中的states()视图方法通过self.annotation.toNames.get(self.name)反向查找到作用于自己的控制标签集合activeStates()再从中筛选出当前选中且类型为TimeSeriesLabelsModel的状态见 TimeSeries.jsx。这正是拖拽区域后自动套用当前选中标签机制的实现基础。TimeSeriesLabels区间标签控制标签TimeSeriesLabels 用于在时间序列图上创建带标签的时间范围labeled time range。其完整参数表如下定义于 includes/tags/timeserieslabels.md参数类型默认值说明namestring元素名称toNamestring要标注的时间序列对象名称choicesingle | multiplesingle配置每次可选择一个还是多个标签maxUsagesnumber每个标签在单个任务中的最大使用次数showInlinebooleantrue标签是否在同一视觉行内展示opacityfloat0.9标注区域的透明度fillColorstringtransparent区域填充色十六进制或 HTML 颜色名strokeColorstring#f48a42描边颜色十六进制strokeWidthnumber1描边宽度基础用法示例TimeSeriesLabels namelabel toNamets Label valueRun/ Label valueWalk/ /TimeSeriesLabelsLabel valueRun/定义了一个名为Run的标签值。实际项目中还可以为每个Label单独设置background颜色例如 timeseries.md 中的示例Label valueRun background#5b5/。一个标签多个值choice 与 perRegion当需要先框选区域、再为区域补充子分类时可以组合使用Choices标签。仓库内置的 outliers-anomaly-detection/config.xml 演示了这一模式TimeSeriesLabels namelabel toNamets Label valueRegion backgroundred / /TimeSeriesLabels Choices nameregion_type toNamets perRegiontrue requiredtrue Choice valueOutlier/ Choice valueAnomaly/ /ChoicesperRegiontrue使得每次框选区域后都会弹出Choices为同一区域附加Outlier/Anomaly分类实现两级标注。TimeSeries时间序列对象标签TimeSeries 负责加载并可视化时间序列数据。它的完整参数表如下定义于 includes/tags/timeseries.md参数类型默认值说明namestring元素名称valuestring数据查找键valueTypeurl 时为 CSV/TSV/JSON 文件 URL否则直接放 JSON 数据valueTypeurl | jsonurl时间序列数据的格式syncstring要同步的对象名称如视频/音频标签cursorColorstring同步时播放游标的颜色hex 或任意 SVG 兼容颜色字符串timeColumnstring提供时间值的列名或列索引若数据没有时间列则自动生成timeFormatstring解析 timeColumn 内值的格式模式由 d3 提供遵循 strftime 实现timeDisplayFormatstring时间值的显示格式日期用 strftime数值用 d3 number 格式durationDisplayFormatstring刷选范围时间跨度的显示格式同样区分日期/数值sepstring,CSV 文件的分隔符overviewChannelsstring显示在概览overview中的通道名或索引逗号分隔overviewWidthstring25%概览窗口默认宽度百分比fixedScalebooleanfalseY 轴是否按数据最大值固定缩放为 false 时当前视图只按可见数据缩放valueTypeurl是官方模板的默认用法——Label Studio 期望任务 JSON 中提供指向 CSV 文件的链接timeColumn指定数据集中用作 X 轴时间线的列。如果不指定timeColumnLabel Studio 会自动生成递增整数序列0, 1, 2, ...作为 X 轴这一行为在源码中有明确实现TimeSeries.jsx的dataObj视图中当self.timecolumn为空时会依据第一列数据长度构造索引数组并写入内部时间键见 TimeSeries.jsx。Channel声明数据通道Channel是TimeSeries的子标签每个Channel对应一个要绘制的数据列。其参数表如下定义于 includes/tags/channel.md参数类型默认值说明columnstring列名或列索引legendstring通道的显示名称unitsstring显示的物理单位名称displayFormatstring数值格式化字符串基于 d3-format如,千分位、.2f小数精度、%百分比heightnumber200曲线图高度strokeColorstring#f48a42曲线描边颜色hexstrokeWidthnumber1曲线描边宽度markerColorstring#f48a42标记点颜色hexmarkerSizenumber0标记点大小markerSymbolnumbercircle标记点形状timeRangestringX 轴时间轴的数据范围dataRangestringY 轴数值轴的数据范围showAxisstring显示或隐藏坐标轴fixedScaleboolean是否固定缩放若给定则覆盖 TimeSeries 上的 fixedScaleMultiChannel多通道分组展示当多个通道需要绘制在同一坐标系中对比时可以用MultiChannel子标签对Channel分组详见 timeseries.md 与 TimeSeries/README.mdView TimeSeries namets value$timeseries valueTypeurl timeColumntime timeFormat%Y-%m-%d %H:%M:%S.%f MultiChannel Channel columnvelocity / Channel columnacceleration / /MultiChannel /TimeSeries TimeSeriesLabels namelabel toNamets Label valueRun backgroundred/ Label valueWalk backgroundgreen/ /TimeSeriesLabels /View从源码结构看MultiChannel模型MultiChannel.jsx支持通道图例Channel Legend的可见性切换与悬停高亮并统一通过TimeSeriesVisualizer组件渲染解决了单通道与多通道渲染逻辑重复的问题。输入数据格式详解CSV、TSV 与 JSON官方模板明确声明 Label Studio 支持以下时间序列输入类型带表头或不带表头的 CSV带表头或不带表头的 TSVJSONCSV 示例以 3 列的 CSV 为例time,sensorone,sensortwo 0.0,3.86,0.00 0.1,2.05,2.11 0.2,1.64,5.85随后创建一个引用 CSV 文件 URL 的 JSON 任务文件[ { data: { csv_url: http://example.com/path/to/file.csv } } ]由于 JSON 中引用的是 URL且 URL 存放在名为csv_url的字段中配置如下TimeSeries namets valueTypeurl value$csv_url sep, timeColumntime Channel columnsensorone / /TimeSeries这里valueTypeurl告诉 Label Studio 通过 URL 加载数据。若要支持跨域加载或私有存储桶可配置 Label Studio 的存储代理能力详见 storage_local.md 等存储相关文档。TSV 示例上传制表符分隔文件时通过sep属性指定分隔符TimeSeries namets valueTypeurl value$csv_url sep\t timeColumntime Channel column0/ /TimeSeriessep默认值为,逗号。在源码的preloadValue中分隔符还支持别名映射tab/\t→ 制表符、space→ 空格、comma→ 逗号、dot→ 点号、auto→ 自动探测见 TimeSeries.jsx。无表头 CSV 与 TSV无表头文件的核心差异在于Channel列名的引用方式既然没有表头、列名未知就改用列索引。例如把第一列作为时间列可写TimeSeries timeColumn0 ... Channel的column属性同理也支持索引如Channel column1 /。这也是官方模板多序列示例中大量使用timeColumn0、column1的原因。JSON 格式Label Studio 中所有任务都以 JSON 存储JSON 是其原生格式。valueTypeurl场景使用该模式导入 CSV 文件后Label Studio 会自动生成形如以下结构的 JSON 任务{ csv: http://localhost:8080/data/upload/my-import-file.csv }valueTypejson场景也可以直接构造 JSON 导入每个键分别对应时间列与各通道{ ts: { time: [ 15.97, 15.85, 25.94 ], sensorone: [ 13.86, 29.05, 64.90 ], sensortwo: [ 21.00, 15.18, 35.85 ] } }此时配置中value$ts、valueTypejson即可源码preloadValue中当valuetype ! url时会直接从任务数据对象中按value键取值见 TimeSeries.jsx。注意官方模板示例中此 JSON 的时间值均为数值若时间列是日期字符串则必须在配置中指定timeFormat例如timeFormat%m/%d/%Y %H:%M:%S否则解析会失败。标注结果输出格式标注完成后每个标注annotation都以 JSON 表示其中result字段形如下例来自 time_series.md{ annotations: [{ result: [ { value: { start: 1592250751951.8074, end: 1592251071946.638, instant: false, timeserieslabels: [ Run ] }, id: S1DkU7FSku, from_name: label, to_name: ts, type: timeserieslabels }, { value: { start: 1592251231975.601, end: 1592251461993.5276, instant: false, timeserieslabels: [ Run ] }, id: XvagJo87mr, from_name: label, to_name: ts, type: timeserieslabels } ] }] }每个区间结果的关键字段value.start/value.end标注区间的起止时间点。数值型时间列时为原始数值如 Unix 毫秒时间戳日期型时间列时则为符合timeFormat的字符串仓库内置模板中即为2020-01-05 00:00:00.000000形式。value.instant是否为瞬时点标注start end时为true。源码addRegion中正是以{ start, end, instant: start end }创建结果见 TimeSeries.jsx。value.timeserieslabels标注的时间序列标签数组多选时包含多个标签。from_name/to_name分别对应配置中的TimeSeriesLabels.name与TimeSeries.name。type固定为timeserieslabels。这一结果格式可以直接用于训练时序模型或通过 Label Studio 的 导出功能 转为 COCO、CSV 等目标格式。进阶单项目标注多条时间序列若一个任务需要同时标注两条或多条时间序列必须先把 CSV 文件以 URL 形式提供再导入引用这些 URL 的 JSON 任务文件。例如任务引用两组时间序列数据[ { data: { csv_file1: http://example.com/path/file1.csv, csv_file2: http://example.com/path/file2.csv } } ]对应的标注配置在同一界面上分别引用两个 CSVView Header valueFirst time series / TimeSeriesLabels namelbl-1 toNamets-1 Label valueLabel 1 / /TimeSeriesLabels TimeSeries namets-1 timeColumn0 value$csv_file1 Channel column1 / /TimeSeries Header valueSecond time series / TimeSeriesLabels namelbl-2 toNamets-2 Label valueLabel 2 / /TimeSeriesLabels TimeSeries namets-2 timeColumn0 value$csv_file2 Channel column1 / /TimeSeries /View关键点TimeSeries标签的value参数用于引用任务 JSON 中存放 CSV URL 的键名$csv_file1、$csv_file2。这里使用了无表头索引写法timeColumn0、column1也可替换为具名列名。源码实现时间列校验与解析细节深入 TimeSeries.jsx 可以看到该组件对时间数据有一套严格的校验逻辑这对排查标注界面不渲染/报错问题很有帮助时间轴必须递增文档明确要求数据的时间轴必须是排好序的sorted否则TimeSeries无法工作。源码在dataObj中逐点校验current previous一旦发现时间回退就抛出timeColumnmust be incremental and sequentially ordered错误TimeSeries.jsx。数值时间列无需 timeFormat解析函数parseTimeFn在未指定timeFormat时退化为NumberTimeSeries.jsx若timeColumn首列是非数值且未配timeFormat会提示必须使用timeFormat解析日期时间。%f 微秒的兼容处理D3 的 strftime 不支持%f微秒源码检测到timeFormat含%f时会发出警告并把%f替换为%L毫秒同时对数据做 3 位毫秒补齐TimeSeries.jsx。官方模板中出现的timeFormat%Y-%m-%d %H:%M:%S.%f即依赖这一兼容逻辑。前端对该组件的测试覆盖在 TimeSeries.test.js其中验证了初始刷选范围brush range的计算当数据点少于 10 个时展示全量范围否则按overviewWidth默认 25%计算初始可见窗口必要时向右扩展保证至少 10 个点可见对应calculateInitialBrushRange/expandRangeToMinimumPoints见 TimeSeries.jsx。仓库内置模板速览与自定义建议label_studio/annotation_templates/time-series-analysis/下 5 个模板可直接用于创建项目其中较有代表性的两个time-series-forecasting/config.xml预测场景将TimeSeries与Choices组合框选可预测区域后对趋势做 Up / Down / Steady 三分类同时演示了timeFormat、timeDisplayFormat、overviewChannels、displayFormat、legend等参数的综合用法TimeSeries namestock valueTypeurl value$csv sep, timeColumntime timeFormat%Y-%m-%d %H:%M:%S.%f timeDisplayFormat%Y-%m-%d overviewChannelsvalue Channel columnvalue displayFormat,.1f strokeColor#1f77b4 legendStock Value/ /TimeSeriesoutliers-anomaly-detection/config.xml异常检测场景perRegiontrue的Choices支持对每个标注区域追加Outlier/Anomaly分类输出结果中每个区域会同时生成timeserieslabels与choices两条 result。自定义扩展时可以从以下几个方面入手详见 TimeSeries/README.md 的开发者指南新属性在TagAttrsTimeSeries.jsx中按 MSTtypes.optional模式扩展再在视图方法中读取。大数据量性能sparseValues()辅助函数会对超大数据集做抽稀阈值受缩放步长控制。播放同步sync参数可将时间序列与视频/音频标签同步事件总线由SyncableMixin提供支持play/pause/seek/speed事件并在 100ms 同步窗口内防止事件循环TimeSeries/README.md。小结从一份 8 行的通用配置出发TimeSeriesTimeSeriesLabelsChannel三件套即可支撑绝大多数时间序列标注需求多变量曲线展示、时间区间框选、多标签分类、异常点瞬时标注、多序列同屏标注以及 CSV / TSV / JSON 三种数据接入方式。本文同时给出了前端编辑器 TimeSeries.jsx 的源码级佐证与 time-series-analysis 目录下的可直接复用模板读者可以以此为起点按自己的业务字段组合标签快速构建生产可用的时间序列标注流水线。【免费下载链接】label-studioLabel Studio is a multi-type data labeling and annotation tool with standardized output format项目地址: https://gitcode.com/GitHub_Trending/la/label-studio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考