HMI Ring Diagrams
Pipeline Data Series Specifications

ringfits – ring diagram mode/ridge fits to power spectra

Data Series class

ring diagram fits to power spectra of (tracked) (mapped) data cubes

There are two modules for ring fitting in the Ring Diagrams pipelines, and because they fit different parameters to models of the spectra, the output data series differ. The two series classes are referred to as f and c. This specification provides descriptions of both the common and distinct features of the output data series of both classes, providing for the interoperability of downstream modules (inversions) on the data products of any of the ring fitting modules.

Data Record organization

Individual records correspond to sets of mode fits to the corresponding records of one of the pspec data series. Individual records are always expected to be referenced by three prime keys describing the spatial and temporal locations of the corresponding tracked cubes. Additional prime keys are necessary if a data series mixes fits to spectra for the same time and location, but different other parameters, such as observable, data source, region size, length of tracking interval, tracking rate, etc.

Data Segments

The data series contains at least one record segment corresponding to the sets of fit parameters with formal errors and fit quality parameters. Some of these parameters are common to both the f and c classes, others are unique to the particular fitting approach. An additional record segment for the full covariance matrices associated with the fits may be present in the data series, as well as optional record segments for the processing history.

The data segments corresponding to the sets of fit parameters including formal errors and goodness-of-fit characteristics, are stored in ASCII files (DRMS generic protocol). The format of the ASCII files produced by the different ringfit modules differ, but must have the following common elements, allowing them to be independently used by the same inversion modules:

The first line (lines are delimited by the newline character \n = 0x0A) identifies the module name and version number that was used to produce the data; it must begin with a # character.
Additional lines beginning with the # character contain optional commentary, including for example the run time parameters and input source
The last line beginning with a # character contains a series of space- and/or tab-separated strings identifying the parameters tabulated, in the order written.
Succeeding lines contain the data: mode identifications, fit parameters, formal uncertainties, and fit quality parameters as applicable, for each mode fit. Data are in space- and/or tab-separated columns.
The first 10 columns of each line of data contain, in order:
1. n — the radial (vertical) order of the mode
2. l — the equivalent spherical harmonic degree of the mode (defined as R₀ k / 2π, where R₀ is the value of the solar radius used for conversion, in Mm; this should match the value used in the tracking/mapping code used in generation of the power spectra.)
3. k — the plane-mode wavenumber, in units of Mm^-1)
4. ν (nu) — the central frequency of the mode fit, in units of μHz
5. δν (D_nu) — the formal error in the central frequency of the mode fit, in units of μHz
6. U_x (Ux) — mode fit parameter for the displacement in the direction of k_x (normally zonal), in units of m/s
7. δU_x (D_Ux) — the formal error in the U_x parameter, in units of m/s
8. U_y (Uy) — mode fit parameter for the displacement in the direction of k_y (normally meridional), in units of m/s
9. δU_y (D_Uy) — the formal error in the U_y parameter, in units of m/s
10. quality — an integer code for the overall quality of the mode fit. A value of 0 indicates that the mode fit is though to be of sufficiently high quality for use in inversions on the parameters nu, Ux, and/or Uy. A value of -1 indicates that no quality assessment has been attached to the mode fit: caveat emptor. Other values of the quality parameter may be used with meanings specific to and defined by the particular fitting procedure.
(It is suggested that a column for k be added in order to verify/specify the value of the solar radius that was used in the tracking code.)
Additional columns may contain other fit and quality parameters in any order, depending on the particular series, with the proviso that each column containing a fit parameter is immediately followed by a column containing the formal uncertainties in that parameter. Formats specific to particular series classes are described below.
Any required column for which the datum is unavailable shall contain the string "NaN" if the value type is floating point, or "-" if fixed point.
Lines containing the mode fit data may appear in any order. It is recommended, but not required, that the fits be ordered first by order and second by degree (the way the sort program would order them numerically without specification of column precedence).

If there is more than one segment defined in the series, the record segment containing the mode fit data as described above should be named modes (implying that the file in the SUMS directory will be named modes by default).

Sample file

Produced by rdfitc Version 1.2 —

# fit of hmi.rdVpspec_fd15[2096][240][240.0][+00.0][+00.0]
# ringfit_bba version 1.2
# nmin=0 nmax=10 lmin=80 lmax=3000 fmin=900 fmax=5500
# bfgsct=125 linminct=15
#n        l        k        nu    D_w0          Ux        D_Ux          Uy        D_Uy qual  l_guess bfgs           f          fm          A0        D_A0           c         D_c          w0        D_w0          B1        D_B1          B2        D_B2          A1        D_A1          A2        D_A2          A3        D_A3           p         D_p          w1        D_w1           S         D_S
 0  228.301  0.32802  1533.565  13.339 -8.2531e+01  6.7803e+01  1.1113e+02  6.7483e+01    1  231.881   22 -2.1798e+04  9.9986e-01 -5.2126e+00  6.7400e-02  7.2063e+01  1.3818e+01  1.1501e+02  1.3339e+01  9.8440e+00  2.0872e-01 -1.3807e+01  4.1404e+00  1.0522e+02  2.6873e+01 -1.2953e+02  5.4948e+02 -4.2457e+02  5.4862e+02  6.8811e+02  3.4759e+02  1.7408e+03  3.7712e+03  2.6427e-02  8.3029e-02
 0  230.510  0.33119  1543.210  12.185 -8.3975e+01  6.6025e+01  1.0986e+02  6.4676e+01    1  234.850   22 -2.2197e+04  1.0049e+00 -5.2269e+00  6.4171e-02  6.7058e+01  1.1775e+01  1.0176e+02  1.2185e+01  1.0068e+01  1.4806e-01 -8.3689e+01  8.5246e+01  1.2318e+02  3.0502e+01  2.6218e+01  5.8532e+02 -4.5772e+01  5.7876e+02  8.2180e+02  3.1953e+02  2.6025e+03  3.3939e+03  8.3289e-03  7.6995e-02
 0  230.942  0.33181  1552.855  11.082 -2.1600e+01  6.3849e+01  1.1929e+02  6.3341e+01    1  237.839    0 -2.2667e+04  9.9101e-01 -5.2192e+00  6.5649e-02  6.4889e+01  1.2442e+01  9.3936e+01  1.1082e+01  1.0181e+01  1.2036e-01 -2.2594e+02  1.5609e+02  1.6140e+02  3.2212e+01  3.1740e+01  5.9367e+02 -6.1463e+01  5.8926e+02  8.9147e+02  3.4644e+02 -6.9256e+02  2.7879e+03 -6.3443e-02  6.7427e-02
...
 0 2396.960  3.44391  4793.596  18.023 -7.6053e+01  5.4232e+00  6.3396e+01  5.1007e+00    1 2421.512   22 -2.6478e+06  1.0103e+00 -7.1509e+00  1.5775e-02  7.0042e+01  1.1882e+01  5.4385e+02  1.8023e+01 -1.0535e+01  1.0000e+00 -2.7428e+00  1.0000e+00 -3.0052e+01  4.7239e-01 -1.8287e+03  4.2989e+01  6.9708e+01  4.5121e+01  4.7592e+02  2.2310e+02  3.9974e+03  5.9827e+02  6.7712e-02  5.2016e-02
 1  176.629  0.25378  1900.077   2.888  4.6026e+01  4.2271e+01 -5.1153e+01  4.1736e+01    1  182.326    0 -1.5423e+04  1.0300e+00 -3.7897e+00  5.8009e-02  2.9997e+02  1.7499e+01  4.5355e+01  2.8877e+00  9.5178e+00  2.8160e-01  5.4723e+00  6.3191e+00  2.6323e+02  2.9375e+01  1.3284e+03  5.1230e+02 -2.7094e+02  5.1681e+02 -1.9475e+02  1.1038e+02 -4.4916e+03  5.2518e+02 -1.3076e-01  1.9328e-02
...
 9  140.917  0.20247  4128.086   2.357 -3.9339e+00  4.3414e+01  5.1480e+02  6.0398e+01    1  135.026    0 -1.1927e+03  9.3630e-01 -2.8038e+00  8.8373e-01  6.9590e+02  2.3275e+01  2.8402e+00  2.3568e+00 -4.5622e+02  2.4176e+02  1.6491e+01  5.2648e-02 -5.9895e+02  7.6297e+02  1.2848e+04  7.8367e+03 -3.8136e+02  6.7505e+03 -1.0636e+02  6.7756e+01  1.0672e+03  2.5961e+03 -1.7970e-02  8.4098e-02
10  106.638  0.15322  4002.701   2.116  6.2663e-04  4.3731e-01 -1.3633e-03  4.3773e-01    1  104.325   44 -1.5756e+03  8.9893e-01 -3.6841e+00  1.6816e+02  6.9931e+02  7.7107e+01  1.0009e+02  2.1159e+00  1.0913e+01  3.0819e-02  9.4036e+00  1.1390e+02 -1.3801e-01  2.3106e+00 -1.1019e-04  1.0000e+00  1.1597e-03  1.0002e+00 -1.7018e+00  2.5287e+01 -3.3089e-03  1.0012e+00 -1.9996e-02  1.1573e-04

Prime Keywords

In general, it is recommended that there be at least three prime keys in data series in this class, in order to uniquely specify the time and location of the analyzed region.

	LonHG	 float	"Longitude of tracked region center"
	LatHG	 float	"Latitude of tracked region center"
	MidTime	 time	"Midpoint of tracking interval"
	CarrRot	 int	"Carrington rotation at MidTime"
	CMLon	 float	"Longitude of central meridian at MidTime"

The combination of CarrRot plus CMLon is of course redundant with MidTime if the orbit of the observing platform is known. CMLon may be useful as a prime key for selecting meridian strips. CarrTime may be used as a single key substitute for CarrRot and CMLon, but is discouraged, since there is no support for forming dataset queries based on strings of that form.

Additional Keywords

The following keys may occur in data series in this class, and if present will be set by rdfitc:

	Module	 string	"Creating module (and version)"
	Source	 string	"Input data source"
	BLD_VERS string	"JSOC library build version"
	Created	 string	"Record creation time"

The following keys may occur in data series in this class, and if present will be propagated from the input series by rdfitc:

	CarrTime string "Carrington rotation and central longitude at MidTime"
	CarrRot	 int    "Carrington rotation at MidTime"
	CMLon    float  "Longitude of central meridian at MidTime"
	LonHG	 float  "Longitude of region center"
	LatHG	 float  "Latitude of region center"
	LonCM    float  "CM (Stonyhurst) Longitude of region center at MidTime"
	MidTime  time   "Midpoint of analysis interval"
	Duration	see ds_track
	Cadence		see ds_track
	LonSpan		see ds_track
	T_START		see ds_track
	T_STOP		see ds_track
	Coverage	see ds_track
	Size		see ds_track
	Width		see ds_track
	Height		see ds_track
	ZonalTrk	see ds_track
	ZonalVel	see ds_track
	MeridTrk	see ds_track
	MeridVel	see ds_track
	MapProj		see ds_track
	MapScale	see ds_track
	MapPA		see ds_track
	RSunRef		see ds_track
	PosAng		see ds_track
	MAI		see ds_track
	APODIZNG	see ds_pspec
	APOD_MIN	see ds_pspec
	APOD_MAX	see ds_pspec
	Apode_f		see ds_pspec
	Apode_k_min	see ds_pspec
	Apode_k_max	see ds_pspec

The value for CarrTime will be constructed from those for CarrRot and CMLon, and vice-versa, if necessary.

Aditional class segment specifications

RingFits-c

In the modes segment, columns 11–36 contain the following data:

l_guess – the original guess value for spherical harmonic degree of the mode
bfgs – the flag value returned by the BFGS function
f – the log likelihood function of the model fit
fm – the merit function of the fit
A0 – log of the mode amplitude
δA₀ (D_A0) – the formal error in A0
c – the amplitude of the power-law dependence of frequency on k
δc (D_c) – the formal error in c
w0 – mean mode width, in units of μHz
δw₀ (D_w0) – the formal error in w0
B1 – the background amplitude for the k^-3 dependence
δB₁ (D_B1) – the formal error in B1
B2 – the background amplitude for the k^-4 dependence
δB₂ (D_B2) – the formal error in B2
A1 – amplitude of linear dependence of power on k
δA₁ (D_A1) – the formal error in A1
A2 – parameter measuring azimuthal variation of power in k
δA₂ (D_A2) – the formal error in A2
A3 – parameter measuring azimuthal variation of power in k
δA₃ (D_A3) – the formal error in A3
p – the power-law exponent of the dependence of frequency on k
δc (D_p) – the formal error in p
w1 – linear dependence of mode width on k, in units of m/s (?)
δw₁ (D_w1) – the formal error in w1
S – the asymmetry parameter
δS (D_S) – the formal error in S

RingFits-f

In the modes segment, columns 11–20 contain the following data:

f-fg – difference of frequency from guess, in units of μHz
f – the log likelihood function of the model fit
χ² (chi2) – reduced χ² of the fit
? – TBD convergence flag
A0 – log of the mode amplitude
δA₀ (D_A0) – the formal error in A0
B0 – log of the background amplitude
δB₀ (D_B0) – the formal error in B0
w – mean mode width, in units of μHz
δw₀ (D_w) – the formal error in w

HMI Ring Diagrams

22 Nov 2021, 15:27-0800