{"id":16993428,"url":"https://github.com/mcnuttandrew/table-cartogram","last_synced_at":"2025-09-09T06:42:49.507Z","repository":{"id":39021061,"uuid":"103849643","full_name":"mcnuttandrew/table-cartogram","owner":"mcnuttandrew","description":"Display tabular data areally","archived":false,"fork":false,"pushed_at":"2024-06-04T17:57:02.000Z","size":4434,"stargazers_count":3,"open_issues_count":45,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-02-27T21:50:17.428Z","etag":null,"topics":["cartogram","table-cartogram","visualization"],"latest_commit_sha":null,"homepage":"https://www.mcnutt.in/table-cartogram/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mcnuttandrew.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-09-17T17:52:53.000Z","updated_at":"2024-06-04T17:57:06.000Z","dependencies_parsed_at":"2024-06-11T01:18:30.834Z","dependency_job_id":null,"html_url":"https://github.com/mcnuttandrew/table-cartogram","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mcnuttandrew%2Ftable-cartogram","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mcnuttandrew%2Ftable-cartogram/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mcnuttandrew%2Ftable-cartogram/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mcnuttandrew%2Ftable-cartogram/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mcnuttandrew","download_url":"https://codeload.github.com/mcnuttandrew/table-cartogram/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243858376,"owners_count":20359253,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cartogram","table-cartogram","visualization"],"created_at":"2024-10-14T03:43:08.672Z","updated_at":"2025-03-17T09:30:38.092Z","avatar_url":"https://github.com/mcnuttandrew.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# table-cartogram.js\n\nTable cartograms are a type of data visualization that represents tables of data as grid of quadrilaterals. They look a lot like if you were a heatmap were area-ed rather than colored. They may look really unconventional, but they have a surprisingly wide collection of uses, ranging from calendars, to pivot tables, and many others. They facilitate part-to-whole and part-to-part comparisons, in a similar manner as a pie chart, as well as offer specific detail look up, as in a traditional table or heatmap. Together these properties can make really interesting displays.\n\n\u003cimg src=\"./docs-site/assets/zion.png\" alt=\"Table cartogram describing visitor statistics to zion national park\"/\u003e\n\nIn this library we provide an iteration based approach to creating table cartograms. We follow a very simple optimization approach in which we select from a library of initializations, also allowing for custom ones, and then iteratively adjust the vertices via gradient descent until a satisfactory condition is reached. Details about the math and algorithm can be found [here](https://osf.io/kem6j) while a discussion of their usage properties can be found [here](https://arxiv.org/abs/2104.04042).\n\n\n### Usage for the REALLY impatient\n\nA version of this library is deployed [here](https://www.mcnutt.in/table-cartogram/). You can upload a dataset to make into a table cartogram there by click \"Customize data\" and then pasting in a well formatted JSON table. Click \"Set string data as custom data\" to save your data. Finally click start to start computing it. \n\n\n\u003cimg src=\"./docs-site/assets/usage-screenshot.png\" alt=\"Screenshot of the ui for creating table cartograms\"/\u003e\n\n\n## Installation\n\nTo install table-cartogram.js pick your favorite command line installation tool and install from npm:\n\n```sh\nnpm install --save table-cartogram\n```\n\n### Usage for the impatient\n\nThis is a layout library similar to d3-force or d3-hierarchy, which means that we don't necessarily provide a way for you to render our shapes on the page. Instead we just process the data you give us and give back the layout as specified. For instance, running\n\n```js\nimport {tableCartogram} from 'table-cartogram';\nconst processedData = tableCartogram({\n  data: [[1, 2, 3], [4, 5, 6], [7, 8, 9]],\n  iterations: 300\n});\n```\nThis will run for 300 steps (is this a lot is this a little? it is unclear in general, see below for more details) and then give back the following json blob:\n\n ```js\n [\n   {\n     vertices: [\n      {x: 0, y: 0},\n      {x: 0, y: 0.11587962704189894},\n      {x: 0.23766482934163694, y: 0.07045603854120724},\n      {x: 0.2399217002219555, y: 0}\n     ], value: 1, data: 1\n   }, {\n     vertices: [\n      {x: 0.2399217002219555, y: 0},\n      {x: 0.23766482934163694, y: 0.07045603854120724},\n      {x: 0.5729791507019034, y: 0.1906732352855676},\n      {x: 0.5807805266917323, y: 0}\n     ], value: 2, data: 2\n   }, {\n     vertices: [\n      {x: 0.5807805266917323, y: 0},\n      {x: 0.5729791507019034, y: 0.1906732352855676},\n      {x: 1, y: 0.1250510371936567},\n      {x: 1, y: 0}\n     ], value: 3, data: 3\n   }, {\n     vertices: [\n      {x: 0, y: 0.11587962704189894},\n      {x: 0, y: 0.44130111740810685},\n      {x: 0.27288647717499803, y: 0.438094616754241},\n      {x: 0.23766482934163694, y: 0.07045603854120724}\n     ], value: 4, data: 4\n   }, {\n     vertices: [\n      {x: 0.23766482934163694, y: 0.07045603854120724},\n      {x: 0.27288647717499803, y: 0.438094616754241},\n      {x: 0.6202653218584823, y: 0.4955203300528266},\n      {x: 0.5729791507019034, y: 0.1906732352855676}\n     ], value: 5, data: 5\n   }, {\n     vertices: [\n      {x: 0.5729791507019034, y: 0.1906732352855676},\n      {x: 0.6202653218584823, y: 0.4955203300528266},\n      {x: 1, y: 0.47631624172556986},\n      {x: 1, y: 0.1250510371936567}\n     ], value: 6, data: 6\n   }, {\n     vertices: [\n      {x: 0, y: 0.44130111740810685},\n      {x: 0, y: 1},\n      {x: 0.28234244751135684, y: 1},\n      {x: 0.27288647717499803, y: 0.438094616754241}\n     ], value: 7, data: 7\n   }, {\n     vertices: [\n      {x: 0.27288647717499803, y: 0.438094616754241},\n      {x: 0.28234244751135684, y: 1},\n      {x: 0.6012939097461701, y: 1},\n      {x: 0.6202653218584823, y: 0.4955203300528266}\n     ], value: 8, data: 8\n   }, {\n     vertices: [\n      {x: 0.6202653218584823, y: 0.4955203300528266},\n      {x: 0.6012939097461701, y: 1},\n      {x: 1, y: 1},\n      {x: 1, y: 0.47631624172556986}\n     ], value: 9, data: 9\n   }\n ]\n ```\nIt is then up to you to figure out how to render this thing! For more impatience, check out the [iterative-display](\"./showcase/components/iterative-display.js\") file for more.\n\n\n\n# API\n\nWe expose three top level functions, which related to three processing modes for the table cartogram: tableCartogram, tableCartogramWithUpdate, tableCartogramAdaptive. In a subsequent release we will expose a collection of react components for computing the table cartogram, those components currently live in showcase/components, most notably iterative-display.js (which shows the converge process for a table cartogram) and table-cartogram.js (which is a simple rendering component).\n\n\n## tableCartogram\n\nConstruct a table cartogram using a fixed number of steps. \n\n### Props  \n**data**: DataTable  \nAny tabular data that can be be combined with an accessor to generate number[][]\n\n**accessor**: (x: any) =\u003e number   \nA lambda function for getting the of a particular cell with data table \n\n**layout**: LayoutType  \nSee Below\n\n**iterations**: number  \nThe number of iteration that you wish for the computation to run\n\n\n**height?**: number  \nDefault: 1  \nThe height scaling factor of computation. Generally good to select a low number such as 1.\n\n**width?**: number  \nDefault: 1  \nThe width scaling factor of computation. Generally good to select a low number such as 1.\n\n**optimizationParams?**: OptimizationParams  \nObject See Below\n\n### Example\n\n```js\nconst directResults = tableCartogram({\n  data: TEST_TABLE,\n  layout: 'gridLayout',\n  iterations: 300,\n  accessor: (d) =\u003e d.x,\n  height: 0.5,\n});\n```\n\n## tableCartogramWithUpdate\n\nConstruct a function for iteratively creating updates, useful for watching the descent process or debugging. Returns a function which takes a number of steps to take, that is it's type is something like `(PROPS) =\u003e (steps: number) =\u003e polygons`.\n\n### Props\n\n**data**: DataTable  \nAny tabular data that can be be combined with an accessor to generate number[][]\n\n**accessor**: (x: any) =\u003e number   \nA lambda function for getting the of a particular cell with data table \n\n**height?**: number  \nDefault: 1  \nThe height scaling factor of computation. Generally good to select a low number such as 1.\n\n**width?**: number  \nDefault: 1  \nThe width scaling factor of computation. Generally good to select a low number such as 1.\n\n**layout**: LayoutType  \nSee Below\n\n**optimizationParams?**: OptimizationParams  \nObject See Below\n\n### Example\n\n```js\nconst resultsBuilder = tableCartogramWithUpdate({\n  data: TEST_TABLE,\n  layout: 'gridLayout',\n  accessor: (d) =\u003e d.x,\n  height: 0.5,\n});\nconst withUpdateResults = resultsBuilder(300);\n```\n\n\n## tableCartogramAdaptive\n\nConstruct a table cartogram using a fixed accuracy target.\n\n### Props\n\n**data**: DataTable  \nAny tabular data that can be be combined with an accessor to generate number[][]\n\n**accessor**: (x: any) =\u003e number   \nA lambda function for getting the of a particular cell with data table \n\n**height?**: number  \nDefault: 1  \nThe height scaling factor of computation. Generally good to select a low number such as 1.\n\n**width?**: number  \nDefault: 1  \nThe width scaling factor of computation. Generally good to select a low number such as 1.\n\n**layout**: LayoutType  \nSee Below\n\n**logging?**: boolean    \nDefault: false\nWhether or not to provide console logging of various metrics across the gradient descent process\n\n**maxNumberOfSteps?**: number;\nThe maximum number of allowed steps in the descent.\n\n**iterationStepSize?**: number   \nDefault: 10   \nHow many gradient steps to take in between checks\n\n\n**maxNumberOfSteps?**: number   \nDefault: 1000   \nThe maximum allowed number of steps that can be taken\n\n**optimizationParams?**: OptimizationParams   \nObject See Below\n\n**targetAccuracy?**: number   \nDefault: 0.01   \nThe target accuracy for the adaptive descent.\n\n### Example\n\n```js\nconst adaptive = tableCartogramAdaptive({\n  data: TEST_TABLE,\n  layout: 'gridLayout',\n  maxNumberOfSteps: 300,\n  accessor: (d) =\u003e d.x,\n  height: 0.5,\n});\n```\n\n## Optimization Params\n\nThe controls for the gradient descent and objective function. \n\n\n\n### Props\nDefault \n```js\n{\n  lineSearchSteps: 30,\n  useAnalytic: false,\n  stepSize: 0.01,\n  nonDeterministic: false,\n  useGreedy: true,\n  orderPenalty: 1,\n  borderPenalty: 1,\n  overlapPenalty: 4,\n}\n```\n\nParam: lineSearchSteps  \nDefault: 30\nDescription: The number of steps to take while computing the gradient line search.\n\nParam: useAnalytic  \nDefault: false\nDescription: Whether to use the analytic gradient or an automatically computed one.\n\nParam: stepSize  \nDefault: 0.01\nDescription: How big a step to use in computing the gradient.\n\nParam: nonDeterministic  \nDefault: false\nDescription: Whether to use stochastic gradient descent or just regular gradient descent.\n\nParam: useGreedy  \nDefault: true\nDescription: Whether to use a greedy strategy (bigger shapes should be corrected first) for computing the object or a normalized one (all shapes should be corrected at the same rate).\n\nParam: orderPenalty  \nDefault: 1\nDescription: How much penalty to assign to nodes that have gone out of order.\n\nParam: borderPenalty  \nDefault: 1\nDescription: How much penalty to assign to nodes that have gone out of the border.\n\nParam: overlapPenalty  \nDefault: 4\nDescription: How much penalty to assign to overlap between quads.\n\n\n## Layouts\n\nWe offer a suite of 12 layouts, 10 single algorithm layouts and 2 meta layouts. Much of the control that our library offers is due to the flexibility of these layouts.\n\nThe single layouts consist of: gridLayout, zigZagOnX, zigZagOnY, zigZagOnXY, psuedoCartogramLayout, psuedoCartogramLayoutZigZag, partialPsuedoCartogram, rampX, rampY, rampXY.\n\nThe meta layouts are: pickBest and pickWorst. As the names suggest they iterate through each of the single layout options and try to select either the best or the worst one, based purely on the objective score at that point.\n\n# Contributing and Local Development\n\nWe welcome contributions and comments. To get started simply run\n\n1. Have Yarn/Node/Npm Installed\n2. Install our deps\n3. Start up the development sandbox\n\nFor example\n```sh\nyarn\nyarn start\n```\n\nAfter you've developed things, make sure that code passes the tests:\n\n```sh\nyarn lint\nyarn test\n```\n\nAnd then you're good!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmcnuttandrew%2Ftable-cartogram","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmcnuttandrew%2Ftable-cartogram","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmcnuttandrew%2Ftable-cartogram/lists"}