title: MATLAB: unwrap function
body: <p>I'm in a discussion with someone from Mathworks re: the <a href="http://www.mathworks.com/access/helpdesk/help/techdoc/ref/unwrap.html" rel="noreferrer"><code>unwrap</code></a> function which has a "bug" in it for jump tolerances other than &pi;, and would like to get some other perspectives:</p>
  
  <blockquote>
    <p><strong>Description</strong></p>
    
    <p><code>Q = unwrap(P)</code> corrects the radian phase angles in a vector P by adding multiples of      &plusmn;2&pi; when absolute jumps between consecutive elements of P are greater than or equal to the default jump tolerance of &pi; radians. If P is a matrix, unwrap operates columnwise. If P is a multidimensional array, unwrap operates on the first nonsingleton dimension.</p>
    
    <p><code>Q = unwrap(P,tol)</code>uses a jump tolerance tol instead of the default value, &pi;.</p>
  </blockquote>
  
  <p>There are two possible interpretations of the documentation:</p>
  
  <ol>
  <li><p><code>Q = unwrap(P,tol)</code> corrects the radian phase angles in a vector P by adding multiples of  &plusmn;2&pi; when absolute jumps between consecutive elements of P are greater than or equal to tol radians. If P is a matrix, unwrap operates columnwise. If P is a multidimensional array, unwrap operates on the first nonsingleton dimension.</p>
  
  <p>Example:</p>
  
  <pre><code>&gt;&gt; x = mod(0:20:200,100); unwrap(x, 50)
  ans =
      0 20.0000 40.0000 60.0000 80.0000 81.6814 101.6814 121.6814 141.6814 161.6814 163.3628
  </code></pre></li>
  <li><p><code>Q = unwrap(P,tol)</code> corrects the elements in a vector P by adding multiples of  &plusmn;2*tol when absolute jumps between consecutive elements of P are greater than or equal to tol. If P is a matrix, unwrap operates columnwise. If P is a multidimensional array, unwrap operates on the first nonsingleton dimension.</p>
  
  <p>Example:</p>
  
  <pre><code>&gt;&gt; x = mod(0:20:200,100); unwrap(x, 50)  
  ans =  
      0    20    40    60    80   100   120   140   160   180   200
  </code></pre></li>
  </ol>
  
  <p>The actual behavior of <code>unwrap()</code> in MATLAB (at least up to R2010a) is #1. My interpretation of <code>unwrap()</code> is that it's supposed to be #2, and therefore there is a bug in the behavior. If <code>unwrap()</code>'s behavior matched #2, then unwrap could be used as an inverse for mod for slowly-varying inputs, i.e. <code>unwrap(mod(x,T),T/2) = x</code> for vectors x where successive elements vary by less than tol=T/2. </p>
  
  <p>Note that this 2nd interpretation is more general than angles, and can unwrap anything with a wraparound period T. (whether a default of T=2&pi; for radians, 360 for degrees, 256 for 8-bit numbers, 65536 for 16-bit numbers, etc.)</p>
  
  <p>So my question is:</p>
  
  <p><strong>Are there possible uses for behavior #1? Which interpretation makes more sense?</strong></p>