-
Notifications
You must be signed in to change notification settings - Fork 12
Overview of `make_cube.py`
The make_cube.py script houses two classes: CubeFactory and TicaCubeFactory. Both of these classes serve to generate a cube from a batch of TESS full frame images (FFIs) that correspond to a TESS sector/camera/CCD observation. There are two different productt (FFI) types that you can generate cubes from that are structurally different, which is why there is one class for each FFI type: CubeFactory will allow you to generate a cube from a batch of mission-delivered FFIs (SPOC FFIs) and TicaCubeFactory will allow you to generate a cube from a batch of TESS Image CAlibrator FFIs (TICA FFIs). There are advantages to using each type, which are outlined in the TESSCut API documentation. This wiki page will walk you through the make_cube.py functionality
The CubeFactory class serves to take in a batch of mission-delivered (SPOC) full frame images and generate a 4-dimensional cube with them, which is then used by CutoutFactory to generate a cutout target pixel file for a designated target or set of coordinates. The main method of this class is make_cube, which calls upon the other methods to generate the cube and store it into a FITS file. The order upon which make_cube calls the methods is as follows:
__init___configure_cube_build_info_table_build_cube_file_write_block_write_info_table
The functionality of each of these methods will be discussed briefly in the sections following. Should there be any questions/comments regarding this wiki page, please file an issue under the Issues tab in this repository or contact us through the Archive Help Desk at [email protected].
This is a standard initialization function within a class that instantiates a certain set of variables as part of the class for future calls later in the code. The max_memory argument is the allocated memory (in GB) that can be used when generating the cube. The smaller this number, the longer it will take to generate the cube, but this number will depend on the specifications of your machine. We suggest leaving this at the default 50 GB unless it causes computational errors.
The attributes block_size and num_blocks are dependent on the input max_memory. This is because the FFIs are not read into the cube all at once, but rather in chunks or "blocks". The block size, and therefore the number of blocks, is calculated from the max_memory value. More detail on this will be under _configure_cube, where these attributes are assigned values.
The remaining attributes are things such as keyword headers, or variables that will be called across multiple functions such as cube_file.
This method will determine the block size (a subset of the full FFI) and the number of blocks to iterate through, based on the input max_memory from __init__. The largest possible block size, or max_block_size is determined by taking the max_memory (converted to Bytes from GB) and dividing it by the slice_size, which is the # of columns in the image multiplied by the # of FFIs in the batch * 2 * 4. [VERIFY:] We multiply by 2 because each cube will have 2 "layers" (axes): 1 axis dedicated to the science data and 1 axis dedicated to the error data, and then multiply by 4 because there are 4 axes per layer. After this calculation is done, the number of blocks is determined by taking the # of rows in the FFIs and dividing by the slice_size, adding 1, and rounding down to the nearest integer ([VERIFY:] we add 1 because np.int always rounds down).
This is also the method that will assign the template_file variable. This is the FFI whose image header keywords are used as the template to initialize the image header table in the later steps.
Lastly, this method also makes the cube's primary header. To do this, we copy the primary header keywords and keyword values from the first FFI in the stack, to the cube file's primary header. Extra header keywords are added such as the factory keywords, and lastly, some primary header keywords are populated with the keyword values from the last FFI in the stack. These keywords are DATE-END and TSTOP for the SPOC FFIs, and ENDTJD for TICA FFIs.
The TicaCubeFactory architecture reflects CubeFactory's with some minor but notable differences. In the sections below, we will point out some of the differences that are not as straight-forward. For the ones that are, we will just refer you back to its analogous section under CubeFactory.