ndx-pose NWB扩展

ndx-pose是在NWB中存储姿态估计数据的标准化格式，例如来自DeepLabCut和SLEAP的数据。请提交问题或PR以建议或添加对其他姿态估计工具的支持。

此扩展包含几个新的神经数据类型

• Skeleton，存储身体部分（节点和边）之间的关系。
• Skeletons，是一个容器，用于存储多个Skeleton对象。
• PoseEstimationSeries，存储身体部分随时间估计的位置（x，y）或（x，y，z），以及估计位置的置信度/似然性。
• PoseEstimation，存储多个身体部分的估计位置数据（PoseEstimationSeries），这些数据由相同视频（工具/算法）计算得出。
• SkeletonInstance，它存储单个帧中身体部分的估计位置和可见性。
• TrainingFrame，它存储单个帧的地面实况数据。它包含SkeletonInstance对象，并引用源视频的一帧（ImageSeries）。源视频可以存储为内部数据数组，或作为通过相对文件路径引用的文件。
• TrainingFrames，它是一个容器，存储多个TrainingFrame对象。
• SourceVideos，它是一个容器，存储表示用于训练的源视频的多个ImageSeries对象。
• PoseTraining，它是一个容器，存储用于训练姿态估计模型的地面实况数据（TrainingFrames）和源视频（SourceVideos）。

建议将Skeletons、PoseEstimation和PoseTraining对象放置在名为"behavior"的NWB处理模块中，如下所示。

安装

pip install ndx-pose

使用示例

1. 示例：将姿态估计（关键点）写入NWB文件.

2. 示例：将训练数据写入NWB文件.

处理多个受试者的姿态估计

NWB文件设计用于存储单个受试者的数据，并且只有一个根级别的Subject对象。因此，ndx-pose被设计用于存储单个受试者的姿态估计。来自不同受试者的姿态估计数据应存储在不同的NWB文件中。

然而，训练图像可以涉及多个骨骼。这些训练图像可能在不同受试者之间相同，因此在NWB文件之间也相同。这些训练图像应在文件之间复制，直到NWB和ndx-pose添加多受试者支持。请参阅https://github.com/rly/ndx-pose/pull/3

资源

将DLC输出转换为NWB/从NWB转换的实用工具：https://github.com/DeepLabCut/DLC2NWB

• 对于多动物项目，每个动物创建一个NWB文件。该NWB文件仅包含/processing/behavior下的PoseEstimation对象。该PoseEstimation对象包含PoseEstimationSeries对象，每个身体部分一个，以及关于姿态估计过程、骨骼和视频的一般元数据。PoseEstimationSeries对象包含特定动物该身体部分的估计位置。

将SLEAP姿态跟踪数据转换为NWB/从NWB转换的实用工具：https://github.com/talmolab/sleap-io

• 由SLEAP（sleap.io.dataset.Labels.export_nwb）使用
• 另请参阅https://github.com/talmolab/sleap/blob/develop/sleap/io/format/ndx_pose.py

关键点MoSeq：https://github.com/dattalab/keypoint-moseq

• 支持从NWB文件读取PoseEstimation对象。

NeuroConv：https://neuroconv.readthedocs.io/en/main/conversion_examples_gallery/conversion_example_gallery.html#behavior

• NeuroConv支持将数据从DeepLabCut（使用上面描述的dlc2nwb）、SLEAP（使用上面描述的sleap_io）、FicTrac和LightningPose转换为NWB。它支持将姿态估计数据追加到现有NWB文件中。

Ethome：用于动物行为机器学习的工具：https://github.com/benlansdell/ethome

• 支持从NWB文件读取PoseEstimation对象。

相关工作

• https://github.com/ndx-complex-behavior
• https://github.com/datajoint/element-deeplabcut

几个NWB数据集使用ndx-pose 0.1.1

• 关于小鼠物体识别的详细行为、视频和神经数据集
• IBL大脑广泛图

GitHub上也有几个开源转换脚本也使用ndx-pose。

非训练相关类型的图

%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#ffffff', "primaryBorderColor': '#144E73', 'lineColor': '#D96F32'}}}%%

classDiagram
    direction LR
    namespace ndx-pose {
        class PoseEstimationSeries{
            <<SpatialSeries>>
            name : str
            description : str
            timestamps : array[float; dims [frame]]
            data : array[float; dims [frame, [x, y]] or [frame, [x, y, z]]]
            confidence : array[float; dims [frame]]
            reference_frame: str
        }

        class PoseEstimation {
            <<NWBDataInterface>>
            name : str
            description : str, optional
            original_videos : array[str; dims [file]], optional
            labeled_videos : array[str; dims [file]], optional
            dimensions : array[uint, dims [file, [width, height]]], optional
            scorer : str, optional
            scorer_software : str, optional
            scorer_software__version : str, optional
            PoseEstimationSeries
            Skeleton, link
            Device, link
        }

        class Skeleton {
            <<NWBDataInterface>>
            name : str
            nodes : array[str; dims [body part]]
            edges : array[uint; dims [edge, [node, node]]]
        }

    }

    class Device

    PoseEstimation --o PoseEstimationSeries : contains 0 or more
    PoseEstimation --> Skeleton : links to
    PoseEstimation --> Device : links to

所有类型的图

%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#ffffff', "primaryBorderColor': '#144E73', 'lineColor': '#D96F32'}}}%%

classDiagram
    direction LR
    namespace ndx-pose {
        class PoseEstimationSeries{
            <<SpatialSeries>>
            name : str
            description : str
            timestamps : array[float; dims [frame]]
            data : array[float; dims [frame, [x, y]] or [frame, [x, y, z]]]
            confidence : array[float; dims [frame]]
            reference_frame: str
        }

        class PoseEstimation {
            <<NWBDataInterface>>
            name : str
            description : str, optional
            original_videos : array[str; dims [file]], optional
            labeled_videos : array[str; dims [file]], optional
            dimensions : array[uint, dims [file, [width, height]]], optional
            scorer : str, optional
            scorer_software : str, optional
            scorer_software__version : str, optional
            PoseEstimationSeries
            Skeleton, link
            Device, link
        }

        class Skeleton {
            <<NWBDataInterface>>
            name : str
            nodes : array[str; dims [body part]]
            edges : array[uint; dims [edge, [node, node]]]
        }

        class TrainingFrame {
            <<NWBDataInterface>>
            name : str
            annotator : str, optional
            source_video_frame_index : uint, optional
            skeleton_instances : SkeletonInstances
            source_video : ImageSeries, link, optional
            source_frame : Image, link, optional
        }

        class SkeletonInstance {
            <<NWBDataInterface>>
            id: uint, optional
            node_locations : array[float; dims [body part, [x, y]] or [body part, [x, y, z]]]
            node_visibility : array[bool; dims [body part]], optional
            Skeleton, link
        }

        class TrainingFrames {
            <<NWBDataInterface>>
            TrainingFrame
        }

        class SkeletonInstances {
            <<NWBDataInterface>>
            SkeletonInstance
        }

        class SourceVideos {
            <<NWBDataInterface>>
            ImageSeries
        }

        class Skeletons {
            <<NWBDataInterface>>
            Skeleton
        }

        class PoseTraining {
            <<NWBDataInterface>>>
            training_frames : TrainingFrames, optional
            source_videos : SourceVideos, optional
        }

    }

    class Device
    class ImageSeries
    class Image

    PoseEstimation --o PoseEstimationSeries : contains 0 or more
    PoseEstimation --> Skeleton : links to
    PoseEstimation --> Device : links to

    PoseTraining --o TrainingFrames : contains
    PoseTraining --o SourceVideos : contains

    TrainingFrames --o TrainingFrame : contains 0 or more

    TrainingFrame --o SkeletonInstances : contains
    TrainingFrame --> ImageSeries : links to
    TrainingFrame --> Image : links to

    SkeletonInstances --o SkeletonInstance : contains 0 or more
    SkeletonInstance --o Skeleton : links to

    SourceVideos --o ImageSeries : contains 0 or more

    Skeletons --o Skeleton : contains 0 or more

贡献者

• @rly
• @bendichter
• @AlexEMG
• @roomrys
• @CBroz1
• @h-mayorquin
• @talmo
• @eberrigan

此扩展是用ndx-template创建的。