Additions to Section 13.3 of WSJT-X User Guide: "Phase Equalkization".

git-svn-id: svn+ssh://svn.code.sf.net/p/wsjt/wsjt/branches/wsjtx@8124 ab8295b8-cf94-4d9e-aec4-7959e3be5d79

doc/common/links.adoc

@@ -77,6 +77,7 @@ d). Edit lines as needed. Keeping them in alphabetic order help see dupes.
 :launchpadki7mt: https://launchpad.net/~ki7mt[KI7MT PPA's]
 :log4om: http://www.log4om.com[Log4OM]
 :lunarEchoes: http://physics.princeton.edu/pulsar/K1JT/LunarEchoes_QEX.pdf[QEX]
+:msk144: http://physics.princeton.edu/pulsar/k1jt/MSK144_Protocol_QEX.pdf[QEX]
 :msys_url: http://sourceforge.net/projects/mingwbuilds/files/external-binary-packages/[MSYS Download]
 :ntpsetup: http://www.satsignal.eu/ntp/setup.html[Network Time Protocol Setup]
 :osx_instructions: http://physics.princeton.edu/pulsar/K1JT/OSX_Readme[Mac OS X Install Instructions]

doc/user_guide/en/measurement_tools.adoc

@@ -72,60 +72,61 @@ slow modes, select *Measure reference spectrum* from the *Tools* menu.
 Wait for about a minute and then hit the *Stop* button.  A file named
 `refspec.dat` will appear in your log directory.  
 
- [ ... TBD ... ]
+ [ ... more to come ... ]
 
-=== Phase Response and Equalization
+=== Phase Equalization
 
 *Measure phase response* under the *Tools* menu is for advanced MSK144
 users. Phase equalization is used to compensate for group-delay
-variation across the passband of receiver filters. Careful application
-of this facility can reduce intersymbol interference, resulting in
-improved decoding sensitivity.  If you use a software-defined receiver
-with linear-phase filters there is no need to apply phase
-equalization.
+variation across your receiver passband. Careful application of this
+facility can reduce intersymbol interference, resulting in improved
+decoding sensitivity.  If you use a software-defined receiver with
+linear-phase filters there is no need to apply phase equalization.
 
-After a received frame is decoded *Measure phase response* generates
-an undistorted waveform whose Fourier transform is used as a
-frequency-dependent phase reference to compare with the phase of the
-received frame's Fourier coefficients.  Phase differences between the
-reference and the received waveform include contributions from the
-originating station's transmit filter, the propagation channel, and
-filters in the receiver. If the received frame originates from a
-station known to transmit signals having little phase distortion (say,
-a station known to use a properly adjusted
-software-defined-transceiver) and if the received signal is relatively
-free from multipath distortion so that the channel phase is close to
-linear, the measured phase differences will be representative of the
-local receiver's phase response.
+After a frame of received data has been decoded, *Measure phase
+response* generates an undistorted audio waveform equal to the one
+generated by the transmitting station.  Its Fourier transform is then
+used as a frequency-dependent phase reference to compare with the
+phase of the received frame's Fourier coefficients.  Phase differences
+between the reference spectrum and received spectrum will include
+contributions from the originating station's transmit filter, the
+propagation channel, and filters in the receiver. If the received
+frame originates from a station known to transmit signals having
+little phase distortion (say, a station known to use a properly
+adjusted software-defined-transceiver) and if the received signal is
+relatively free from multipath distortion so that the channel phase is
+close to linear, the measured phase differences will be representative
+of the local receiver's phase response.
 
 Complete the following steps to generate a phase equalization curve:
 
 - Record a number of wav files that contain decodable signals from
 your chosen reference station. Best results will be obtained when the
-SNR of the reference signals is at least 9 dB.
+aignal-to-noise ratio of the reference signals is 10 dB or greater.
 
 - Enter the callsign of the reference station in the DX Call box.
 
-- Select *Measure phase response* from the *Tools* menu, and process
-the wav files. The mode character will change from `&` to `^` while
-_WSJT-X_ is measuring the phase response and it will change back to
-`&` after the measurement is completed. The program needs to average a
-number of high-SNR frames to accurately estimate the phase, so it may
-be necessary to process several wav files. The measurement can be
-aborted at any time by selecting *Measure phase response* again to
-toggle the phase measurement off.
+- Select *Measure phase response* from the *Tools* menu, and open each
+of the wav files in turn. The mode character on decoded text lines
+will change from `&` to `^` while _WSJT-X_ is measuring the phase
+response, and it will change back to `&`  after the measurement is
+completed. The program needs to average a number of high-SNR frames to
+accurately estimate the phase, so it may be necessary to process
+several wav files. The measurement can be aborted at any time by
+selecting *Measure phase response* again to toggle the phase
+measurement off.
 
 +
 
 When the measurement is complete _WSJT-X_ will save the measured
 phase response in the *Log directory*, in a file with suffix
 ".pcoeff". The filename will contain the callsign of the reference
-station and a timestamp.  For example: K0TPP_170923_112027.pcoeff
+station and a timestamp, for example `K0TPP_170923_112027.pcoeff`.
 
 - Select *Equalization tools ...* under the *Tools* menu and click the
 *Phase ...* button to view the contents of the *Log directory*. Select
 the desired pcoeff file. The measured phase values will be plotted as
-discrete circles along with a fitted curve labeled "Proposed". This is
+filled circles along with a fitted red curve labeled "Proposed". This is
 the proposed phase equalization curve. It's a good idea to repeat the
 phase measurement several times, using different wav files for each
 measurement, to ensure that your measurements are repeatable.
@@ -135,55 +136,59 @@ to save the proposed response. The red curve will be replaced with a
 light green curve labeled "Current" to indicate that the phase
 equalization curve is now being applied to the received data. Another
 curve labeled "Group Delay" will appear. The "Group Delay" curve shows
-the group delay variation across the passband, in ms. Push the
+the group delay variation across the passband, in ms. Click the
 *Discard*  button to remove the captured data, leaving only the applied
 phase equalization curve and corresponding group delay curve.
 
 - To revert to no phase equalization, push the *Restore Defaults*
 button followed by the *Apply* button.
 
-The three numbers that are printed at the end of each MSK144 decode line
-can be used to assess the improvement provided by equalization. These numbers
-`N` `H` `E` are:
- `N` - Number of frames averaged,
- `H` - Number of bit errors corrected,
- `E` - Size of MSK eye diagram opening. 
+The three numbers printed at the end of each MSK144 decode line can be
+used to assess the improvement provided by equalization. These numbers
+are: `N` = Number of frames averaged, `H` = Number of hard bit errors
+corrected, `E` = Size of MSK eye diagram opening.
 
 Here is a decode of K0TPP obtained while *Measure phase response* was measuring
 the phase response:
 
   103900  17  6.5 1493 ^  WA8CLT K0TPP +07       1  0  1.2
 
-The "^" symbol indicates that a phase measurement is being accumulated. The 
-three numbers at the end of the line indicate that one frame was
-used to obtain the decode, there were no bit errors, and the 
-eye-opening was 1.2. Here's how the same decode looks after phase equalization:
+The "^" symbol indicates that a phase measurement is being accumulated
+but is not yet finished. The three numbers at the end of the line
+indicate that one frame was used to obtain the decode, there were no
+hard bit errors, and the eye-opening was 1.2 on a -2 to +2
+scale.  Here's how the same decode looks after phase equalization:
 
   103900  17  6.5 1493 &  WA8CLT K0TPP +07       1  0  1.6
 
-In this case, equalization has increased the eye opening from 1.2 to 1.6.
-Larger eye openings are associated with reduced likelihood of bit errors and
-higher likelihood that a frame will be successfully decoded. 
-In this case, the larger eye-opening 
-tells us that phase equalization was successful, but it is important to note
-that this test does not tell us whether the applied phase equalization curve
-is going to improve decoding of signals other than those from the reference 
-station, K0TPP! 
+In this case, equalization has increased the eye opening from 1.2 to
+1.6.  Larger positive eye openings are associated with reduced
+likelihood of bit errors and higher likelihood that a frame will be
+successfully decoded.  In this case, the larger eye-opening tells us
+that phase equalization was successful, but it is important to note
+that this test does not by itself tell us whether the applied phase
+equalization curve is going to improve decoding of signals other than
+those from the reference station, K0TPP.
 
-We strongly advise you to carry out before and after comparisons 
-using a large number of saved wav files with signals from many different 
-stations to decide whether or not the equalization curve improves decoding for most 
-signals. When doing before and after comparisons, keep in mind that 
-equalization may cause _WSJT-X_ to successfully decode a frame 
-that was not decoded before equalization was applied.  
-For this reason, be sure that the time "T" of
-the two decodes are the same before comparing their end-of-line quality numbers.
+It's a good idea to carry out before and after comparisons using a
+large number of saved wav files with signals from many different
+stations, to help decide whether your equalization curve improves
+decoding for most signals. When doing such comparisons, keep in mind
+that equalization may cause _WSJT-X_ to successfully decode a frame
+that was not decoded before equalization was applied.  For this
+reason, be sure that the time "T" of the two decodes are the same
+before comparing their end-of-line quality numbers.
 
-When comparing before and after decodes having the same "T", keep in mind
-that a smaller first number means that decoding has improved, even if the 
-second and third numbers appear to be "worse". For example, suppose that the quality
-numbers before equalization are "2 0  0.2" and after equalization 
-"1 5 -0.5". These numbers show improved decoding because 
-the decode was obtained using only a single
-frame after equalization whereas a 2-frame average was needed before equalization.
+When comparing before and after decodes having the same "T", keep in
+mind that a smaller first number means that decoding has improved,
+even if the second and third numbers appear to be "worse". For
+example, suppose that the end-of-line quality numbers before
+equalization are `2 0 0.2` and after equalization `1 5 -0.5`. These
+numbers show improved decoding because the decode was obtained using
+only a single frame after equalization whereas a 2-frame average was
+needed before equalization.  This implies that shorter and/or weaker
+pings could be decodable.
 
+NOTE: Further details on phase equalization and examples of fitted
+phase curves and eye diagrams can be found in the article on MSK144 by
+K9AN and K1JT published in {msk144}.