另一个nd2 (Nikon NIS Elements) 文件读取器
项目描述
nd2
.nd2 (Nikon NIS Elements) 文件读取器。
此读取器提供了Nikon ND2 SDK的纯Python实现。
它曾经使用Cython封装了官方SDK，但后来已经完全重写为纯Python（为了性能、易于分发和维护），同时保持与官方SDK完全的API兼容性。
注意： 此库与尼康没有任何关联，但我们感谢实验室成像SDK开发者的帮助。
功能包括良好的元数据检索、直接to_dask和to_xarray选项用于延迟和/或注释数组，以及输出到OME-TIFF。
此库已针对许多nd2文件进行了测试，旨在最大化兼容性和数据提取。（如果您发现某个nd2文件以某种方式失败，请提交问题并提供文件！）
:book: 文档
安装
pip install nd2
或从conda
conda install -c conda-forge nd2
支持旧版nd2文件
旧版nd2 (JPEG2000) 文件也受支持，但需要imagecodecs。要安装支持这些文件的版本，请使用legacy附加组件。
pip install nd2[legacy]
更快的XML解析
文件中的大部分元数据都存储为XML。如果环境中有，则nd2将使用比内置的xml模块快得多的lxml。要安装支持lxml的版本，请使用
pip install nd2 lxml
使用方法和API
完整的API文档可在https://tlambert03.github.io/nd2找到。
以下为快速总结
import nd2
import numpy as np
my_array = nd2.imread('some_file.nd2') # read to numpy array
my_array = nd2.imread('some_file.nd2', dask=True) # read to dask array
my_array = nd2.imread('some_file.nd2', xarray=True) # read to xarray
my_array = nd2.imread('some_file.nd2', xarray=True, dask=True) # read to dask-xarray
# or open a file with nd2.ND2File
f = nd2.ND2File('some_file.nd2')
# (you can also use nd2.ND2File() as a context manager)
with nd2.ND2File('some_file.nd2') as ndfile:
print(ndfile.metadata)
...
# ATTRIBUTES: # example output
f.path # 'some_file.nd2'
f.shape # (10, 2, 256, 256)
f.ndim # 4
f.dtype # np.dtype('uint16')
f.size # 1310720 (total voxel elements)
f.sizes # {'T': 10, 'C': 2, 'Y': 256, 'X': 256}
f.is_rgb # False (whether the file is rgb)
# if the file is RGB, `f.sizes` will have
# an additional {'S': 3} component
# ARRAY OUTPUTS
f.asarray() # in-memory np.ndarray - or use np.asarray(f)
f.to_dask() # delayed dask.array.Array
f.to_xarray() # in-memory xarray.DataArray, with labeled axes/coords
f.to_xarray(delayed=True) # delayed xarray.DataArray
# OME-TIFF OUTPUT (new in v0.10.0)
f.write_tiff('output.ome.tif') # write to ome-tiff file
# see below for examples of these structures
# METADATA # returns instance of ...
f.attributes # nd2.structures.Attributes
f.metadata # nd2.structures.Metadata
f.frame_metadata(0) # nd2.structures.FrameMetadata (frame-specific meta)
f.experiment # List[nd2.structures.ExpLoop]
f.text_info # dict of misc info
f.voxel_size() # VoxelSize(x=0.65, y=0.65, z=1.0)
f.rois # Dict[int, nd2.structures.ROI]
f.binary_data # any binary masks stored in the file. See below.
f.events() # returns tabular "Recorded Data" view from in NIS Elements/Viewer
# with info for each frame in the experiment.
# output is passabled to pandas.DataFrame
f.ome_metadata() # returns metadata as an ome_types.OME object
# (requires ome-types package)
# allll the metadata we can find...
# no attempt made to standardize or parse it
# look in here if you're searching for metadata that isn't exposed in the above
# but try not to rely on it, as it's not guaranteed to be stable
f.unstructured_metadata()
f.close() # don't forget to close when not using a context manager!
f.closed # boolean, whether the file is closed
元数据结构
这些结构遵循尼康SDK输出结构（如有相关）。以下是部分示例输出
属性
Attributes(
bitsPerComponentInMemory=16,
bitsPerComponentSignificant=16,
componentCount=2,
heightPx=32,
pixelDataType='unsigned',
sequenceCount=60,
widthBytes=128,
widthPx=32,
compressionLevel=None,
compressionType=None,
tileHeightPx=None,
tileWidthPx=None,
channelCount=2
)
元数据
注意：对于旧版（JPEG2000）文件的data将是一个普通的未结构化字典。
Metadata(
contents=Contents(channelCount=2, frameCount=60),
channels=[
Channel(
channel=ChannelMeta(
name='Widefield Green',
index=0,
color=Color(r=91, g=255, b=0, a=1.0),
emissionLambdaNm=535.0,
excitationLambdaNm=None
),
loops=LoopIndices(NETimeLoop=None, TimeLoop=0, XYPosLoop=1, ZStackLoop=2),
microscope=Microscope(
objectiveMagnification=10.0,
objectiveName='Plan Fluor 10x Ph1 DLL',
objectiveNumericalAperture=0.3,
zoomMagnification=1.0,
immersionRefractiveIndex=1.0,
projectiveMagnification=None,
pinholeDiameterUm=None,
modalityFlags=['fluorescence']
),
volume=Volume(
axesCalibrated=[True, True, True],
axesCalibration=[0.652452890023035, 0.652452890023035, 1.0],
axesInterpretation=(
<AxisInterpretation.distance: 'distance'>,
<AxisInterpretation.distance: 'distance'>,
<AxisInterpretation.distance: 'distance'>
),
bitsPerComponentInMemory=16,
bitsPerComponentSignificant=16,
cameraTransformationMatrix=[-0.9998932296054086, -0.014612644841559427, 0.014612644841559427, -0.9998932296054086],
componentCount=1,
componentDataType='unsigned',
voxelCount=[32, 32, 5],
componentMaxima=[0.0],
componentMinima=[0.0],
pixelToStageTransformationMatrix=None
)
),
Channel(
channel=ChannelMeta(
name='Widefield Red',
index=1,
color=Color(r=255, g=85, b=0, a=1.0),
emissionLambdaNm=620.0,
excitationLambdaNm=None
),
loops=LoopIndices(NETimeLoop=None, TimeLoop=0, XYPosLoop=1, ZStackLoop=2),
microscope=Microscope(
objectiveMagnification=10.0,
objectiveName='Plan Fluor 10x Ph1 DLL',
objectiveNumericalAperture=0.3,
zoomMagnification=1.0,
immersionRefractiveIndex=1.0,
projectiveMagnification=None,
pinholeDiameterUm=None,
modalityFlags=['fluorescence']
),
volume=Volume(
axesCalibrated=[True, True, True],
axesCalibration=[0.652452890023035, 0.652452890023035, 1.0],
axesInterpretation=(
<AxisInterpretation.distance: 'distance'>,
<AxisInterpretation.distance: 'distance'>,
<AxisInterpretation.distance: 'distance'>
),
bitsPerComponentInMemory=16,
bitsPerComponentSignificant=16,
cameraTransformationMatrix=[-0.9998932296054086, -0.014612644841559427, 0.014612644841559427, -0.9998932296054086],
componentCount=1,
componentDataType='unsigned',
voxelCount=[32, 32, 5],
componentMaxima=[0.0],
componentMinima=[0.0],
pixelToStageTransformationMatrix=None
)
)
]
)
实验
[
TimeLoop(
count=3,
nestingLevel=0,
parameters=TimeLoopParams(
startMs=0.0,
periodMs=1.0,
durationMs=0.0,
periodDiff=PeriodDiff(avg=16278.339965820312, max=16411.849853515625, min=16144.830078125)
),
type='TimeLoop'
),
XYPosLoop(
count=4,
nestingLevel=1,
parameters=XYPosLoopParams(
isSettingZ=True,
points=[
Position(stagePositionUm=[26950.2, -1801.6000000000001, 498.46000000000004], pfsOffset=None, name=None),
Position(stagePositionUm=[31452.2, -1801.6000000000001, 670.7], pfsOffset=None, name=None),
Position(stagePositionUm=[35234.3, 2116.4, 664.08], pfsOffset=None, name=None),
Position(stagePositionUm=[40642.9, -3585.1000000000004, 555.12], pfsOffset=None, name=None)
]
),
type='XYPosLoop'
),
ZStackLoop(count=5, nestingLevel=2, parameters=ZStackLoopParams(homeIndex=2, stepUm=1.0, bottomToTop=True, deviceName='Ti2 ZDrive'), type='ZStackLoop')
]
兴趣区域
在元数据中找到的兴趣区域在ND2File.rois中可用，它是一个dict，包含nd2.structures.ROI对象，以ROI ID为键。
{
1: ROI(
id=1,
info=RoiInfo(
shapeType=<RoiShapeType.Rectangle: 3>,
interpType=<InterpType.StimulationROI: 4>,
cookie=1,
color=255,
label='',
stimulationGroup=0,
scope=1,
appData=0,
multiFrame=False,
locked=False,
compCount=2,
bpc=16,
autodetected=False,
gradientStimulation=False,
gradientStimulationBitDepth=0,
gradientStimulationLo=0.0,
gradientStimulationHi=0.0
),
guid='{87190352-9B32-46E4-8297-C46621C1E1EF}',
animParams=[
AnimParam(
timeMs=0.0,
enabled=1,
centerX=-0.4228425369685782,
centerY=-0.5194951478743071,
centerZ=0.0,
rotationZ=0.0,
boxShape=BoxShape(
sizeX=0.21256931608133062,
sizeY=0.21441774491682075,
sizeZ=0.0
),
extrudedShape=ExtrudedShape(sizeZ=0, basePoints=[])
)
]
),
...
}
文本信息
{
'capturing': 'Flash4.0, SN:101412\r\nSample 1:\r\n Exposure: 100 ms\r\n Binning: 1x1\r\n Scan Mode: Fast\r\nSample 2:\r\n Exposure: 100 ms\r\n Binning: 1x1\r\n Scan Mode: Fast',
'date': '9/28/2021 9:41:27 AM',
'description': 'Metadata:\r\nDimensions: T(3) x XY(4) x λ(2) x Z(5)\r\nCamera Name: Flash4.0, SN:101412\r\nNumerical Aperture: 0.3\r\nRefractive Index: 1\r\nNumber of Picture Planes: 2\r\nPlane #1:\r\n Name: Widefield Green\r\n Component Count: 1\r\n Modality: Widefield Fluorescence\r\n Camera Settings: Exposure: 100 ms\r\n Binning: 1x1\r\n Scan Mode: Fast\r\n Microscope Settings: Nikon Ti2, FilterChanger(Turret-Lo): 3 (FITC)\r\n Nikon Ti2, Shutter(FL-Lo): Open\r\n Nikon Ti2, Shutter(DIA LED): Closed\r\n Nikon Ti2, Illuminator(DIA): Off\r\n Nikon Ti2, Illuminator(DIA) Iris intensity: 3.0\r\n Analyzer Slider: Extracted\r\n Analyzer Cube: Extracted\r\n Condenser: 1 (Shutter)\r\n PFS, state: On\r\n PFS, offset: 7959\r\n PFS, mirror: Inserted\r\n PFS, Dish Type: Glass\r\n Zoom: 1.00x\r\n Sola, Shutter(Sola): Active\r\n Sola, Illuminator(Sola) Voltage: 100.0\r\nPlane #2:\r\n Name: Widefield Red\r\n Component Count: 1\r\n Modality: Widefield Fluorescence\r\n Camera Settings: Exposure: 100 ms\r\n Binning: 1x1\r\n Scan Mode: Fast\r\n Microscope Settings: Nikon Ti2, FilterChanger(Turret-Lo): 4 (TRITC)\r\n Nikon Ti2, Shutter(FL-Lo): Open\r\n Nikon Ti2, Shutter(DIA LED): Closed\r\n Nikon Ti2, Illuminator(DIA): Off\r\n Nikon Ti2, Illuminator(DIA) Iris intensity: 1.5\r\n Analyzer Slider: Extracted\r\n Analyzer Cube: Extracted\r\n Condenser: 1 (Shutter)\r\n PFS, state: On\r\n PFS, offset: 7959\r\n PFS, mirror: Inserted\r\n PFS, Dish Type: Glass\r\n Zoom: 1.00x\r\n Sola, Shutter(Sola): Active\r\n Sola, Illuminator(Sola) Voltage: 100.0\r\nTime Loop: 3\r\n- Equidistant (Period 1 ms)\r\nZ Stack Loop: 5\r\n- Step: 1 µm\r\n- Device: Ti2 ZDrive',
'optics': 'Plan Fluor 10x Ph1 DLL'
}
二进制数据
此属性返回一个表示nd2文件中所有二进制掩膜的nd2.BinaryLayers对象。
nd2.BinaryLayers对象是一系列单个nd2.BinaryLayer对象（每个二进制层一个），每个BinaryLayer在序列中是一个命名元组，其中包含诸如name属性和data属性等，其中data属性是numpy数组的列表（每个实验帧一个），如果二进制层在该帧中没有数据，则为None。
最常见的用法是将整个BinaryLayers对象或单个BinaryLayer转换为numpy.ndarray。
>>> import nd2
>>> nd2file = nd2.ND2File('path/to/file.nd2')
>>> binary_layers = nd2file.binary_data
# The output array will have shape
# (n_binary_layers, *coord_shape, *frame_shape).
>>> np.asarray(binary_layers)
例如，如果nd2文件中的数据形状为(nT, nZ, nC, nY, nX)，且有4个二进制层，那么np.asarray(nd2file.binary_data)的输出形状将为(4, nT, nZ, nY, nX)。（注意，输出数组中不存在nC维度，二进制层始终位于第一个轴）。
您还可以将单个BinaryLayer转换为numpy数组。
>>> binary_layer = binary_layers[0]
>>> np.asarray(binary_layer)
事件
此属性返回NIS查看器中图像属性 > 记录数据选项卡中报告的表格数据。
（将有一个列对应于上述custom_data部分的CustomDataV2_0部分的每个标记，以及元数据中找到的任何其他事件）
返回类型数据的格式由orient参数控制
'records'：列表字典 -[{列 -> 值}, ...]（默认值）'dict'：字典字典 -{列 -> {索引 -> 值}, ...}'list'：字典列表 -{列 -> [值, ...]}
不是每个事件都包含每个列标题，因此当orient为'dict'或'list'时，将插入float('nan')以保持每列的长度一致。
# with `orient='records'` (DEFAULT)
[
{
'Time [s]': 1.32686654,
'Z-Series': -2.0,
'Exposure Time [ms]': 100.0,
'PFS Offset': 0,
'PFS Status': 0,
'X Coord [µm]': 31452.2,
'Y Coord [µm]': -1801.6,
'Z Coord [µm]': 552.74,
'Ti2 ZDrive [µm]': 552.74
},
{
'Time [s]': 1.69089657,
'Z-Series': -1.0,
'Exposure Time [ms]': 100.0,
'PFS Offset': 0,
'PFS Status': 0,
'X Coord [µm]': 31452.2,
'Y Coord [µm]': -1801.6,
'Z Coord [µm]': 553.74,
'Ti2 ZDrive [µm]': 553.74
},
{
'Time [s]': 2.04194662,
'Z-Series': 0.0,
'Exposure Time [ms]': 100.0,
'PFS Offset': 0,
'PFS Status': 0,
'X Coord [µm]': 31452.2,
'Y Coord [µm]': -1801.6,
'Z Coord [µm]': 554.74,
'Ti2 ZDrive [µm]': 554.74
},
{
'Time [s]': 2.38194662,
'Z-Series': 1.0,
'Exposure Time [ms]': 100.0,
'PFS Offset': 0,
'PFS Status': 0,
'X Coord [µm]': 31452.2,
'Y Coord [µm]': -1801.6,
'Z Coord [µm]': 555.74,
'Ti2 ZDrive [µm]': 555.74
},
{
'Time [s]': 2.63795663,
'Z-Series': 2.0,
'Exposure Time [ms]': 100.0,
'PFS Offset': 0,
'PFS Status': 0,
'X Coord [µm]': 31452.2,
'Y Coord [µm]': -1801.6,
'Z Coord [µm]': 556.74,
'Ti2 ZDrive [µm]': 556.74
}
]
# with `orient='list'`
{
'Time [s]': array([1.32686654, 1.69089657, 2.04194662, 2.38194662, 2.63795663]),
'Z-Series': array([-2., -1., 0., 1., 2.]),
'Exposure Time [ms]': array([100., 100., 100., 100., 100.]),
'PFS Offset': array([0, 0, 0, 0, 0], dtype=int32),
'PFS Status': array([0, 0, 0, 0, 0], dtype=int32),
'X Coord [µm]': array([31452.2, 31452.2, 31452.2, 31452.2, 31452.2]),
'Y Coord [µm]': array([-1801.6, -1801.6, -1801.6, -1801.6, -1801.6]),
'Z Coord [µm]': array([552.74, 553.74, 554.74, 555.74, 556.74]),
'Ti2 ZDrive [µm]': array([552.74, 553.74, 554.74, 555.74, 556.74])
}
# with `orient='dict'`
{
'Time [s]': {0: 1.32686654, 1: 1.69089657, 2: 2.04194662, 3: 2.38194662, 4: 2.63795663},
'Z-Series': {0: -2.0, 1: -1.0, 2: 0.0, 3: 1.0, 4: 2.0},
'Exposure Time [ms]': {0: 100.0, 1: 100.0, 2: 100.0, 3: 100.0, 4: 100.0},
'PFS Offset []': {0: 0, 1: 0, 2: 0, 3: 0, 4: 0},
'PFS Status []': {0: 0, 1: 0, 2: 0, 3: 0, 4: 0},
'X Coord [µm]': {0: 31452.2, 1: 31452.2, 2: 31452.2, 3: 31452.2, 4: 31452.2},
'Y Coord [µm]': {0: -1801.6, 1: -1801.6, 2: -1801.6, 3: -1801.6, 4: -1801.6},
'Z Coord [µm]': {0: 552.74, 1: 553.74, 2: 554.74, 3: 555.74, 4: 556.74},
'Ti2 ZDrive [µm]': {0: 552.74, 1: 553.74, 2: 554.74, 3: 555.74, 4: 556.74}
}
您可以将events()的输出传递给pandas.DataFrame。
In [1]: pd.DataFrame(nd2file.events())
Out[1]:
Time [s] Z-Series Exposure Time [ms] PFS Offset PFS Status [] X Coord [µm] Y Coord [µm] Z Coord [µm] Ti2 ZDrive [µm]
0 1.326867 -2.0 100.0 0 0 31452.2 -1801.6 552.74 552.74
1 1.690897 -1.0 100.0 0 0 31452.2 -1801.6 553.74 553.74
2 2.041947 0.0 100.0 0 0 31452.2 -1801.6 554.74 554.74
3 2.381947 1.0 100.0 0 0 31452.2 -1801.6 555.74 555.74
4 2.637957 2.0 100.0 0 0 31452.2 -1801.6 556.74 556.74
5 8.702229 -2.0 100.0 0 0 31452.2 -1801.6 552.70 552.70
6 9.036269 -1.0 100.0 0 0 31452.2 -1801.6 553.70 553.70
7 9.330319 0.0 100.0 0 0 31452.2 -1801.6 554.68 554.68
8 9.639349 1.0 100.0 0 0 31452.2 -1801.6 555.70 555.70
9 9.906369 2.0 100.0 0 0 31452.2 -1801.6 556.64 556.64
10 11.481439 -2.0 100.0 0 0 31452.2 -1801.6 552.68 552.68
11 11.796479 -1.0 100.0 0 0 31452.2 -1801.6 553.68 553.68
12 12.089479 0.0 100.0 0 0 31452.2 -1801.6 554.68 554.68
13 12.371539 1.0 100.0 0 0 31452.2 -1801.6 555.68 555.68
14 12.665469 2.0 100.0 0 0 31452.2 -1801.6 556.68 556.68
ome_metadata()
有关此方法返回的OME类型的详细信息，请参阅ome-types文档。
In [1]: ome = nd2file.ome_metadata()
In [2]: print(ome)
OME(
instruments=[<1 Instrument>],
images=[<1 Image>],
creator='nd2 v0.7.1'
)
In [3]: print(ome.to_xml())
<OME xmlns="http://www.openmicroscopy.org/Schemas/OME/2016-06"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.openmicroscopy.org/Schemas/OME/2016-06 http://www.openmicroscopy.org/Schemas/OME/2016-06/ome.xsd"
Creator="nd2 v0.7.1.dev2+g4ea166e.d20230709">
<Instrument ID="Instrument:0">
<Detector Model="Hamamatsu Dual C14440-20UP" SerialNumber="Hamamatsu Dual C14440-20UP" ID="Detector:0"/>
</Instrument>
<Image ID="Image:0" Name="test39">
<AcquisitionDate>2023-07-08T09:30:55</AcquisitionDate>
...
贡献/开发
要本地测试和贡献，请克隆此存储库，然后
pip install -e .[dev]
下载样本数据
pip install requests
python scripts/download_samples.py
然后运行测试
pytest
（如果不起作用，请随意打开一个问题！）
替代方案
以下是我知道的一些其他nd2读取器，尽管其中许多不再维护
- pims_nd2 - 基于pims的读取器。v9.00（2015）SDK的ctypes包装器
- nd2reader - 基于pims的读取器，使用反向工程文件头。主要在NIS Elements 4.30.02的文件上进行测试
- nd2file - 另一个纯Python，分块映射读取器，未维护？
- pyND2SDK - 仅限Windows的v9.00（2015）SDK的cython包装器。不在PyPI上
创建此库的动机因素包括
- 支持尽可能多的nd2文件，具有大型测试套件并强调正确性
- 基于dask的pims独立延迟读取器
- 通过xarray关联轴元数据
下载文件
下载适合您平台的文件。如果您不确定选择哪个，请了解有关 安装包 的更多信息。
源分布
nd2-0.10.1.tar.gz (645.4 kB 查看哈希值)
构建分布
nd2-0.10.1-py3-none-any.whl (81.1 kB 查看哈希值)
关闭
nd2-0.10.1.tar.gz 的哈希值
| 算法 | 哈希摘要 | |
|---|---|---|
| SHA256 | 88ee60f6ba39392722a162da58fb81bf0cdb8ed6c772772e4db91e90f97e490a |
|
| MD5 | 7f27a8c74af1d1a7c67eee39deee83d5 |
|
| BLAKE2b-256 | c324d8a4c64704492127f5e061f9d595a8ad29ada1340847fb16650c0478500a |
关闭
nd2-0.10.1-py3-none-any.whl 的哈希值
| 算法 | 哈希摘要 | |
|---|---|---|
| SHA256 | 52458bc09a43390429c60e0103fc9bdc21432714d98c23ca86fce4eb80473aa0 |
|
| MD5 | c26b9dd341a4da2f5c861fde7bc85e79 |
|
| BLAKE2b-256 | cadb87558eccc05ddd7421913e7ae5c70a92dc29ff094a5079b9f2c042d9fcd8 |