pv.Nest.html 19 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808
  1. <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  2. "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
  3. <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
  4. <head>
  5. <meta http-equiv="content-type" content="text/html; charset=utf-8" />
  6. <meta name="generator" content="JsDoc Toolkit" />
  7. <title>JsDoc Reference - pv.Nest</title>
  8. <style type="text/css">
  9. /* default.css */
  10. body
  11. {
  12. font: 12px "Lucida Grande", Tahoma, Arial, Helvetica, sans-serif;
  13. width: 800px;
  14. }
  15. .header
  16. {
  17. clear: both;
  18. background-color: #ccc;
  19. padding: 8px;
  20. }
  21. h1
  22. {
  23. font-size: 150%;
  24. font-weight: bold;
  25. padding: 0;
  26. margin: 1em 0 0 .3em;
  27. }
  28. hr
  29. {
  30. border: none 0;
  31. border-top: 1px solid #7F8FB1;
  32. height: 1px;
  33. }
  34. pre.code
  35. {
  36. display: block;
  37. padding: 8px;
  38. border: 1px dashed #ccc;
  39. }
  40. #index
  41. {
  42. margin-top: 24px;
  43. float: left;
  44. width: 160px;
  45. position: absolute;
  46. left: 8px;
  47. background-color: #F3F3F3;
  48. padding: 8px;
  49. }
  50. #content
  51. {
  52. margin-left: 190px;
  53. width: 600px;
  54. }
  55. .classList
  56. {
  57. list-style-type: none;
  58. padding: 0;
  59. margin: 0 0 0 8px;
  60. font-family: arial, sans-serif;
  61. font-size: 1em;
  62. overflow: auto;
  63. }
  64. .classList li
  65. {
  66. padding: 0;
  67. margin: 0 0 8px 0;
  68. }
  69. .summaryTable { width: 100%; }
  70. h1.classTitle
  71. {
  72. font-size:170%;
  73. line-height:130%;
  74. }
  75. h2 { font-size: 110%; }
  76. caption, div.sectionTitle
  77. {
  78. background-color: #7F8FB1;
  79. color: #fff;
  80. font-size:130%;
  81. text-align: left;
  82. padding: 2px 6px 2px 6px;
  83. border: 1px #7F8FB1 solid;
  84. }
  85. div.sectionTitle { margin-bottom: 8px; }
  86. .summaryTable thead { display: none; }
  87. .summaryTable td
  88. {
  89. vertical-align: top;
  90. padding: 4px;
  91. border-bottom: 1px #7F8FB1 solid;
  92. border-right: 1px #7F8FB1 solid;
  93. }
  94. /*col#summaryAttributes {}*/
  95. .summaryTable td.attributes
  96. {
  97. border-left: 1px #7F8FB1 solid;
  98. width: 140px;
  99. text-align: right;
  100. }
  101. td.attributes, .fixedFont
  102. {
  103. line-height: 15px;
  104. color: #002EBE;
  105. font-family: "Courier New",Courier,monospace;
  106. font-size: 13px;
  107. }
  108. .summaryTable td.nameDescription
  109. {
  110. text-align: left;
  111. font-size: 13px;
  112. line-height: 15px;
  113. }
  114. .summaryTable td.nameDescription, .description
  115. {
  116. line-height: 15px;
  117. padding: 4px;
  118. padding-left: 4px;
  119. }
  120. pre
  121. {
  122. border-left: solid 10px #ddd;
  123. padding-left: 1.5em;
  124. }
  125. .summaryTable { margin-bottom: 8px; }
  126. ul.inheritsList
  127. {
  128. list-style: square;
  129. margin-left: 20px;
  130. padding-left: 0;
  131. }
  132. .detailList {
  133. margin-left: 20px;
  134. line-height: 15px;
  135. }
  136. .detailList dt { margin-left: 20px; }
  137. .detailList .heading
  138. {
  139. font-weight: bold;
  140. padding-bottom: 6px;
  141. margin-left: 0;
  142. }
  143. .light, td.attributes, .light a:link, .light a:visited
  144. {
  145. color: #777;
  146. font-style: italic;
  147. }
  148. .fineprint
  149. {
  150. text-align: right;
  151. font-size: 10px;
  152. }
  153. </style>
  154. </head>
  155. <body>
  156. <!-- ============================== header ================================= -->
  157. <!-- begin static/header.html -->
  158. <div id="header">
  159. </div>
  160. <!-- end static/header.html -->
  161. <!-- ============================== classes index ============================ -->
  162. <div id="index">
  163. <!-- begin publish.classesIndex -->
  164. <div align="center"><a href="../index.html">Class Index</a>
  165. | <a href="../files.html">File Index</a></div>
  166. <hr />
  167. <h2>Classes</h2>
  168. <ul class="classList">
  169. <li><i><a href="../symbols/_global_.html">_global_</a></i></li>
  170. <li><a href="../symbols/Array.html">Array</a></li>
  171. <li><a href="../symbols/Date.html">Date</a></li>
  172. <li><a href="../symbols/pv.html">pv</a></li>
  173. <li><a href="../symbols/pv.Anchor.html">pv.Anchor</a></li>
  174. <li><a href="../symbols/pv.Area.html">pv.Area</a></li>
  175. <li><a href="../symbols/pv.Bar.html">pv.Bar</a></li>
  176. <li><a href="../symbols/pv.Color.html">pv.Color</a></li>
  177. <li><a href="../symbols/pv.Color.Hsl.html">pv.Color.Hsl</a></li>
  178. <li><a href="../symbols/pv.Color.Rgb.html">pv.Color.Rgb</a></li>
  179. <li><a href="../symbols/pv.Colors.html">pv.Colors</a></li>
  180. <li><a href="../symbols/pv.Dot.html">pv.Dot</a></li>
  181. <li><a href="../symbols/pv.Flatten.html">pv.Flatten</a></li>
  182. <li><a href="../symbols/pv.Image.html">pv.Image</a></li>
  183. <li><a href="../symbols/pv.Label.html">pv.Label</a></li>
  184. <li><a href="../symbols/pv.Layout.grid.html">pv.Layout.grid</a></li>
  185. <li><a href="../symbols/pv.Layout.icicle.html">pv.Layout.icicle</a></li>
  186. <li><a href="../symbols/pv.Layout.stack.html">pv.Layout.stack</a></li>
  187. <li><a href="../symbols/pv.Layout.sunburst.html">pv.Layout.sunburst</a></li>
  188. <li><a href="../symbols/pv.Layout.treemap.html">pv.Layout.treemap</a></li>
  189. <li><a href="../symbols/pv.Line.html">pv.Line</a></li>
  190. <li><a href="../symbols/pv.Mark.html">pv.Mark</a></li>
  191. <li><a href="../symbols/pv.Nest.html">pv.Nest</a></li>
  192. <li><a href="../symbols/pv.ns.html">pv.ns</a></li>
  193. <li><a href="../symbols/pv.Panel.html">pv.Panel</a></li>
  194. <li><a href="../symbols/pv.Rule.html">pv.Rule</a></li>
  195. <li><a href="../symbols/pv.Scale.linear.html">pv.Scale.linear</a></li>
  196. <li><a href="../symbols/pv.Scale.log.html">pv.Scale.log</a></li>
  197. <li><a href="../symbols/pv.Scale.ordinal.html">pv.Scale.ordinal</a></li>
  198. <li><a href="../symbols/pv.Tree.html">pv.Tree</a></li>
  199. <li><a href="../symbols/pv.Vector.html">pv.Vector</a></li>
  200. <li><a href="../symbols/pv.version.html">pv.version</a></li>
  201. <li><a href="../symbols/pv.Wedge.html">pv.Wedge</a></li>
  202. </ul>
  203. <hr />
  204. <!-- end publish.classesIndex -->
  205. </div>
  206. <div id="content">
  207. <!-- ============================== class title ============================ -->
  208. <h1 class="classTitle">
  209. Class pv.Nest
  210. </h1>
  211. <!-- ============================== class summary ========================== -->
  212. <p class="description">
  213. Represents a Nest operator for the specified array. Nesting
  214. allows elements in an array to be grouped into a hierarchical tree
  215. structure. The levels in the tree are specified by <i>key</i> functions. The
  216. leaf nodes of the tree can be sorted by value, while the internal nodes can
  217. be sorted by key. Finally, the tree can be returned either has a
  218. multidimensional array via <a href="#entries">#entries</a>, or as a hierarchical map via
  219. <a href="#map">#map</a>. The <a href="#rollup">#rollup</a> routine similarly returns a map, collapsing
  220. the elements in each leaf node using a summary function.
  221. <p>For example, consider the following tabular data structure of Barley
  222. yields, from various sites in Minnesota during 1931-2:
  223. <pre>{ yield: 27.00, variety: "Manchuria", year: 1931, site: "University Farm" },
  224. { yield: 48.87, variety: "Manchuria", year: 1931, site: "Waseca" },
  225. { yield: 27.43, variety: "Manchuria", year: 1931, site: "Morris" }, ...</pre>
  226. To facilitate visualization, it may be useful to nest the elements first by
  227. year, and then by variety, as follows:
  228. <pre>var nest = pv.nest(yields)
  229. .key(function(d) d.year)
  230. .key(function(d) d.variety)
  231. .entries();</pre>
  232. This returns a nested array. Each element of the outer array is a key-values
  233. pair, listing the values for each distinct key:
  234. <pre>{ key: 1931, values: [
  235. { key: "Manchuria", values: [
  236. { yield: 27.00, variety: "Manchuria", year: 1931, site: "University Farm" },
  237. { yield: 48.87, variety: "Manchuria", year: 1931, site: "Waseca" },
  238. { yield: 27.43, variety: "Manchuria", year: 1931, site: "Morris" },
  239. ...
  240. ] },
  241. { key: "Glabron", values: [
  242. { yield: 43.07, variety: "Glabron", year: 1931, site: "University Farm" },
  243. { yield: 55.20, variety: "Glabron", year: 1931, site: "Waseca" },
  244. ...
  245. ] },
  246. ] },
  247. { key: 1932, values: ... }</pre>
  248. Further details, including sorting and rollup, is provided below on the
  249. corresponding methods.
  250. <br /><i>Defined in: </i> <a href="../symbols/src/data_Nest.js.html">Nest.js</a>.
  251. </p>
  252. <!-- ============================== constructor summary ==================== -->
  253. <table class="summaryTable" cellspacing="0" summary="A summary of the constructor documented in the class pv.Nest.">
  254. <caption>Class Summary</caption>
  255. <thead>
  256. <tr>
  257. <th scope="col">Constructor Attributes</th>
  258. <th scope="col">Constructor Name and Description</th>
  259. </tr>
  260. </thead>
  261. <tbody>
  262. <tr>
  263. <td class="attributes">&nbsp;</td>
  264. <td class="nameDescription" >
  265. <div class="fixedFont">
  266. <b><a href="../symbols/pv.Nest.html#constructor">pv.Nest</a></b>(array)
  267. </div>
  268. <div class="description">Constructs a nest operator for the specified array.</div>
  269. </td>
  270. </tr>
  271. </tbody>
  272. </table>
  273. <!-- ============================== properties summary ===================== -->
  274. <!-- ============================== methods summary ======================== -->
  275. <table class="summaryTable" cellspacing="0" summary="A summary of the methods documented in the class pv.Nest.">
  276. <caption>Method Summary</caption>
  277. <thead>
  278. <tr>
  279. <th scope="col">Method Attributes</th>
  280. <th scope="col">Method Name and Description</th>
  281. </tr>
  282. </thead>
  283. <tbody>
  284. <tr>
  285. <td class="attributes">&nbsp;</td>
  286. <td class="nameDescription">
  287. <div class="fixedFont"><b><a href="../symbols/pv.Nest.html#entries">entries</a></b>()
  288. </div>
  289. <div class="description">Returns a hierarchical nested array.</div>
  290. </td>
  291. </tr>
  292. <tr>
  293. <td class="attributes">&nbsp;</td>
  294. <td class="nameDescription">
  295. <div class="fixedFont"><b><a href="../symbols/pv.Nest.html#key">key</a></b>(key)
  296. </div>
  297. <div class="description">Nests using the specified key function.</div>
  298. </td>
  299. </tr>
  300. <tr>
  301. <td class="attributes">&nbsp;</td>
  302. <td class="nameDescription">
  303. <div class="fixedFont"><b><a href="../symbols/pv.Nest.html#map">map</a></b>()
  304. </div>
  305. <div class="description">Returns a hierarchical map of values.</div>
  306. </td>
  307. </tr>
  308. <tr>
  309. <td class="attributes">&nbsp;</td>
  310. <td class="nameDescription">
  311. <div class="fixedFont"><b><a href="../symbols/pv.Nest.html#rollup">rollup</a></b>(f)
  312. </div>
  313. <div class="description">Returns a rollup map.</div>
  314. </td>
  315. </tr>
  316. <tr>
  317. <td class="attributes">&nbsp;</td>
  318. <td class="nameDescription">
  319. <div class="fixedFont"><b><a href="../symbols/pv.Nest.html#sortKeys">sortKeys</a></b>(order)
  320. </div>
  321. <div class="description">Sorts the previously-added keys.</div>
  322. </td>
  323. </tr>
  324. <tr>
  325. <td class="attributes">&nbsp;</td>
  326. <td class="nameDescription">
  327. <div class="fixedFont"><b><a href="../symbols/pv.Nest.html#sortValues">sortValues</a></b>(order)
  328. </div>
  329. <div class="description">Sorts the leaf values.</div>
  330. </td>
  331. </tr>
  332. </tbody>
  333. </table>
  334. <!-- ============================== events summary ======================== -->
  335. <!-- ============================== constructor details ==================== -->
  336. <div class="details"><a name="constructor"> </a>
  337. <div class="sectionTitle">
  338. Class Detail
  339. </div>
  340. <div class="fixedFont">
  341. <b>pv.Nest</b>(array)
  342. </div>
  343. <div class="description">
  344. Constructs a nest operator for the specified array. This constructor should
  345. not be invoked directly; use <a href="../symbols/pv.html#.nest">pv.nest</a> instead.
  346. </div>
  347. <dl class="detailList">
  348. <dt class="heading">Parameters:</dt>
  349. <dt>
  350. <span class="light fixedFont">{array}</span> <b>array</b>
  351. </dt>
  352. <dd>an array of elements to nest.</dd>
  353. </dl>
  354. </div>
  355. <!-- ============================== field details ========================== -->
  356. <!-- ============================== method details ========================= -->
  357. <div class="sectionTitle">
  358. Method Detail
  359. </div>
  360. <a name="entries"> </a>
  361. <div class="fixedFont">
  362. <b>entries</b>()
  363. </div>
  364. <div class="description">
  365. Returns a hierarchical nested array. This method is similar to
  366. <a href="../symbols/pv.html#.entries">pv.entries</a>, but works recursively on the entire hierarchy. Rather
  367. than returning a map like <a href="#map">#map</a>, this method returns a nested
  368. array. Each element of the array has a <tt>key</tt> and <tt>values</tt>
  369. field. For leaf nodes, the <tt>values</tt> array will be a subset of the
  370. underlying elements array; for non-leaf nodes, the <tt>values</tt> array will
  371. contain more key-values pairs.
  372. <p>For an example usage, see the Nest constructor.
  373. </div>
  374. <dl class="detailList">
  375. <dt class="heading">Returns:</dt>
  376. <dd>a hierarchical nested array.</dd>
  377. </dl>
  378. <hr />
  379. <a name="key"> </a>
  380. <div class="fixedFont">
  381. <span class="light">{<a href="../symbols/pv.Nest.html">pv.Nest</a>}</span>
  382. <b>key</b>(key)
  383. </div>
  384. <div class="description">
  385. Nests using the specified key function. Multiple keys may be added to the
  386. nest; the array elements will be nested in the order keys are specified.
  387. </div>
  388. <dl class="detailList">
  389. <dt class="heading">Parameters:</dt>
  390. <dt>
  391. <span class="light fixedFont">{function}</span> <b>key</b>
  392. </dt>
  393. <dd>a key function; must return a string or suitable map
  394. key.</dd>
  395. </dl>
  396. <dl class="detailList">
  397. <dt class="heading">Returns:</dt>
  398. <dd><span class="light fixedFont">{<a href="../symbols/pv.Nest.html">pv.Nest</a>}</span> this.</dd>
  399. </dl>
  400. <hr />
  401. <a name="map"> </a>
  402. <div class="fixedFont">
  403. <b>map</b>()
  404. </div>
  405. <div class="description">
  406. Returns a hierarchical map of values. Each key adds one level to the
  407. hierarchy. With only a single key, the returned map will have a key for each
  408. distinct value of the key function; the correspond value with be an array of
  409. elements with that key value. If a second key is added, this will be a nested
  410. map. For example:
  411. <pre>pv.nest(yields)
  412. .key(function(d) d.variety)
  413. .key(function(d) d.site)
  414. .map()</pre>
  415. returns a map <tt>m</tt> such that <tt>m[variety][site]</tt> is an array, a subset of
  416. <tt>yields</tt>, with each element having the given variety and site.
  417. </div>
  418. <dl class="detailList">
  419. <dt class="heading">Returns:</dt>
  420. <dd>a hierarchical map of values.</dd>
  421. </dl>
  422. <hr />
  423. <a name="rollup"> </a>
  424. <div class="fixedFont">
  425. <b>rollup</b>(f)
  426. </div>
  427. <div class="description">
  428. Returns a rollup map. The behavior of this method is the same as
  429. <a href="#map">#map</a>, except that the leaf values are replaced with the return value
  430. of the specified rollup function <tt>f</tt>. For example,
  431. <pre>pv.nest(yields)
  432. .key(function(d) d.site)
  433. .rollup(function(v) pv.median(v, function(d) d.yield))</pre>
  434. first groups yield data by site, and then returns a map from site to median
  435. yield for the given site.
  436. </div>
  437. <dl class="detailList">
  438. <dt class="heading">Parameters:</dt>
  439. <dt>
  440. <span class="light fixedFont">{function}</span> <b>f</b>
  441. </dt>
  442. <dd>a rollup function.</dd>
  443. </dl>
  444. <dl class="detailList">
  445. <dt class="heading">Returns:</dt>
  446. <dd>a hierarchical map, with the leaf values computed by <tt>f</tt>.</dd>
  447. </dl>
  448. <dl class="detailList">
  449. <dt class="heading">See:</dt>
  450. <dd><a href="#map">#map</a></dd>
  451. </dl>
  452. <hr />
  453. <a name="sortKeys"> </a>
  454. <div class="fixedFont">
  455. <span class="light">{<a href="../symbols/pv.Nest.html">pv.Nest</a>}</span>
  456. <b>sortKeys</b>(order)
  457. </div>
  458. <div class="description">
  459. Sorts the previously-added keys. The natural sort order is used by default
  460. (see <a href="../symbols/pv.html#.naturalOrder">pv.naturalOrder</a>); if an alternative order is desired,
  461. <tt>order</tt> should be a comparator function. If this method is not called
  462. (i.e., keys are <i>unsorted</i>), keys will appear in the order they appear
  463. in the underlying elements array. For example,
  464. <pre>pv.nest(yields)
  465. .key(function(d) d.year)
  466. .key(function(d) d.variety)
  467. .sortKeys()
  468. .entries()</pre>
  469. groups yield data by year, then variety, and sorts the variety groups
  470. lexicographically (since the variety attribute is a string).
  471. <p>Key sort order is only used in conjunction with <a href="#entries">#entries</a>, which
  472. returns an array of key-values pairs. If the nest is used to construct a
  473. <a href="#map">#map</a> instead, keys are unsorted.
  474. </div>
  475. <dl class="detailList">
  476. <dt class="heading">Parameters:</dt>
  477. <dt>
  478. <span class="light fixedFont">{function}</span> <b>order</b>
  479. <i>Optional</i>
  480. </dt>
  481. <dd>an optional comparator function.</dd>
  482. </dl>
  483. <dl class="detailList">
  484. <dt class="heading">Returns:</dt>
  485. <dd><span class="light fixedFont">{<a href="../symbols/pv.Nest.html">pv.Nest</a>}</span> this.</dd>
  486. </dl>
  487. <hr />
  488. <a name="sortValues"> </a>
  489. <div class="fixedFont">
  490. <span class="light">{<a href="../symbols/pv.Nest.html">pv.Nest</a>}</span>
  491. <b>sortValues</b>(order)
  492. </div>
  493. <div class="description">
  494. Sorts the leaf values. The natural sort order is used by default (see
  495. <a href="../symbols/pv.html#.naturalOrder">pv.naturalOrder</a>); if an alternative order is desired, <tt>order</tt>
  496. should be a comparator function. If this method is not called (i.e., values
  497. are <i>unsorted</i>), values will appear in the order they appear in the
  498. underlying elements array. For example,
  499. <pre>pv.nest(yields)
  500. .key(function(d) d.year)
  501. .key(function(d) d.variety)
  502. .sortValues(function(a, b) a.yield - b.yield)
  503. .entries()</pre>
  504. groups yield data by year, then variety, and sorts the values for each
  505. variety group by yield.
  506. <p>Value sort order, unlike keys, applies to both <a href="#entries">#entries</a> and
  507. <a href="#map">#map</a>. It has no effect on <a href="#rollup">#rollup</a>.
  508. </div>
  509. <dl class="detailList">
  510. <dt class="heading">Parameters:</dt>
  511. <dt>
  512. <span class="light fixedFont">{function}</span> <b>order</b>
  513. <i>Optional</i>
  514. </dt>
  515. <dd>an optional comparator function.</dd>
  516. </dl>
  517. <dl class="detailList">
  518. <dt class="heading">Returns:</dt>
  519. <dd><span class="light fixedFont">{<a href="../symbols/pv.Nest.html">pv.Nest</a>}</span> this.</dd>
  520. </dl>
  521. <!-- ============================== event details ========================= -->
  522. <hr />
  523. </div>
  524. <!-- ============================== footer ================================= -->
  525. <div class="fineprint" style="clear:both">
  526. Documentation generated by <a href="http://code.google.com/p/jsdoc-toolkit/" target="_blank">JsDoc Toolkit</a> 2.3.0 on Tue Oct 06 2009 09:59:02 GMT-0700 (PDT)
  527. </div>
  528. </body>
  529. </html>