You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

148 lines
4.1 KiB

4 years ago
  1. Tutorial
  2. ========
  3. Installation
  4. ~~~~~~~~~~~~
  5. The package is available on PyPi. Install it using:
  6. ::
  7. pip install nd2reader
  8. If you don't already have the packages ``numpy``, ``pims``, ``six`` and
  9. ``xmltodict``, they will be installed automatically if you use the
  10. ``setup.py`` script. ``nd2reader`` is an order of magnitude faster in
  11. Python 3. I recommend using it unless you have no other choice. Python
  12. 2.7 and Python >= 3.4 are supported.
  13. Installation via Conda Forge
  14. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  15. Installing ``nd2reader`` from the ``conda-forge`` channel can be
  16. achieved by adding ``conda-forge`` to your channels with:
  17. ::
  18. conda config --add channels conda-forge
  19. Once the ``conda-forge`` channel has been enabled, ``nd2reader`` can be
  20. installed with:
  21. ::
  22. conda install nd2reader
  23. It is possible to list all of the versions of ``nd2reader`` available on
  24. your platform with:
  25. ::
  26. conda search nd2reader --channel conda-forge
  27. Opening ND2s
  28. ~~~~~~~~~~~~
  29. ``nd2reader`` follows the `pims <https://github.com/soft-matter/pims>`__
  30. framework. To open a file and show the first frame:
  31. .. code:: python
  32. from nd2reader import ND2Reader
  33. import matplotlib.pyplot as plt
  34. with ND2Reader('my_directory/example.nd2') as images:
  35. plt.imshow(images[0])
  36. After opening the file, all ``pims`` features are supported. Please
  37. refer to the `pims
  38. documentation <http://soft-matter.github.io/pims/>`__.
  39. ND2 metadata
  40. ~~~~~~~~~~~~
  41. The ND2 file contains various metadata, such as acquisition information,
  42. regions of interest and custom user comments. Most of this metadata is
  43. parsed and available in dictionary form. For example:
  44. .. code:: python
  45. from nd2reader import ND2Reader
  46. with ND2Reader('my_directory/example.nd2') as images:
  47. # width and height of the image
  48. print('%d x %d px' % (images.metadata['width'], images.metadata['height']))
  49. All metadata properties are:
  50. - ``width``: the width of the image in pixels
  51. - ``height``: the height of the image in pixels
  52. - ``date``: the date the image was taken
  53. - ``fields_of_view``: the fields of view in the image
  54. - ``frames``: a list of all frame numbers
  55. - ``z_levels``: the z levels in the image
  56. - ``total_images_per_channel``: the number of images per color channel
  57. - ``channels``: the color channels
  58. - ``pixel_microns``: the amount of microns per pixel
  59. - ``rois``: the regions of interest (ROIs) defined by the user
  60. - ``experiment``: information about the nature and timings of the ND
  61. experiment
  62. Iterating over fields of view
  63. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  64. Using ``NDExperiments`` in the Nikon software, it is possible to acquire
  65. images on different ``(x, y)`` positions. This is referred to as
  66. different fields of view. Using this reader, the fields of view are on
  67. the ``v`` axis. For example:
  68. .. code:: python
  69. from nd2reader import ND2Reader
  70. with ND2Reader('my_directory/example.nd2') as images:
  71. # width and height of the image
  72. print(images.metadata)
  73. will output
  74. .. code:: python
  75. {'channels': ['BF100xoil-1x-R', 'BF+RITC'],
  76. 'date': datetime.datetime(2017, 10, 30, 14, 35, 18),
  77. 'experiment': {'description': 'ND Acquisition',
  78. 'loops': [{'duration': 0,
  79. 'sampling_interval': 0.0,
  80. 'start': 0,
  81. 'stimulation': False}]},
  82. 'fields_of_view': [0, 1],
  83. 'frames': [0],
  84. 'height': 1895,
  85. 'num_frames': 1,
  86. 'pixel_microns': 0.09214285714285715,
  87. 'total_images_per_channel': 6,
  88. 'width': 2368,
  89. 'z_levels': [0, 1, 2]}
  90. for our example file. As you can see from the metadata, it has two
  91. fields of view. We can also look at the sizes of the axes:
  92. .. code:: python
  93. print(images.sizes)
  94. .. code:: python
  95. {'c': 2, 't': 1, 'v': 2, 'x': 2368, 'y': 1895, 'z': 3}
  96. As you can see, the fields of view are listed on the ``v`` axis. It is
  97. therefore possible to loop over them like this:
  98. .. code:: python
  99. images.iter_axes = 'v'
  100. for fov in images:
  101. print(fov) # Frame containing one field of view
  102. For more information on axis bundling and iteration, refer to the `pims
  103. documentation <http://soft-matter.github.io/pims/v0.4/multidimensional.html#axes-bundling>`__.