can

This module’s scope covers operations related to the can file format.

The Tuna can is a image and metadata file format. It consists of a serializable object (instantiated from the tuna.io.can.can class), where convenience methods (such as algebraic procedures on its arrays) are defined.

class tuna.io.can.can(array=None, file_name=None, interference_order=None, interference_reference_wavelength=None, photons=None)

This class’ responsibilities are to create and operate upon Tuna can files.

It inherits from file_reader.

Its constructor signature is:

Parameters:

• array : numpy.ndarray : defaults to None

  The data to be stored in the can.

• file_name : string : defaults to None

  The name of the file containing the data.

• interference_order : integer : defaults to None

  The value of the interference order of the observed light on the data.

• interference_order_wavelength : integer : defaults to None

  The wavelength, in Angstroms, of the observed light on the data.

• photons : dictionary : defaults to None

  A dictionary containing the description of each photon count on the data.

The Tuna can is the preferred internal format for Tuna. Therefore, when most modules are used, they return their result in a can.

Example usage:

import tuna
raw = tuna.io.read ( file_name = "tuna/tuna/test/unit/unit_io/adhoc.ad3" )
type ( raw )
Out[3]: tuna.io.can.can
raw2 = raw + raw
raw_copy = raw2 - raw
raw.flipud ( )
raw.fliplr ( )
raw.convert_ndarray_into_table ( )    
raw.update ( )

convert_ndarray_into_table()

This method’s goal is to convert a numpy.ndarray into a photon table, where the value contained in the array, for each voxel, is considered as a photon count.

The result is saved in self.photons, which has the following structure (example):

self.photons = [ 
    { 'channel' : 10,
      'row'     : 128,
      'col'     : 1,
      'photons' : 1024 },
    { 'channel' : 11,
      'row'     : 128,
      'col'     : 1,
      'photons' : 700 },
    ...
    { 'channel' : 30,
      'row'     : 128,
      'col'     : 128,
      'photons' : 0 } ]

convert_table_into_ndarray()

This method’s goal is to accumulate values from a table (required to be in the same structure as specified in the method convert_ndarray_into_table) into a numpy array.

It will create an array with the minimal dimensions necessary to hold all photons; therefore if you have “photonless” regions in a data cube, and convert it to a table, then back into a cube, you might end with a numpy.ndarray with a different shape than you started.

fliplr()

This method’s goal is to wrap around numpy.fliplr, which flips a 2D array from left to right (the rightmost column becomes the leftmost one). This is applied to each plane of a cube, or the single plane of a planar image.

flipud()

This method’s goal is to wrap around numpy.flipud, which flips a 2D array from up to down (the last line becomes the first). This is applied to each plane of a cube, or the single plane of a planar image.

info()

This method’s goal is to output to the current logging.info handler some metadata about the current can.

read()

This method’s goal is to read a file content’s into a can. Will sequentially attempt to read the file as an .ADT, .fits, .AD2 and .AD3 formatted file. The first attempt to succeed is used.

update()

This method’s goal is to clears current metadata, and regenerate this information based on the current contents of the can’s array and photon table.