6 Functions

The following examples show usage and output from a number of the function plugins available within the UDFAnalysis package.

6.1 Bin Function


PIC

Figure 18: Plots of binned data


Figure 18 shows a set of 4 plots of Probability Distribution Function (PDF). The probability distributions were computed using the Bin Function which bins variables within a specified interval. Both the interval and the number of bins within the interval are selectable. This example shows binning of 4 different variables, the x component of the magnetic field, the plasma electron density, the x component of the electron bulk velocity in GSE coordinates and the component of the electron bulk velocity parallel to the magnetic field vector. The time range over which the data was accumulated is shown in the label above the plots.

The Bin Function Menu shows four separate bin definitions. The Input variables were read in from individual data sources. The BinX variables are the returned bin centers and the BinY variables are the number of events in each bin. Min and Max define the extent of the interval over which the data is being binned and Bins is the number of bins to divide the interval into. These vary with the expected range and fineness of the data. All of the defines have Norm set to YES. This normalizes the PDF to run from 0 to 1 which is useful if you are plotting many PDF’s which share a common Y axis.

In the plots definitions autoscaling was turned off for all axes since the ranges covered by each plot are known from the binning definitions.

You should take some time to look at the VARIABLE definition menu and submenus under it as they show how the various data sets are being imported and how the data variables themselves are defined. Note that because the some of the moment data is to be returned in magnetic coordinates, the magnetic field data but be input before the moment data.

One think you will note if you run this menu is that it takes a substantial amount of time to read in moment data. This is caused by the large number of coordinate transformations which are being executed as the data rotated from the spacecraft frame into a GSE based coordinated and a subset of that data is further rotated in a magnetic field based coordinate system. Addition of some C backing code in future releases my mitigate this somewhat.

6.2 Filter Function


PIC

Figure 19: Plots of filtered data


Figure 19 shows a set of 2 plots illustrating results of the Filter Function. The filter function returns data within, above and below a specified frequency band. The band is often set to have a zero width in which case only data above and below the selected frequency is returned. In this mode the function can be used to compute the moving mean of a variable and the variation about the mean which is what is done in this example.

The Filter Setup menu under the Function menu shows the option settings used in generating the filters. The input being filtered is the y component of the magnetic field. Because the upper and lower band edges are set to the same value the function will return can only the filtered data below and above 0.005 Hz. Return is set to LH meaning that both the data in the Low and High frequency ranges are returned. Since two variables are being returned the output variable (fBy) is a variable of order 2. The low frequency component is returned in fBy0 and the high frequency component in fBy1. The smoothing order is left at the default value of 2.

The upper plot in the Figure 19 contains the unfiltered input variable By (black) and the filtered low frequency component of the data Red. The lower plot contains the high frequency component of the data.

6.3 Vector Function


PIC

Figure 20: Plots of the results of vector operations


Figure 20 shows a set of 4 plots of output generated by the Vector Function. The vector function provides a number of operations specific to vectors or order 3 variables. This example uses both magnetic field data and plasma moment data to illustrate the usage of four vector operators. The four operations shown in the Vector Setup menu which is a submenu under the FUNCTIONS menu. In the first defined operation the magnetic field vector which is input in Cartesian coordinates is changed to spherical coordinates and output in the vector variable BP. The components of this vector are plotted in the upper three panels in the example output. Remember that the polar angle is returned in the range 0 180. In the next operation the input magnetic field is converted to a unit vector which is stored in uB. This is not output but is used in the next operation which takes the cross product of the plasma bulk velocity with the unit magnetic field vector. The cross product is output in the variable VxB. The last operation computes the magnitude of the cross product which is stored in VxBM. This the plasma velocity perpendicular to the magnetic field.and is output in the lower panel in Figure 20. Of the operators used only the cross product operator requires the input of two vectors. The other operators work on a single vector.

6.4 Fit, Set Value and Variable Map Functions


PIC

Figure 21: Plots of the results of fit function


As its name implies, the fit function fits a set of data to a user specified model function. Use of the fit function often requires previous calls to the VMap function and sometimes to the SetV function both of which will be introduced in this example. Figure 21 shows a set of 2 plots which include fits to data generated by the Fit Function.

There are four separate fits defined in the fit menu, all of which have a dimension of 1, that is the fits are of the form y = f(x). The first two fits in the menu text window a linear fit algorithm to fit the same input data set to two different polynomial functions. From the number of coefficients, the first definition fits the input data to straight line and the second to a function of the form A0 + A1x + A2x2. The data being fit is a set of Bx and By values. The variables holding the data have been mapped into the second order variable bFit using the VMAP Function.

The next two fit definitions use a non-linear fitting algorithm and also fit a common set of data. The first non-linear fit is to a single Gaussian function and the second to a pair of Gaussians. The input data is the Probability Distribution Function of the x component of a set of magnetic field data which was shown in the Binning example in section 6.1.

Non-linear fits require an initial guess of the fit coefficients, three in the case of a single Gaussian fit and double that for a two Gaussian fit. The guesses are held in the variables gF and gF2. Both of these variables are created using the SETV Function setup menu. Since you can only assign a maximum of 4 values per line it takes two lines to completely specify the 6 values in gF2.

The Plot Definition Menu shows how to plot the fits. The fit output variable specified in the Fit Setup Menu is entered as the X Variable in the plot with no other variables specified. All of the information needed to reconstruct the fit is contained in output variable generated by the fit function.

6.5 Statistics Function


PIC

Figure 22: Plot showing statistics data


Figure 22 shows output generated by the Statistics Function. The statistics function computes and returns a number of statistical parameters for an scalar variable. These are not plottable quantities but as seen in the figure can be added to the plots as annotation. The input data in this case is a set of Bx magnetic field values and what is plotted is the Probability Distribution Function of the values as computed using the BIN function.

The Plot Label illustrates how to output the returned statistics information. The statistic definitions and values were output as separate columns of labels which allowed the alignment seen in the figure.

6.6 Define Grid and Grid Fill Functions


PIC

Figure 23: Plot showing data gridded at different time resolutions


The Define Grid function provides a mechanism to define a grid information array which can then be applied to arbitrary data sets to put them in a regular grid. The gridding of the data is done through the Grid Fill Function. The output of the Define Grid function is not plottable but that of the Grid Fill is. Figure 23 shows output generated by the Grid Fill Function.

The input data to the example is a set of ungridded Bx values. Both the data and the start and stop times are read in and saved. The latter is needed in the Grid Fill function. Then two nearly identical time based grids are defined. Each grid definition occupies two lines in the DefGrid setup menu text window. Leaving both the X Min and X Max options blank causes the X extent of the grid to match the X extent of the system-wide time grid. The first grid definition is stored in gIA and sets the grid cell width to be 4 seconds. The second grid definition is stored in gIB and sets the grid cell width to be 120 seconds.

Application of the grid definitions is made in the Grid Fill setup menu. The input data is placed into two grids: BxA which was defined according to the options set in gIA and BxB which was defined according to the options set in gIB. Both of these data sets are then plotted in the example output plot, the lower resolution grid in red and the higher resolution grid in black.

6.7 Dynamic-PS Function


PIC

Figure 24: Plot showing dynamic power spectra


The dynamic-ps function creates a dynamic power spectra from any scalar variable stored in a time-based grid. The input is often data which has been passed through the Filter Function either to remove the low frequency component in the data or to restrict the frequency range in the data prior to creating the power spectra.

Figure 24 shows output generated by the Dynamic-PS Function. The input data is a set of high resolution FGM magnetic field data obtained from the Cluster Active Archive. All of the dynamic spectra involve the Y component of the field only. There are three sets of Dynamic Power Spectra shown in the figure: one derived from the raw input and two from frequency filtered components of the data. The Time Menu has the cell width of the time grid set 0.015s which is about the time resolution of the high resolution magnetic field data at this time.

The data was filtered using the Filter Function. The first definition in the setup menu filters the data into two components, one below 0.3 Hz and one above 0.3 Hz. Only the upper component is returned as a named variable. The second definition filters the data into three components, one below 0.3 Hz. one between 0.3 Hz and 1.0 Hz, and one above 0.3 Hz. Only the band and upper components are returned as named variables.

The dynamic power spectra setup menu contains four definitions of the dynamic power spectra of which the middle two definitions are coupled, that is their results are returned in the same variable combination. The returned variables are of order 4. The first two variable components hold the start and stop time of the window in which the individual power spectra are computed, the third component contains the frequencies at which the power is returned, and the last component contains the power.

The dynamic power spectra are spectrogram type plots and require an X (in this case the time), a Y (the frequency steps) and an I (the power) input. This is seen in the PLOT DEFINITION menu. The upper plot in the output is the dynamic power spectra derived from the raw data, the next from the filtered data > 0.3 Hz, and the last from the combined 0.3 to 1.0 Hz and > 1.0 Hz components. The first two plots have the input to the dynamic power spectra function overplotted while the last plot has just the signal within the band overplotted. Note: When plotting a line plot over a spectrogram type plot the line plot must be specified after the spectrogram plot in the plot definition list.

The gaps at the end of the dynamic spectra plot are due to the finite window width in which the spectra are computed. Gaps beginning and end of the line plots of the filtered data are due to the finite with of the filters used in the processing of the data.

6.8 Collapse Function


PIC

Figure 25: Collapse Function Example


The Collapse Function allows a 2D grid to be collapsed down to a 1D grid. The collapse direction and range in the input grid is selectable. Figure 25 shows output generated by the Collapse Function overlayed on spectrogram plot set up in the example in section 5.5.

Collapsing over the spectrogram requires two subsequent function calls. Because the input data is not gridded, a grid must be defined and the data gridded prior to the collapse. The gridding of the data in the spectrogram plot is done in the plotting routine and is not available as a variable that can be used. The grid is time based, runs over the plot time, and has 4 second resolution. There are more grids in Y than energy channels so that when the data is gridded it needs to be filled in the Y direction to remove any gaps. The collapse is done in the Y direction in the range 50 to 300 eV. The collapsed grid is output in the variable NoSw which can be plotted as 1D time based variable.