.. auto-generated by script ../../../../utils/nxdl2rst.py from the NXDL source NXregion.nxdl.xml .. index:: ! NXregion (base class) ! region (base class) see: region (base class); NXregion .. _NXregion: ======== NXregion ======== **Status**: base class, extends :ref:`NXobject` **Description**: Geometry and logical description of a region of data in a parent group. When used, it could be a child group to, say, :ref:`NXdetector`. This can be used to describe a subset of data used to create downsampled data or to derive some data from that subset. Note, the fields for the rectangular region specifiers follow HDF5’s dataspace hyperslab parameters (see https://portal.hdfgroup.org/display/HDF5/H5S_SELECT_HYPERSLAB). Note when **block** :math:`= 1`, then **stride** :math:`\equiv` **step** in Python slicing. For example, a ROI sum of an area starting at index of [20,50] and shape [220,120] in image data:: detector:NXdetector/ data[60,256,512] region:NXregion/ @region_type = "rectangular" parent = "data" start = [20,50] count = [220,120] statistics:NXdata/ @signal = "sum" sum[60] the ``sum`` dataset contains the summed areas in each frame. Another example, a hyperspectral image downsampled 16-fold in energy:: detector:NXdetector/ data[128,128,4096] region:NXregion/ @region_type = "rectangular" parent = "data" start = [2] count = [20] stride = [32] block = [16] downsampled:NXdata/ @signal = "maximum" @auxiliary_signals = "copy" maximum[128,128,20] copy[128,128,320] the ``copy`` dataset selects 20 16-channel blocks that start 32 channels apart, the ``maximum`` dataset will show maximum values in each 16-channel block in every spectra. **Symbols**: These symbols will denote how the shape of the parent group's data field, .. math:: (D_0, ..., D_{\mathbf{O}-1}, d_0, ..., d_{\mathbf{R}-1}) could be split into a left set of **O** outer dimensions, :math:`\boldsymbol{D}`, and a right set of **R** region dimensions, :math:`\boldsymbol{d}`, where the data field has rank **O** + **R**. Note **O** :math:`>= 0`. **O**: Outer rank **R**: Region rank **Groups cited**: :ref:`NXdata` .. index:: NXdata (base class); used in base class **Structure**: .. _/NXregion@region_type-attribute: .. index:: region_type (file attribute) **@region_type**: (required) :ref:`NX_CHAR ` This is ``rectangular`` to describe the region as a hyper-rectangle in the index space of its parent group's data field. Obligatory value: ``rectangular`` .. _/NXregion/parent-field: .. index:: parent (field) **parent**: (optional) :ref:`NX_CHAR ` The name of data field in the parent group or the path of a data field relative to the parent group (so it could be a field in a subgroup of the parent group) .. _/NXregion/parent_mask-field: .. index:: parent_mask (field) **parent_mask**: (optional) :ref:`NX_CHAR ` The name of an optional mask field in the parent group with rank :math:`\boldsymbol{R}` and dimensions :math:`\boldsymbol{d}`. For example, this could be ``pixel_mask`` of an :ref:`NXdetector`. .. _/NXregion/start-field: .. index:: start (field) **start**: (recommended) :ref:`NX_NUMBER ` (Rank: 1, Dimensions: [R]) The starting position for region in detector data field array. This is recommended as it also defines the region rank. If omitted then defined as an array of zeros. .. _/NXregion/count-field: .. index:: count (field) **count**: (recommended) :ref:`NX_INT ` (Rank: 1, Dimensions: [R]) The number of blocks or items in the hyperslab selection. If omitted then defined as an array of dimensions that take into account the other hyperslab selection fields to span the parent data field's shape. .. _/NXregion/stride-field: .. index:: stride (field) **stride**: (optional) :ref:`NX_INT ` (Rank: 1, Dimensions: [R]) An optional field to define striding used to downsample data. If omitted then defined as an array of ones. .. _/NXregion/block-field: .. index:: block (field) **block**: (optional) :ref:`NX_INT ` (Rank: 1, Dimensions: [R]) An optional field to define the block size used to copy or downsample data. In the :math:`i`-th dimension, if :math:`\mathbf{block}[i] \lt \mathbf{stride}[i]` then the downsampling blocks have gaps between them; when ``block`` matches ``stride`` then the blocks are contiguous; otherwise the blocks overlap. If omitted then defined as an array of ones. .. _/NXregion/scale-field: .. index:: scale (field) **scale**: (optional) :ref:`NX_NUMBER ` (Rank: 1, Dimensions: [R]) An optional field to define a divisor for scaling of reduced data. For example, in a downsampled sum, it can reduce the maximum values to fit in the domain of the result data type. In an image that is downsampled by summing 2x2 blocks, using :math:`\mathrm{scale}=4` allows the result to fit in the same integer type dataset as the parent dataset. If omitted then no scaling occurs. .. _/NXregion/downsampled-group: **downsampled**: (optional) :ref:`NXdata` An optional group containing data copied/downsampled from parent group’s data. Its dataset name must reflect how the downsampling is done over each block. So it could be a reduction operation such as sum, minimum, maximum, mean, mode, median, etc. If downsampling is merely copying each block then use "copy" as the name. Where more than one downsample dataset is written (specified with ``@signal``) then add ``@auxiliary_signals`` listing the others. In the copy case, the field should have a shape of :math:`(D_0, ..., D_{\mathbf{O}-1}, \mathbf{block}[0] * \mathbf{count}[0], ..., \mathbf{block}[\mathbf{R}-1] * \mathbf{count}[\mathbf{R}-1])`, otherwise the expected shape is :math:`(D_0, ..., D_{\mathbf{O}-1}, \mathbf{count}[0], ..., \mathbf{count}[\mathbf{R}-1])`. The following figure shows how blocks are used in downsampling: .. figure:: region/NXregion-example.png :width: 60% A selection with :math:`\mathbf{start}=2, \mathbf{count}=4, \mathbf{stride}=3, \mathbf{block}=2` from a dataset with shape [13] will result in the ``reduce`` dataset of shape [4] and a ``copy`` dataset of shape [8]. .. _/NXregion/statistics-group: **statistics**: (optional) :ref:`NXdata` An optional group containing any statistics derived from the region in parent group’s data such as sum, minimum, maximum, mean, mode, median, rms, variance, etc. Where more than one statistical dataset is written (specified with ``@signal``) then add ``@auxiliary_signals`` listing the others. All data fields should have shapes of :math:`\boldsymbol{D}`. Hypertext Anchors ----------------- List of hypertext anchors for all groups, fields, attributes, and links defined in this class. * :ref:`/NXregion/block-field ` * :ref:`/NXregion/count-field ` * :ref:`/NXregion/downsampled-group ` * :ref:`/NXregion/parent-field ` * :ref:`/NXregion/parent_mask-field ` * :ref:`/NXregion/scale-field ` * :ref:`/NXregion/start-field ` * :ref:`/NXregion/statistics-group ` * :ref:`/NXregion/stride-field ` * :ref:`/NXregion@region_type-attribute ` **NXDL Source**: https://github.com/nexusformat/definitions/blob/main/base_classes/NXregion.nxdl.xml