Full list of tools Importing data Plotting data Importing a complete set of data Before using, there is a one-time set-up prerequisite. Edit one line in kpValuesAt.m (in package rpiKPExtract): Line 6: folder = 'Z:\REU - IMAGE\Matlab Scripts\rpiKPExtract\'; Replace our folder 'Z:\REU - IMAGE\Matlab Scripts\rpiKPExtract\' with the path to where the package rpiKPExtract is installed on your hard drive. Also, be sure to add to Matlab's path library the location of where you put the RPI scripts. When you are in BinBrowser, find the plasmagrams that you wish to group as a set. For each plasmagram, save it as an PNG file in a folder of choice. Use the default filename supplied by BinBrowser (usually a time stamp like 20040814_205914_pr38.png) to ease later sorting features. For each plasmagram, also save the accompanying bin data in an ASCII file, and name it [image-name].bin, where image-name is what you called the PNG file. It should be in the same folder as the PNG file. If BinBrowser is currently online (status indicated in title bar), also save the accompanying spin data for each plasmagram. The spin data is found by clicking the Info button and then clicking S/C Spin on the pop-menu window. Copy and paste all of the spin data shown into a text file called [image-name].spin, where image-name is what you called the PNG file. It should be in the same folder as the previous files. To complete the data extraction process, you need to get the global parameters. Use All_Info.txt as the filename. If all of your plasmagrams appear in the list under Session Selector, than this All_Info.txt will be sufficient. If some of the plasmagrams were from a different session set (e.g. a different local level 0 file), you have two options: Save the global parameters of the other set as a different file, say All_Info2.txt, and append the body of the second file (excluding the header lines) onto the end of the first file All_Info.txt. The modified All_Info.txt will then contain parameters for both session sets. The easier option is to process each session set separately, so that their data exist in separate folders. Each folder contains the corresponding All_Info.txt. At this point, the folder to be processed should resemble: 20040814_000937_pr38.png 20040815_000937_pr38.png 20040816_000937_pr38.png 20040814_000937_pr38.spin 20040815_000937_pr38.spin 20040816_000937_pr38.spin 20040814_000937_pr38.bin 20040815_000937_pr38.bin 20040816_000937_pr38.bin All_Info.txt Once this data set is assembled in your folder of choice, you can import the data into Matlab: 200408data = rpiDataReader(folderPath); The input folderPath is the full string path to the designated folder. The result 200408data is subdivided as follows: 200408data.spinBlock -- matrix of spin data for all sesssions (see rpiSpinReader for specifics) 200408data.binBlock -- matrix of bin data for all sessions (see rpiBinReader for specifics) 200408data.globals -- matrix of global data (see rpiAllInfoReader for specifics) 200408data.coordinates -- structure of coordinate records (see rpiCoordinateTransform for specifics) 200408data.times -- vector of times for twin program sessions 200408data.pngFilenames -- vector of plasmagram file names 200408data.binFilenames -- vector of bin file names 200408data.spinFilenames -- vector of spin file names ............................................................................................. Specialized data reading rpiBinReader Given a folder path, returns a block of bin data for all sessions (n total). The format of this data block is: result(n).Freq -- range of frequencies used result(n).N -- repetitions result(n).Ax -- x antenna amplitudes result(n).PhX -- x antenna phases result(n).Ay -- y antenna amplitudes result(n).PhY -- y antenna phases result(n).Az -- z antenna amplitudes result(n).PhZ -- z antenna phases result(n).Range -- span of virtual ranges rpiSpinReader Given a folder path, returns a block of spin data for all sessions (n total). The format of this data is: result(n).Header result(n).Freq -- range of frequencies used result(n).RunTime -- times of soundings result(n).NadirAngle -- nadir angle (with respect to line to center of the earth) result(n).AngleXB -- x antenna angle (with respect to B) result(n).AngleYB -- y antenna angle (with respect to B) result(n).AngleZB -- z antenna angle (with respect to B) result(n).XGSM1 -- x coordinate in GSM result(n).XGSM2 -- y coordinate GSM result(n).XGSM3 -- z coordinate in GSM The resultant histogram structure can be visualized using rpiSpinVsFreq. rpiPngReader Given a folder path, reads all the PNG plasmagram files inside. If the files are named correctly, then the proper times are also extracted. rpiAllInfoReader Given a folder path, returns a block of global data for all sessions (n total). The format of this data is: result.re -- distance to center of earth result.dpla -- distance to plasmasphere result.dmp -- distance to magnetopause result.fce -- electron gyrofrequency result.fpe -- electron plasma frequency result.mlt -- magnetic local time result.ilat -- invariant latitude result.long -- longitude result.lat -- latitude result.lshell -- L shell value result.fmp -- maximum frequency of the echo from magnetopause result.mlat -- magnetic latitude result.pfmp - maximum power flux in W/m^2 for magnetopause result.xmp -- x coordinate of magnetopause in SM result.ymp -- y coordinate of magnetopause in SM result.zmp -- z coordinate of magnetopause in SM result.xsm -- x coordinate of IMAGE in SM result.ysm -- y coordinate of IMAGE in SM result.zsm -- z coordinate of IMAGE in SM result.time -- vector of time strings formatted like 20040814_000937 rpiCoordinateTransform Given a data block created by rpiDataReader, creates coordinate transformations in MAG, GEO, and LOCAL for each twin RPI session processed (n total). result(n).MAG contains coordinates in Geomagnetic Coordinate System: sat_lat -- latitude sat_lon -- longitude sat_R -- radial distance x_ant -- directional cosine of x antenna y_ant -- directional cosine of y antenna z_ant -- directional cosine of z antenna result(n).GEO contains coordinates in Geographic Coordinate System: sat_lat -- latitude sat_lon -- longitude sat_R -- radial distance x_ant -- directional cosine of x antenna y_ant -- directional cosine of y antenna z_ant -- directional cosine of z antenna result(n).LOCAL contains coordinates in Local Coordinate System (defined by B): B_lat -- latitude of B B_lon -- longitude of B x_ant -- directional cosine of x antenna y_ant -- directional cosine of y antenna z_ant -- directional cosine of z antenna ............................................................................................. Histogram creation rpiHistRead and rpiHistSupplement Use this pair of scripts to generate histogram data for any PGH echo in general. The supplemental information is obtained by visually inspecting the plasmagrams in order and calling rpiHistSupplement multiple times as shown below. input = 'Z:\Data\2004 08\'; output = 'Z:\Data\2004 08\out\'; rpiHistogram(input, output); % 'input' contains data set % 'output' holds MAT result supplement.med_amp = 20; supplement.startF = 30; supplement.endF = 40; supplement.startR = 1.4; supplement.endR = 1.2; supplement.multiplicity = 2; supplement.resonance = 'no'; rpiHistSupplement(input, supplement); ... % median amplitude of spur % starting frequency % ending frequency % starting virtual range % ending virtual range % multiplicity of spurs % does a resonance also appear ('yes'/'no') % add supplemental info to existing MAT It is important that a supplement is made for each plasmagram, in the order that the plasmagrams appear. The default ordering is chronologically (coincidentally also alphabetical). The resultant histogram structure can be visualized using rpiHistPlot. rpiResRead Create a histogram data structure for a set of resonances. inputs = char('Z:\Data\2004 08\01-10\', 'Z:\Data\2004 08\11-20\', 'Z:\Data\2004 08\21-31\'); output = char('Z:\Data\2004 08\out\'); rpiResRead(inputs, output); A vector of data folder paths is identified by 'inputs'; a single destination folder is identified by 'output.' The script is capable of automatically recognizing resonances from the bin data, determining their amplitudes and delay times, and sorting resonance cases from non-resonance cases. The resultant histogram structure can be visualized using rpiResPlot. ............................................................................................. Extracting the electron density rpiExtractNe This script was created by Maria and allows you to accurately calculate the local electron density (and hence the local electron plasma frequency) at any point during an orbit. Values obtained this way are more accurate than the default model values provided by BinBrowser. Before using, you must edit one line rpiExtractNe.m (in package rpiNeProfile): Line 15: DEFAULTS.predPath = 'Z:\Data\Predictions\'; Find where BinBrowser is installed on your hard drive. In the BinBrowser directory you should see a folder Predictions. Replace our folder path 'Z:\Data\Predictions\' with the location of your Predictions folder. This enables the script to reference model values provided by BinBrowser. The script determines actual density values from a dynamic spectrogram taken from BinBrowser. You must save the spectrogram with the following settings: (1) Image must be 1000 x 600. (2) Set the frequency limits to 3-1000 kHz. (3) Time range must begin and end on full hour boundaries (05:00 UT not 05:30 UT). Density extractions work best when working with short segments (2-3 hours at a time). (4) Save as PNG with the filename format yyyymmdd_AA-BBxy.png, where AA is the beginning two-digit hour and BB is the ending two-digit hour. Run the script as follows: rpiExtractNe(input, output); Parameters 'input' and 'output' are string identifiers of where the spectrogram was saved and where the resultant MAT file will be saved, respectively. Choose the correct image from the pop-up list. Now it is time to pick at what times you want to calculate the density values. We recommend using the upper hybrid frequency, so just leave the default options as they appear. The upper hybrid band is seen as the green streak, usually above the model fce and fpe curves. Click the top of the upper hybrid band at the times you want to probe for density values. In the above example, the times 14:15, 14:30, and 14:45 were selected. When you are done selecting all the times you want, click 'Done' and the results are saved to the output folder. Import the saved MAT file to do further data analysis. rpiImportNe Suppose you used rpiExtractNe on a set of spectrograms and you want to combine the ffce, fpe, and Ne values. Move the MAT files into a common directory and call: neData = rpiImportNe(input); The script chronologically reads all the MAT files in 'input' and produces 'neData' with three vectors.