# 钙分析工具包 **Repository Path**: ShanghaiTech-GuanLab/Calcium-analysis-kit ## Basic Information - **Project Name**: 钙分析工具包 - **Description**: 钙信号分析作图 - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2021-09-14 - **Last Updated**: 2022-06-07 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README 钙数据分析作图工具包。所有函数位于CaAnalyze包下，使用前需导入。分为数据收集CollectData、数据转码Transcode和作图DrawFigure，3个子包。依赖[埃博拉酱的MATLAB扩展](https://ww2.mathworks.cn/matlabcentral/fileexchange/96344-matlab-extension)和[数据格式规范](https://gitee.com/ShanghaiTech-GuanLab/Data-format-specification) # 目录 [CollectData](#CollectData) - [CaDF20_CaDM20](#CaDF20_CaDM20) 读入CaDF2.0文件，存储为CaDM2.0内存格式 - [MetaTags_METags](#MetaTags_METags) 将多个MetaTags文件读入为METags内存格式（已过时） - [Rdc2_CaDM20](#Rdc2_CaDM20) [Transcode](#Transcode) - [PositiveCellCluster](#PositiveCellCluster) 找出哪些细胞在哪些模块下为阳性 - [PositiveCellMask](#PositiveCellMask) 取出阳性细胞逻辑向量（刘开元算法） - [SortBeforeOH](#SortBeforeOH) 在做总览热图OverallHeatmap之前对细胞进行分群排序。 [DrawFigure](#DrawFigure) - [ColorfulDotLines](#ColorfulDotLines) 具有彩色标记点的多线图 - [ElasticChart](#ElasticChart) 弹簧图，反映点之间的距离关系。 - [LMHColorMap](#LMHColorMap) 生成低、中、高三阶段分布的Colormap - [OverallHeatmap](#OverallHeatmap) 显示每个细胞不同天的全Trial平均Trace - [TrialwiseTrace](#TrialwiseTrace) 作单Trial追踪图，图上有多条相互断开的折线在X轴上排布，每条线可具有误差阴影和刺激范围 [包外工具函数](#包外工具函数) - [SplitOneSingleDimensionByAnother](#SplitOneSingleDimensionByAnother) 将数组某一维度的数据按照分组标记拆分到另一个单一维度中，使得那个单一维度扩张，多出来的空位用指定值补全。 # CollectData 该包负责将数据文件读入内存，整理成便于引用计算分析的格式。 ## CaDF20_CaDM20 读入CaDF2.0文件，存储为CaDM2.0内存格式 ### 必需参数 CaDF20(:,1)string，[CaDF2.0文件](https://gitee.com/ShanghaiTech-GuanLab/Data-format-specification/blob/master/+FormatSpecification/Specifications/CaDF2.0.json)路径 ### 名称值参数 BehM10(:,3)table，[BehM1.0表](https://gitee.com/ShanghaiTech-GuanLab/Data-format-specification/blob/master/+FormatSpecification/Specifications/BehM1.0.json)，用于将多模块会话拆解为实际的模块 BaseLength(1,1)uint8，如果需要算ΔF/F₀，输入前缀基线采样时点数。如不指定则不算。 SplitMap(1,1)struct，拆分映射。结构体的每个字段是要拆分的会话名，字段值是字符串向量，列出要拆分到的回合类型 ### 返回值 [CaDM2.0](https://gitee.com/ShanghaiTech-GuanLab/Data-format-specification/blob/master/+FormatSpecification/Specifications/CaDM2.0.json)各字段 ## MetaTags_METags 将多个MetaTags文件读入为METags内存格式。本函数已过时，将在未来版本中删除。 ### 输入参数 MTPaths(:,1)string，可选，MetaTags文件路径。默认打开文件对话框要求用户手动选择。 SizeT(1,1)uint16=65535，名称-值，每个文件要截取的时间帧数，应当短于所有文件中的时间帧数，否则会出错。如果设为65535，则取所有时间帧。 TagThreshold(1,1)uint16=550，名称-值，将Tag值逻辑化时的阈值 ### 返回值 返回[MECgRawsTags格式](#MECgRawsTags格式)规范中的Mice Experiments METags三个字段。 ### MetaTags文件格式 MetaTags文件的标准文件名格式是： ``` <鼠名>.<日期时间>.<实验名>.<光电参数>.[_].MetaTags.mat ``` 包含两个字段： MetaData(1,1)struct - ScannerType(1,1)string，扫描器类型，可以是"Resonant"或"Galvano" - DeviceNames(:,1)string，采集设备名，如"RNDD4G"、"CD1"等。每行对应一个图像通道。 - Fps(1,1)double，采样帧率 - SizeX(1,1)double，图像宽度 - SizeY(1,1)double，图像高度 - SizeZ(1,1)double，图像深度 - SizeC(1,1)double，图像通道数 - SizeT(1,1)double，时间周期数 - DimensionOrder(1,1)string，维度顺序，通常是"XYCZT" - OmeXml(1,1)string，OME元数据XML - ChannelColors(:,4)table，包含Red, Green, Blue, Alpha四列，都是(1,1)uint8，每个通道一行，对应一个图像通道的颜色。 Tags(1,1)struct，每个字段是一个CD通道设备名，值是(:,1)double，每个元素为一帧的全像素平均值。 ## MTRM_Rdc3 将MECgRawsTags标准格式文件读入为Rdc3格式文件的某些字段。本函数已过时，将在未来版本中删除。 ```MATLAB %打开文件对话框选择文件MTRM文件，转换成Rdc3字段 [Filename,fps,Name,nrd_c,raw_data,raw_tag] = CollectData.MTRM_Rdc3 %分标阈值设为600，直接指定文件路径 MTPaths=OpenFileDialog(Filter="MetaTags文件|*.MetaTags.mat",Title="选择MetaTags文件",Multiselect=true); RMPaths=OpenFileDialog(Filter="Measurements文件|*.Measurements.mat",Title="选择Measurements文件",Multiselect=true); [Filename,fps,Name,nrd_c,raw_data,raw_tag] = CollectData.MTRM_Rdc3(600,MTPaths=MTPaths,RMPaths=RMPaths); ``` ### 可选位置参数 TagThreshold(1,1)uint16=550，分标阈值 ### 名称-值对组参数 #### MTPaths(:,1)string MetaTags文件路径（\*.MetaTags.mat）。默认打开一个文件选择对话框来取得该参数。 MetaTags文件的标准文件名格式是： ``` <鼠名>.<日期时间>.<实验名>.<光电参数>.[_].MetaTags.mat ``` #### RMPaths(:,1)string Measurements文件路径（*.Measurements.mat）。默认打开一个文件选择对话框来取得该参数。 Measurements文件的标准文件名格式是： ``` <鼠名>.<日期时间>.<实验名>.<光电参数>._.Registered.<细胞类群>.Measurements.mat ``` 对于本函数的一次调用，只能输入具有相同鼠名、实验名和细胞类群的文件。如果有多个不同，请分多次调用本函数。 ### 返回值 Filename(1,1)string，自动生成的rdc3文件名 还返回Rdc3文件格式的fps Name nrd_c raw_data raw_tag字段，详见[Rdc3格式](#Rdc3格式)。 ## Rdc2_CaDM20 读入Rdc2文件，存储为CaDM2.0内存格式 输入参数：Rdc2Paths(:,1)string，[Rdc2文件](https://gitee.com/ShanghaiTech-GuanLab/Data-format-specification/blob/master/+FormatSpecification/Specifications/Rdc2.json)路径 返回值：[CaDM2.0](https://gitee.com/ShanghaiTech-GuanLab/Data-format-specification/blob/master/+FormatSpecification/Specifications/CaDM2.0.json)各字段 # Transcode 本包包含数据转码函数，将CollectData收集到的数据转化为适合于DrawFigure作图的格式。 ## PositiveCellCluster 找出哪些细胞在哪些模块下为阳性 ```MATLAB import CaAnalyze.Transcode.PositiveCellCluster %本函数最后两个参数可选，语法示例： %使用第1个模块作为基线，允许细胞在多个类中阳性 PositiveCellCluster(Measurements,2.7); %使用指定的基线，允许细胞在多个类中阳性 PositiveCellCluster(Measurements,2.7,Baseline); %使用第1个模块作为基线，每个细胞只能属于单一类 PositiveCellCluster(Measurements,2.7,true); %使用指定的基线，每个细胞只能属于单一类 PositiveCellCluster(Measurements,2.7,Baseline,true); ``` ### 输入参数 Measurements(1,:)cell，每个元胞是一个模块；胞内是(:,:,:)数组，为测量值，第1维细胞，第2维时间，第3维回合 WCut(1,1)，响应概率要超过全细胞平均的几倍才算阳性？一般2层4.6，5层2.7 Baseline(:,:,:)=Measurements{1}，可选基线，默认第1个模块。 Unique(1,1)logical=false，是否要求每个细胞只能属于单一类。若true，将对多模块中阳性的细胞，额外根据响应概率与阈值概率的差、商进行择优取类 ### 返回值 PositiveTable(:,:)logical，指示每个细胞在每个模块下是否阳性的逻辑表。第1维细胞，第2维模块。 ## PositiveCellMask 取出阳性细胞逻辑向量（刘开元算法） ### 输入参数 Measurements(:,:,:)，测量值，第1维细胞，第2维时间，第3维回合 Baseline(:,:,:)，基线测量值，第1维细胞，第2维时间，第3维回合 WCut(1,1)，响应概率要超过全细胞平均的几倍才算阳性？一般2层4.6，5层2.7 ### 返回值 PCM(:,1)logical，指示每个细胞是否阳性 ## SortBeforeOH 在做总览热图OverallHeatmap之前对细胞进行分群排序。 排序支持两种方法，详见参数ByMaxGroup ### 输入参数 Data(:,:,:)，必需，第1维是泳道内不同的行，第2维是泳道内不同的列，第3维是不同的泳道 ByMaxGroup(1,1)logical=true，可选，是否采用最大组法。 - 若true，则将每个细胞按照它在哪个泳道中均值最大分群，从小到大排列，然后将各组按照泳道顺序堆叠 - 若false，则将计算每个细胞的相关系数，然后根据相关性矩阵进行排序 ### 返回值 Data(:,:,:)，维度同输入，但经过了聚类和排序。 # DrawFigure 该包负责作图，只接受最接近直接作图的处理后数据，不负责数据处理 ## ColorfulDotLines 具有彩色标记点的多线图 本图适合用于表示多个对象在2/3维空间内随时间游走的轨迹，通过对采样点设置连续变化的颜色来表现对象在特定时间点的位置，以及对同一时间点上不同对象位置进行比较。 ```MATLAB import CaAnalyze.DrawFigure.ColorfulDotLines %作二维多线图，每个转折点都用渐变的颜色标出 ColorfulDotLines(X,Y); %作三维多线图，每个转折点都用渐变的颜色标出 ColorfulDotLines(X,Y,Z); %设置其它可选属性，可与上述任意语法组合使用 ColorfulDotLines(___,Name=Value); %返回多线对象和一个散点对象，可与上述任意语法组合使用 [Lines,Scatter]=ColorfulDotLines(___); ``` ### 示例 ```MATLAB import CaAnalyze.DrawFigure.ColorfulDotLines load('doc\ColorfulDotLines数据.mat'); Lines=CaAnalyze.DrawFigure.ColorfulDotLines(Score(:,:,1),Score(:,:,2),Score(:,:,3),LineColors=LineColors,PointIndex=PointIndex,PointColors=PointColors); legend(Lines,LineLabels); CB=colorbar; CB.Label.String="Time from cue(s)"; ``` 生成的是3D图像，运行后可以在图窗中使用3D旋转查看 ![](doc/ColorfulDotLines图像.svg) ### 位置参数 X(:,:)，X坐标，第1维是线内的点，第2维是不同的线 Y(:,:)，Y坐标，第1维是线内的点，第2维是不同的线 Z(:,:)，Z坐标，第1维是线内的点，第2维是不同的线 ### 名称值参数 LineColors(:,3)，每条线的颜色，第1维对应不同的线，第2维对应RGB通道。如果颜色数少于线数，将循环使用；如果多于，则仅使用前几种颜色。 PointIndex，数值向量，每个点对应的时点。如果点过多可能会遮挡线的颜色，此时可以仅指定少数几个时点，其它时点对应的点将不会被呈现出来。 PointColors(:,3)，时点与颜色的对应关系，第1维对应不同的线，第2维对应RGB通道。点的颜色将随时间变化，此处提供的颜色越多，变化越均匀连续。 ### 返回值 Lines(:,1)matlab.graphics.chart.primitive.Line，每条线返回一个线条对象，可用于后续添加图例等。 Scatter(1,1)matlab.graphics.chart.primitive.Scatter，无论有多少个点，只返回一个散点对象。 ## ElasticChart 弹簧图，反映点之间的距离关系。 假设各点之间是弹簧，有一个自然长度，拉伸则变细但施加拉力，压缩则变粗但施加推力。已知各点之间的距离，连接上自然长度为这个距离的弹簧，就可以在二维平面上自动对抗平衡出弹簧系统图 ### 必需参数 DistanceMatrix(:,:)numeric，正方形距离矩阵，两两点间距离的精确值。无数据的请填入NaN PointNames(:,1)string，和矩阵边长相等的字符串向量，每个点的名称 Iteration(1,1)numeric，迭代次数。次数越多越精细准确，但耗时越长。 ### 可选参数 Positions(1,:)complex，每个点的初始位置，行向量，用复数表示 ### 名称-值对组参数 ScatterStyle(1,:)cell，散点样式，将传递给scatter，默认{[],'green'} TextStyle(1,:)cell，文字样式，将传递给text，默认{'Color','red','HorizontalAlignment','center','VerticalAlignment','middle'} PlotStyle(1,:)cell，线条样式，将传递给plot，默认{'blue'} ### 返回值 Positions(1,:)complex，弹簧系统平衡后的各点位置。 ## LMHColorMap 生成低、中、高三阶段分布的Colormap ### 必需位置参数 Lowest(1,3)double，最小值的RGB颜色，应在[0,1]之间 Middle(1,3)double，中间值的RGB颜色，应在[0,1]之间 Highest(1,3)double，最大值的RGB颜色，应在[0,1]之间 ### 可选位置参数 LowSteps(1,1)uint8=255，低段区分色阶数 HighSteps(1,1)uint8=255，高段区分色阶数 ### 返回值 Colormap(:,3)double，生成的颜色映射图 ## OverallHeatmap 显示每个细胞不同天的全Trial平均Trace ```MATLAB load("OverallHeatmapData.mat"); figure; FigureAspectRatio(3,2,"Amplify"); TL=tiledlayout("flow",TileSpacing='tight',Padding='tight'); Axes=SuperCell2Mat(DrawFigure.OverallHeatmap(TL,OHData,"Colormap",LMHColorMap([0 0 1],[1 1 1],[1 0 0]),"ImagescStyle",{"XData",[1 500]/30-2,[-1,1]})); arrayfun(@(Ax,T)title(Ax,T),Axes(1,:),["Blue-only" "Audio-only" "Water-only" "X-lick-water 1" "X-lick-water 2"]); arrayfun(@(Ax,L)ylabel(Ax,L),Axes(:,1),["Original 1";"Original 2";"Transfer 1";"Transfer 2"]); xlabel(TL,"Time(s) from stimulus"); ylabel(TL,"Cell ID"); CB=colorbar; CB.Layout.Tile="east"; CB.Label.String="ΔF/F_0"; CB.TickLabels=round(2.^str2double(CB.TickLabels)-1,1,"significant"); ``` ![](示例/OverallHeatmap.svg) ### 必需参数 TiledLayout(1,1)matlab.graphics.layout.TiledChartLayout，将要在其中作图的分块布局。 Data(:,:,:)，作图数据。第1维是不同的细胞，将作图为不同行；第2维是Trial内的时间轴，将作图到同一行；第3维是不同的天，将水平展开为不同的泳道 ### 重复参数 Flags(1,1)string，可以重复设置以下旗帜： - HideXAxis，隐藏X轴 - HideYAxis，隐藏Y轴 ### 名称-值对组参数 ImagescStyle(1,:)cell=cell(1,0)，本函数调用imagesc绘图，此处指定要传递给imagesc的其它参数。建议至少设置XData和YData参数，保证XY坐标尺度正确。 Colormap(:,3)double，颜色映射。如不指定，将由MATLAB自动设置。 SubTitles(1,:)string，每个泳道的小标题。如不指定，将不显示小标题。 ### 返回值 Axes(:,:)cell，每个元胞里是对应位置的图的坐标轴，可用于后期修饰 ## TrialwiseTrace 作单Trial追踪图，图上有多条相互断开的折线在X轴上排布，每条线可具有误差阴影和刺激范围 ```MATLAB tiledlayout("flow"); %% 基本用法 nexttile; %生成一些随机数据 Data=rand(5,10,10); %求平均值 Mean=mean(Data,3); %求误差（此处使用SEM） Error=std(Data,0,3)/sqrt(10); %作图 [Lines,Shadows]=DrawFigure.TrialwiseTrace(Mean,Error); %% 自定义样式 nexttile; %横轴在0~1之间 Xs=linspace(0,1,10); %阴影区为半透明红色 FillStyle={"r","FaceAlpha",0.1,"LineStyle","none"}; %图线为虚线 PlotStyle={"--"}; %绘制刺激范围 StimuRange=[0.3 0.4]; %Y轴范围 YLimit=[0 2]; %每条线间隔X为0.1 XSpacing=0.2; [Lines,Shadows,Stimuli]=DrawFigure.TrialwiseTrace(Mean,Error,XSpacing,"StimuRange",StimuRange,"ShadowStyle",FillStyle,"LineStyle",PlotStyle,"Xs",Xs,"YLimit",YLimit); ``` ![](+DrawFigure/示例/TrialwiseTrace.svg) 因为生成的是随机数据，图线位置可能不同，但样式应当一致。 ### 必需参数 MeanLines(:,:)，每一行是一条平均线上的不同时点数值，不同行是不同的平均线 ErrorShadows(:,:)，每一行是一条平均线不同时点的误差，不同行是不同线的误差 ### 可选参数 XSpacing(1,1){mustBeNonnegative}=1，每条线之间的X距离 ### 名称-值对组参数 StimuRange(1,2)，刺激所在的时间范围。如不指定，则不绘制刺激范围，不输出返回值Stimuli。 Xs(1,:)=1:width(MeanLines)，各时点的X值 YLimit(1,2)，Y轴数值范围。如不指定，则由MATLAB自动设置。 LineStyle(1,:)cell={'b'}，均值折线的样式，将传递给plot函数实现 ShadowStyle(1,:)cell={"b","FaceAlpha",0.2,"LineStyle","none"}，误差阴影的样式，将传递给fill函数实现 StimuStyle(1,:)cell={"r","FaceAlpha",0.2,"LineStyle","none"}，刺激范围的样式，将传递给fill函数实现。如果StimuRange未指定，将忽略该参数。 ### 参数互限 MeanLines和ErrorShadows应当具有完全相同的尺寸，且与Xs具有相同的宽度 ### 返回值 Lines(:,1)matlab.graphics.chart.primitive.Line，平均线，plot函数返回的图线对象 Shadows(:,1)matlab.graphics.primitive.Patch，误差阴影，fill函数返回的填充对象 Stimuli(:,1)matlab.graphics.primitive.Patch，刺激范围，fill函数返回的填充对象。如果StimuRange未指定，将不返回该参数，尝试取得该返回值将导致错误。 # 包外工具函数 ## SplitOneSingleDimensionByAnother 将数组某一维度的数据按照分组标记拆分到另一个单一维度中，使得那个单一维度扩张，多出来的空位用指定值补全。 如下代码，先生成4×4×4的随机数，然后将第1维度按照[1 1 2 3]拆分到第4维度中去，多出来的空位用NaN补全。 ```MATLAB [SplitArray,UniqueMarkers] = SplitOneSingleDimensionByAnother(rand(4,4,4),4,1,[1 1 2 3],NaN); ``` 拆分后的数组SplitArray是4×4×4×3，(:,:,:,1)存放原数组(1:2,:,:)的数据，(:,:,:,2)存放原数组(3,:,:)的数据，(:,:,:,3)存放原数组(4,:,:)的数据。UniqueMarkers标识扩张维度上每一维存放了对应了哪个分组标记的那些维度的数据。 ### 输入参数 Array，多维数组 SingleDimension(1,1)uint8，要扩张的单一维度 GroupDimension(1,1)uint8，要拆分的维度 GroupMarkers(:,1)，分组标记向量，其长度必须等于Array的GroupDimension维度的长度 EmptyValue(1,1)，填补空位的标量值 ### 返回值 SplitArray，拆分-扩张后的数组结果 UniqueMarkers(:,1)，向量长度与SplitArray第SingleDimension维度相等，标识扩张维度上每一维存放了对应了哪个分组标记的那些维度的数据。