File Name Translator Script

Download KOAID File Name Translator Shell Script

The names of data files as ingested into the Keck Observatory Archive (KOA) have been standardized into unique identifiers known as "KOAIDs" in the form AA.YYYYMMDD.#####.fits, where AA is the two-letter code for the instrument, YYYYMMDD is the UT date of observation, and ##### is the five-digit index number representing the number of seconds after UT midnight.

For observers with logs referring to the telescope-assigned filenames or other researchers with data reduction tools that expect file names in the orginal directory structure, it is desirable to translate the KOA filenames back to the original observatory filenames. We provide a UNIX shell script, koa_translator, for this purpose.

Usage:

koa_translator [directory] [-test]

The script looks through the specified directory (or the current directory if there is no argument) and all subdirectories for file names in the KOAID format described above. Files ending in ".fits" or ".fits.gz" will also be processed as these files are assumed to be from KOA.

The "-test" argument creates a file (translate.csh) that can be executed to perform the translation. Without this argument, the script will be created, run, and then deleted.

For each file found, the translator will look through the file's FITS header and reconstruct the original file name (including a parent directory derived from the UT date, and possibly appropriate subdirectories) and write to a file ("translate.csh") the appropriate shell commands to rename the KOA file to the original file name.

Other files with the same KOAID in their file names will also be renamed for consistency.

This is meant to reconstruct the original directory and file name structure as was used at the time of observation. The reconstruction will not always be perfect. Observers may have used nonstandard directory structure, or KOA might have recorded multiple versions of the same original file name. The latter might occur, for example, if observers recorded some files then deleted them and reset the file number to write new files into the same file names.

Note that if there are duplicate original filenames, the program will use the original filename for the first version it finds, then create second (and subsequent, if necessary) versions with ".v2", ".v3", etc. added to the filename. THIS DOES NOT GUARANTEE THAT FILES ALL USING ".v2", FOR EXAMPLE, ARE REALLY FROM THE SAME DATASET. You may have to do some checking to determine which files belong in which dataset.