This document is meant as an introduction, explaining basic terms and concepts about the Yohkoh mission and data. A newcomer to Yohkoh should read this document before trying to use the Yohkoh Analysis Guide (YAG). The YAG is a comprehensive guide describing the data and the software; it is self-contained document that explains how to access the data, carry out analysis tasks and even install the software. The YAG may be fairly intimidating at first glance because of its bulk, but the reader should note that the bulk results mostly from the great breadth of the software, and that the basic principles are quite straightforward.
Yohkoh (``Sunbeam'' in Japanese) is a satellite dedicated to high-energy observations of the Sun, specifically of flares and other coronal disturbances. The Yohkoh mission was launched on August 30, 1991, from the Kagoshima Space Centre in southern Japan. The spacecraft carries a payload of four scientific instruments: the Soft X-ray Telescope (SXT), the Hard X-ray Telescope (HXT), the Bragg Crystal Spectrometer (BCS) and the Wide Band Spectrometer (WBS). The SXT (which is sensitive in the range 1-2 KeV) takes images in various wavebands (selected by filters) using a CCD - either the full CCD frame, or a selected part of the CCD frame is returned in telemetry - these are known as full frame, and partial frame images (FFI and PFI); the HXT (which is sensitive in the range 10-100 KeV) measures Fourier components in 4 channels through a set of 64 pairs of grids - the images are reconstructed on the ground; the BCS observes the line complexes of Fe XXVI, Fe XXV, Ca XIX and S XV using bent germanium crystals; and the WBS observes the overall energy release between soft X-rays and gamma-rays using three separate instrument packages. Together these instruments provide the most detailed record yet obtained of high-energy processes in solar flares and in other forms of solar coronal activity.
See the special edition of Solar Physics (1991, Vol 136, No. 1) for more information on the instruments.
The spacecraft is in a slightly elliptical, low-Earth orbit (approx. 570 x 730 km), with an orbital period of ~ 96 minutes. As the orbit precesses, the time the spacecraft spends in sunlight on each revolution varies between 65 and 75 minutes. During 5 or 6 orbits each day, the spacecraft passes through the radiation belts of the South Atlantic Anomaly; at these times, all detectors that use high voltages are turned off (i.e. all BCS and HXT channels, and most WBS channel; the SXT is not affected).
Observations made by the instruments are stored in the spacecraft Bubble Data Recorder (BDR). The BDR has a capacity of 10 Mbytes, and in order to optimise the use of the recorder, the spacecraft can operate at several bit-rates: high, medium and low; switching between these rates is partly automatic (as a function of the spacecraft mode) and is partly controlled by on-board deferred commands. In high bit-rate, the BDR can only hold 42 minutes of observations and some switching of bit-rates is therefore necessary; some overwriting of the data in the BDR is allowed, but the rules for this are beyond the scope of this document.
There are a large number of spacecraft modes, including several subsystem specific modes (e.g. ACS mode for the Attitude Control System specific activities), but the ones of principal interest are Quiet mode and Flare mode; switching between these modes is normally controlled by a flare flag generated by the WBS instrument (its threshold is usually set to GOES X-ray class C2). The allocation of telemetry to the four instruments and other subsystems differs in the different modes, but the main difference between the two principal modes is that there is more HXT data in Flare Mode than in Quiet Mode (where the extra space is used by the SXT).
For 5 or 6 orbits each day, the spacecraft passes over the Kagoshima Space Centre (KSC). During these passes, all spacecraft commanding is performed; commanding at other times is through the on-board deferred command store. The BDR is dumped at each KSC pass, and is in addition dumped at a number of passes (up to 10/day) over the ground-stations of the NASA Deep Space Network (DSN). After each KSC contact, the data received from Yohkoh is reformatted so that quick-look analysis can be performed. Once per week, when all the data has been transmitted to ISAS, the Yohkoh Data Archive is produced by running the reformatter once more.
The Yohkoh reformatter produces a file for each instrument for every orbit, with a start time corresponding to the (predicted) first minute of Sun of the orbit (spacecraft dawn); these files have prefixes of BDA for the BCS instrument, HDA for the HXT, and WDA for the WBS; for the SXT, two files corresponding to full and partial frame images are produced, the SFR and SPR files. The names of these files are of the form ``pppyymmdd.hhmm'', where``ppp'' is the three-letter prefix, ``yymmdd'' is the date (year, month, day) and ``hhmm'' is the time (hours and minutes). For example, ``spr911115.1712'', would contain SXT partial-frame images for the orbit starting at 17:12 UT on 15 November 1991.
All the files are simple byte streams that are interpreted into IDL structures when the files are read in. Each file is broken into a number of sections, the ones of principal interest are the roadmap, index and data sections. For each instrument mode (image, spectral or other integration), there is an index and a data record; the roadmap is a short summary of all the index records. The contents of each section varies slightly between the instruments (as defined by the structures), but there are a number of fields that are always present (e.g. time, spacecraft mode, etc); each file is intended to stand by itself, so some information is duplicated between the files.
From the reformatted instrument files, a number of secondary files are produced. These include the observing logs and other synoptic files, and also a number of files relating to instrument performance and calibration. One secondary file per type per week is produced, with names of form ``pppyy_wwa.nn'', where ``ppp'' is the prefix, ``yy_ww'' is the year and week, and ``nn'' is a revision number; the ``a'' was allocated in case the files had to be split - this has not happened. Examples of files of this type include the Yohkoh event log (EVN), the Yohkoh orbital ephemeris (FEM), the instrument observing logs (OBD, OSF, OSP and OWH), the SXT Dark Current (SDC), etc. For example, the BCS observing log for week 30 of 1993 would be ``obd93_30a.01''.
There are also a few files produced on a monthly basis, e.g. the SXT Full Frame Images (FFI) monthly file (SFM); these have names of the form ``pppyymm00.0000'', where ``ppp'' is the prefix and ``yymm'' is the year and month of the file. For example, ``sfm930600.0000'' would contain an SXT FFI image for each day of the month of June 1993.
A list of all file prefixes can be found in the Yohkoh Analysis Guide, and may also be obtained by typing HELP_PREFIX in IDL.
There are a number of other ancillary datasets that are included in the framework of the Yohkoh Data Archive. These include observations from other spacecraft, and from ground-based observatories. These have names of the form of the secondary files (``pppyy_wwa.nn'', see above), and examples include the GOES event log (GEV), GOES lightcurves (GXT), CGRO Batse lightcurves (GBL), Nobeyama radio lightcurves (NTS), etc.
Some image data from ground-based observatories are also stored, usually in FITS format. Datasets of this type include various images from Big Bear, He 10,830 Angstrom images and magnetograms from Kitt Peak, and H-alpha images from a number of sites around the world. Ground-based data files have a prefix of the form Gsx, where the ``G'' stands for ground-based, ``s'' is the site and ``x'' is the data type. Thus, all Big Bear images have prefixes of the form ``GBx'', and Kitt Peak images prefixes are ``GKx''; all H-alpha images have prefixes of the form ``GsH''.
Again, a list of all file prefixes can be found in the Yohkoh Analysis Guide, and may also be obtained by typing HELP_PREFIX in IDL.
The volume of data produced by Yohkoh exceeds 100 Gbytes, without considering all the supporting datasets; clearly this exceeds the data storage capabilities of the computers most people use and many sites only have a fraction of the files available.
At Institute of Space and Astronautical Science (ISAS) in Japan, the Solar Data Archive Centre (SDAC) in the USA, the UK Yohkoh Data Archive Centre (YDAC), and other principal sites for Yohkoh analysis, all the catalogue files are held on-line, as are all the secondary instrument files and all pertinent subsystem files needed for data analysis. These files are generally stored under subdirectories of root directory /ydb, e.g. /ydb/obd, /ydb/evn; some of the smaller ancillary files are also stored in this area (e.g. /ydb/batse, /ydb/gxt). All such directories are accessed by the software using environment variables (or logicals under VMS) of the form ``$DIR_sss_ppp'', where ``sss'' is a subsystem and ``ppp'' is usually a prefix. Thus, the SXT dark current files would be found under a directory addressed by the environment variable ``DIR_SXT_SDC''; this would probably (but not necessarily) correspond to the directory /ydb/sdc.
If they are held, files from ground based observatories are stored under directories of the form /yd*/gboyy_ww, where ``yy_ww'' is the year and week.
A number of the Yohkoh instrument data files are usually held on-line. How many, and the organization of where the files are held, differs from site to site. For example, there are a number of large flares held at YDAC under /ydb/flares. Within IDL, all public directories holding data are determined by the software through routines like DATA_PATHS.
When analysing Yohkoh data, the only data files needed are those for instruments and periods of interest. Other secondary data files may be needed for detailed analysis; in most cases, only secondary files relating to the weeks of interest will be needed. It is therefore possible to analyse Yohkoh data with only a partial installation of the data and secondary files, changing which ones are kept as the period of interest changes. At the YDAC, all necessary secondary files are stored on-line and these remarks relate mainly to people who wish to continue analysis work at their home institution after first selecting the data through YDAC.
Almost all the Yohkoh analysis software is written in IDL and is generally optimized for computer workstation use.
The BCS, HXT and WBS have a few routines in Fortran and C, but because of difficulties in the transportability between platforms and operating systems, and because of the difficulties that occur if the structures are modified, these are being phased out.
Quite detailed descriptions of general user software for each instrument are given in the Yohkoh Analysis Guide. Nevertheless, a few comments on simple access are given below. While using IDL, more information on any individual routine may be found using the DOC_LIBRARY and XDOC routines; information on the calling sequence of any procedure or function may be found using the routine CHKARG. For example, doc_library,'help_prefix' would return information contained in the documentation header of the routine HELP_PREFIX, and chkarg,'help_prefix' would return information on the calling sequence of the routine.
The initial access route into the Yohkoh Data Archive should be through the catalogue files. For Yohkoh itself, these include the weekly observing logs, the event log, and orbital ephemeris, and the monthly SXT FFI image files. It is possible to do many preliminary searches and statistical surveys using the abstracted data of the observing logs, which for example contains time series of counting rates from each instrument. Additional information can be found in the GOES event log, the files containing the GOES 1-minute lightcurves, and the list of NOAA active regions.
There are many routines that can be of help: Listings of the Yohkoh event log, the orbital ephemeris, the GOES event log, and list of NOAA active regions may be accessed through routines PR_ENV, PR_FEM, PR_GEV, PR_NAR, etc.; the format of the calls for this type of routine is usually PR_ppp, start_time, end_time. Similarly, plots of the GOES lightcurves and the BATSE lightcurves may be produced with PLOT_GOES and PLOT_GBL; again the call is often of the form PLOT_ppp, start_time, end_time. For example, plot_goes,'1-Jun-93' would plot the GOES data for the June 1st, 1993.
Plots from the observing log may be produced with calls to PLOTY, OBS_PLOTand BCS_24HR_PLOT (the later routine is BCS specific).
All of the reformatted instrument files, and many other types of files can be accessed in IDL using the routine YODAT. Through a series of simple questions, the user may select one or more data files of a specified type, and select the desired time interval. The programme then reads in the file, producing a roadmap structure, and if requested, index and data structures. These can then be accessed and displayed by many routines (see the Yohkoh Analysis Guide), but a couple of routines to initially play with are STEPPER for the SXT and BCS_SPMOVIE for the BCS; STEPPER will produce a movie of images, while BCS_SPMOVIE does the same for BCS spectra. LIST_BDA,INDEX allows the user to list the BCS modes, while PRINT,GET_INFO(INDEX) will produce similar following the reading of an SXT data file.
See the Yohkoh Analysis Guide for more information.