doc/concatenating.html

   1
   2 <html>
   3  <head>
   4   <title>Cat the Planet!</title>
   5  </head>
   6  <body>
   7   <div><a href="./index.html">back to doc index</a></div>
   8   <div><b>cat</b>: Horizontally concatenate. Vectors are treated as
   9    column matrices like they are on the "create and edit" page. </div>
  10   <div><b>vcat</b>: Vertical (or vector-wise) concatenation.</div>
  11
  12   <h3>Examples</h3>
  13   <p>The following examples utilize the "store" function to build all
  14   variables from the result of different concatenations.</p>
  15
  16   <table width="100%" border="1"
  17    style="text-align: center; font-family:monospace">
  18    <tr>
  19     <td width="25%"><b>Input</b></td>
  20     <td width="15%"><b>Output</b></td>
  21     <td><b>Explanation</b></td>
  22    </tr>
  23    <tr>
  24     <td>(store "A" (cat 3 5 7))</td>
  25     <td>[3 5 7]</td>
  26     <td>Join the numbers to make a row matrix.</td>
  27    </tr>
  28    <tr>
  29     <td>(store "u" (vcat 1 2 3))</td>
  30     <td>(1, 2, 3)</td>
  31     <td>This time, the result is a vector. Stored as <b>u</b></td>
  32    </tr>
  33    <tr>
  34     <td>(cat u A)</td>
  35     <td>[1 3 5 7]<br/>[2 0 0 0]<br/>[3 0 0 0]</td>
  36     <td>The column vector <b>u</b> joins with <b>A</b> by allocating the
  37      needed rows of zeros.</td>
  38    </tr>
  39    <tr>
  40     <td>(cat A u)</td>
  41     <td>[3 5 7 1]<br/>[0 0 0 2]<br/>[0 0 0 3]</td>
  42     <td><b>u</b> joined with <b>A</b> from the other side.</td>
  43    </tr>
  44    <tr>
  45     <td>(vcat u A)</td>
  46     <td>[1 2 3]<br/>[3 5 7]</td>
  47     <td>Vertical concatenation using the transpose of the column vector <b>u</b>.<br/>
  48      vcat will always transpose vectors to be horizontal when called with a matrix.<br/>
  49      I figure this is the "best" behavior.
  50     </td>
  51    </tr>
  52    <tr>
  53     <td>(vcat (vcat 3 4 5) (vcat 6 7 8 9))</td>
  54     <td>(3, 4, 5, 6, 7, 8, 9)</td>
  55     <td>Create 2 vectors: (3, 4, 5) and (6, 7, 8, 9)<br/>
  56      and through vcat, join them.</td>
  57    </tr>
  58    <tr>
  59     <td>(cat (vcat 3 4 5) (vcat 6 7 8 9))</td>
  60     <td>[3 6]<br/>[4 7]<br/>[5 8]<br/>[0 9]</td>
  61     <td>Using cat instead gives the two vectors stacked as
  62      columns in a matrix. Note the extra zero given to the left
  63      column.</td>
  64    </tr>
  65    <tr>
  66     <td>(store "B" (vcat (cat 1 2) (cat 3 4)))</td>
  67     <td>[1 2]<br/>[3 4]</td>
  68     <td>If you want to make a matrix by rows via cat, use this
  69      format. Of course, here we also store the result as matrix
  70      <b>B</b>.</td>
  71    </tr>
  72    <tr>
  73     <td align="left" style="font-family:default" colspan=3>
  74      <h4>Of course, it only follows that matrices can be
  75       joined in the same way...</h4>
  76     </td>
  77    </tr>
  78    <tr>
  79     <td>(cat A B)</td>
  80     <td>[3 5 7 1 2]<br/>[0 0 0 3 4]</td>
  81     <td><b>A</b> on the left, <b>B</b> on the right.</td>
  82    </tr>
  83    <tr>
  84     <td>(vcat A B)</td>
  85     <td>[3 5 7]<br/>[1 2 0]<br/>[3 4 0]</td>
  86     <td><b>A</b> on top, <b>B</b> below.</td>
  87    </tr>
  88    <tr>
  89     <td align="left" style="font-family:default" colspan=3>
  90      <h4>Lineal interprets some interesting
  91       number/matrix concatenation as well...</h4>
  92     </td>
  93    </tr>
  94    <tr>
  95     <td>(cat 9 B)</td>
  96     <td>[9 1 2]<br/>[9 3 4]</td>
  97     <td>Add a column of 9's onto the left of <b>B</b>.</td>
  98    </tr>
  99    <tr>
 100     <td>(vcat B 9)</td>
 101     <td>[1 2]<br/>[3 4]<br/>[9 9]</td>
 102     <td>Add a row of 9's onto the bottom of <b>B</b>.</td>
 103    </tr>
 104    <tr>
 105     <td>(store "S" (cat 4 (vcat 4 5)))</td>
 106     <td>[4 4]<br/>[4 5]</td>
 107     <td>Make a symmetric matrix <b>S</b>.</td>
 108    </tr>
 109    <tr>
 110     <td>(store "S" (cat 3 (vcat 3 S)))</td>
 111     <td>[3 3 3]<br/>[3 4 4]<br/>[3 4 5]</td>
 112     <td>Build on a row of 3's atop <b>S</b> then a column of 3's onto
 113      its left side.</td>
 114    </tr>
 115    <tr>
 116     <td>(store "S" (cat 1 (vcat 1 (cat 2 (vcat 2 S)))))</td>
 117     <td>[1 1 1 1 1]<br/>[1 2 2 2 2]<br/>[1 2 3 3 3]<br/>[1 2 3 4 4]<br/>[1 2 3 4 5]</td>
 118     <td>Finish off the symmetric pattern. Re-store it as <b>S</b>.</td>
 119    </tr>
 120    <tr>
 121     <td align="left" style="font-family:default" colspan=3>
 122      <h4>This concept holds with vectors too! But results
 123       may be surprising.<br/>
 124       Which is why vcat = vertical and cat = horizontal.</h4>
 125     </td>
 126    </tr>
 127    <tr>
 128     <td>(cat 7 u)</td>
 129     <td>[7 1]<br/>[7 2]<br/>[7 3]</td>
 130     <td><b>u</b> is treated like a matrix.
 131      If you wanted (7, 1, 2, 3), use (vcat 7 u).</td>
 132    </tr>
 133    <tr>
 134     <td align="left" style="font-family:default" colspan=3>
 135      <h4>And in some situations, results may be very surprising...</h4>
 136     </td>
 137    </tr>
 138    <tr>
 139     <td>(cat 7 u 8)</td>
 140     <td>[7 1 8]<br/>[7 2 8]<br/>[7 3 8]</td>
 141     <td>OK, so that's not too surprising since Lineal has
 142      a lot of functions which take an arbitrary number of terms.</td>
 143    </tr>
 144    <tr>
 145     <td>(cat 6 7 u 8)</td>
 146     <td>[6 7 1 8]<br/>[6 7 2 8]<br/>[6 7 3 8]</td>
 147     <td>Again, nothing too out of the ordinary.</td>
 148    </tr>
 149    <tr>
 150     <td>(cat 7 u 8 9)</td>
 151     <td>[7 1 8 9]<br/>[7 2 0 0]<br/>[7 3 0 0]</td>
 152     <td>A little strange. This happens because the cat and vcat
 153      functions build from right to left.<br/>
 154      Here, it is equivalent to calling (cat 7 (cat u (cat 8 9))).<br/>
 155      (cat 8 9) returns a row matrix [8 9] and so on.
 156     </td>
 157    </tr>
 158   </table>
 159  </body>
 160 </html>
 161