Package nom.tam.fits

Class RandomGroupsHDU

java.lang.Object
nom.tam.fits.BasicHDU<RandomGroupsData>
nom.tam.fits.RandomGroupsHDU
All Implemented Interfaces:
FitsElement
public class RandomGroupsHDU extends BasicHDU<RandomGroupsData>
Random groups header/data unit. Random groups were an early attempt at extending FITS support beyond images, and was eventually superseded by binary tables, which offer the same functionality and more in a more generic way. The use of random group HDUs is discouraged, even by the FITS standard. Some old radio data may be packaged in this format. Thus apart from provided limited support for reading such data, users should not create random groups anew. BinaryTableHDU offers a much more flexible and capable way for storing an ensemble of parameters, arrays, and more.

Note that the internal storage of random groups is a Object[ngroups][2] array. The first element of each group (row) is a 1D array of parameter data of a numerical primitive type (e.g. short[], double[]). The second element in each group (row) is an image of the same element type as the parameters. When analyzing group data structure only the first group is examined, but for a valid FITS file all groups must have the same structure.

As of version 1.19, we provide support for accessing parameters by names including building up higher-precision values by combining multiple related parameter conversion recipes through scalings and offsets, as described in the FITS standard (e.g. combining 3 or 4 related byte parameter values to obtain a full-precision 32-bit float parameter value when BITPIX is 8).

See Also:

  • Constructor Details

    • RandomGroupsHDU

      public RandomGroupsHDU(Header header, RandomGroupsData data)
      Deprecated.
      (for internal use) Its visibility should be reduced to package level in the future.
      Create an HDU from the given header and data.
      Parameters:
      header - header to use
      data - data to use

  • Method Details

    • encapsulate

      @Deprecated public static RandomGroupsData encapsulate(Object o) throws FitsException
      Deprecated.
      (for internal use) Will reduce visibility in the future
      Parameters:
      o - the array of object to create the random groups
      Returns:
      a random groups data structure from an array of objects representing the data.
      Throws:
      FitsException - if the data could not be created.

    • isData

      @Deprecated public static boolean isData(Object potentialData)
      Deprecated.
      (for internal use) Will reduce visibility in the future
      Check if this data is compatible with Random Groups structure. Must be an Object[nGroups][2] structure with both elements of each group having the same base type and the first element being a simple primitive array. We do not check anything but the first row.
      Parameters:
      potentialData - data to check
      Returns:
      is this data compatible with Random Groups structure

    • isHeader

      @Deprecated public static boolean isHeader(Header hdr)
      Deprecated.
      (for internal use) Will reduce visibility in the future
      Parameters:
      hdr - The header to be tested.
      Returns:
      Is this a random groups header?

    • manufactureData

      @Deprecated public static RandomGroupsData manufactureData(Header header) throws FitsException
      Deprecated.
      (for internal use) Will reduce visibility in the future
      Prepares a data object into which the actual data can be read from an input subsequently or at a later time.
      Parameters:
      header - The FITS header that describes the data
      Returns:
      A data object that support reading content from a stream.
      Throws:
      FitsException - if the data could not be prepared to prescriotion.

    • createFrom

      public static RandomGroupsHDU createFrom(Object[][] data) throws FitsException
      Creates a random groups HDU from an Object[nGroups][2] array. Prior to 1.18, we used Fits.makeHDU(Object) to create random groups HDUs automatically from matching data. However, FITS recommends using binary tables instead of random groups in general, and this type of HDU is included in the standard only to support reading some older radio data. Hence, as of 1.18 Fits.makeHDU(Object) will never return random groups HDUs any longer, and will instead create binary (or ASCII) table HDUs instead. If the need arises to create new random group HDUs programatically, beyond reading of older files, then this method can take its place.
      Parameters:
      data - The random groups table. The second dimension must be 2. The first element in each group (row) must be a 1D numerical primitive array, while the second element may be a multi-dimensional image of the same element type. All rows must consists of arrays of the same primitive numerical types and sized, e.g. { float[5], float[7][2] } or { short[3], short[2][2][4] }.
      Returns:
      a new random groups HDU, which encapsulated the supploed data table.
      Throws:
      FitsException - if the seconds dimension of the array is not 2.
      Since:
      1.18
      See Also:

    • info

      public void info(PrintStream stream)
      Description copied from class: BasicHDU
      Print out some information about this HDU.
      Specified by:
      info in class BasicHDU<RandomGroupsData>
      Parameters:
      stream - the printstream to write the info on

    • getParameterCount

      public int getParameterCount()
      Returns the number of parameter bytes (per data group) accompanying each data object in the group.
      Overrides:
      getParameterCount in class BasicHDU<RandomGroupsData>
      Returns:
      the number of bytes used for arbitrary extra parameters accompanying each data object in the group.
      See Also:

    • getGroupCount

      public int getGroupCount()
      Returns the number of data objects (of identical shape and size) that are group together in this HDUs data segment.
      Overrides:
      getGroupCount in class BasicHDU<RandomGroupsData>
      Returns:
      the number of data objects (of identical shape and size) that are grouped together in the data segment.
      See Also:

    • isHeader

      public boolean isHeader()
      Check that this HDU has a valid header.
      Returns:
      true if this HDU has a valid header.

    • getBUnit

      public String getBUnit()
      Returns the name of the physical unit in which image data are represented.
      Overrides:
      getBUnit in class BasicHDU<RandomGroupsData>
      Returns:
      the standard name of the physical unit in which the image is expressed, e.g. "Jy beam^{-1}".

    • getBlankValue

      public long getBlankValue() throws FitsException
      Returns the integer value that signifies blank (missing or null) data in an integer image.
      Overrides:
      getBlankValue in class BasicHDU<RandomGroupsData>
      Returns:
      the integer value used for identifying blank / missing data in integer images.
      Throws:
      FitsException - if the header does not specify a blanking value or if it is not appropriate for the type of imge (that is not an integer type image)

    • getBScale

      public double getBScale()
      Returns the floating-point increment between adjacent integer values in the image. Strictly speaking, only integer-type images should define a quantization scaling, but there is no harm in having this value in floating-point images also -- which may be interpreted as a hint for quantization, perhaps.
      Overrides:
      getBScale in class BasicHDU<RandomGroupsData>
      Returns:
      the floating-point quantum that corresponds to the increment of 1 in the integer data representation.
      See Also:

    • getBZero

      public double getBZero()
      Returns the floating-point value that corresponds to an 0 integer value in the image. Strictly speaking, only integer-type images should define a quantization scaling, but there is no harm in having this value in floating-point images also -- which may be interpreted as a hint for quantization, perhaps.
      Overrides:
      getBZero in class BasicHDU<RandomGroupsData>
      Returns:
      the floating point value that correspond to the integer 0 in the image data.
      See Also:

    • write

      public void write(ArrayDataOutput stream) throws FitsException
      Description copied from interface: FitsElement
      Writes the contents of the element to a data sink, adding padding as necessary if the element (such as a header or data segment) is expected to complete the FITS block of 2880 bytes.
      Specified by:
      write in interface FitsElement
      Overrides:
      write in class BasicHDU<RandomGroupsData>
      Parameters:
      stream - The data sink.
      Throws:
      FitsException - if the write was unsuccessful.

    • getParameterNames

      public Set<String> getParameterNames()
      Returns a list of parameter names bundled along the images in each group, as extracted from the PTYPE_n_ header entries.
      Returns:
      A set containing the parameter names contained in this HDU
      Since:
      1.19
      See Also:

    • getParameter

      public double getParameter(String name, int group) throws ArrayIndexOutOfBoundsException, FitsException
      Returns the value for a given group parameter.
      Parameters:
      name - the parameter name
      group - the zero-based group index
      Returns:
      the stored parameter value in the specified group, or Double.NaN if the there is no such group.
      Throws:
      ArrayIndexOutOfBoundsException - if the group index is out of bounds.
      FitsException - if the deferred parameter data cannot be accessed
      Since:
      1.19
      See Also: