{"id":13481612,"url":"https://github.com/tomgp/d3-iconarray","last_synced_at":"2025-04-10T12:33:16.996Z","repository":{"id":35714802,"uuid":"39992818","full_name":"tomgp/d3-iconarray","owner":"tomgp","description":"A D3 module for making grids of icons","archived":false,"fork":false,"pushed_at":"2021-07-17T07:41:50.000Z","size":370,"stargazers_count":84,"open_issues_count":0,"forks_count":8,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-03-24T11:13:11.222Z","etag":null,"topics":["d3","data-visualisation","grid","icon-array","scale"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tomgp.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-07-31T07:32:03.000Z","updated_at":"2024-10-13T20:59:30.000Z","dependencies_parsed_at":"2022-09-08T11:03:30.203Z","dependency_job_id":null,"html_url":"https://github.com/tomgp/d3-iconarray","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tomgp%2Fd3-iconarray","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tomgp%2Fd3-iconarray/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tomgp%2Fd3-iconarray/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tomgp%2Fd3-iconarray/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tomgp","download_url":"https://codeload.github.com/tomgp/d3-iconarray/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248217131,"owners_count":21066633,"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":["d3","data-visualisation","grid","icon-array","scale"],"created_at":"2024-07-31T17:00:53.335Z","updated_at":"2025-04-10T12:33:16.974Z","avatar_url":"https://github.com/tomgp.png","language":"JavaScript","funding_links":[],"categories":["Utils"],"sub_categories":[],"readme":"# d3-iconarray\n\n![examples](images/examples.png)\n\nA D3 plugin targeting V4 helping you to draw an array of icons.\n\n\u003ca href=\"#why\"\u003eWhy?\u003c/a\u003e\n\nThere are two parts to this plugin. First a \u003ca href=\"#layout\"\u003elayout\u003c/a\u003e which will assign x,y coordinates to elements of an array given some parameters. Second a \u003ca href=\"#scale\"\u003escale\u003c/a\u003e which will put regular breaks in the array of icons to aid legibility.\n\n## Installing\n\nIf you use NPM, `npm install d3-iconarray`. Otherwise, download the [latest release](https://github.com/tomgp/d3-iconarray/releases/latest).\n\n## Examples\n\n * \u003ca href=\"http://bl.ocks.org/tomgp/47d151732913c6d1f74e\"\u003eA minimal example using both layout and scale features\u003c/a\u003e\n * \u003ca href=\"http://bl.ocks.org/tomgp/8c11fd6d5c533ce6d31c\"\u003eUsing the plugin to make a hemicycle for election results\u003c/a\u003e\n * \u003ca href=\"http://bl.ocks.org/tomgp/6fb9b8c93f86b24d6828\"\u003eRecreating a \u003cabbr title=\"Group B strep\"\u003eGBS\u003c/abbr\u003e risk graphic from Scientific American\u003c/a\u003e\n * \u003ca href=\"http://bl.ocks.org/tomgp/f891cc72ecb5d6015a5d\"\u003eSetting the scale's gapSize and gapInterval properties\u003c/a\u003e\n * \u003ca href=\"http://bl.ocks.org/tomgp/59b5d482551ca14a4063\"\u003eUS Senate battlegrounds\u003c/a\u003e\n * \u003ca href=\"http://bl.ocks.org/tomgp/a2c34418f2341f078624\"\u003ewhen to use the widthFirst switch (UK election results)\u003c/a\u003e\n * \u003ca href=\"http://bl.ocks.org/tomgp/eb4079086278ae34844a\"\u003eModal transport share with emojis\u003c/a\u003e\n\n## API Reference\n\n### Layout\n\n\u003ca href=\"#layout\" name=\"layout\"\u003e#\u003c/a\u003e d3_iconarray\u003cb\u003e.layout\u003c/b\u003e()\n\nConstruct a new icon array layout function.\n\n\u003ca href=\"#_layout\" name=\"_layout\"\u003e#\u003c/a\u003e \u003cb\u003elayout\u003c/b\u003e([data array])\n\nThe function created by the above.  When given an array of data will return an array containing grid positions as well as the original data. Unless a \u003ca href=\"#height\"\u003eheight\u003c/a\u003e or \u003ca href=\"#width\"\u003ewidth\u003c/a\u003e restriction has been specified the layout will try to make the grid as square as possible. eg. a 100 element data array will result in a 10x10 grid.\n\nexample\n\n```\nvar layout = d3_iconarray.layout();\n\nvar grid = layout([1,2,3,4]); \n\n/*\n'grid' is\n\n[\n\t{\"data\":1,\"position\":{\"x\":0,\"y\":0}},\n\t{\"data\":2,\"position\":{\"x\":1,\"y\":0}},\n\t{\"data\":3,\"position\":{\"x\":0,\"y\":1}},\n\t{\"data\":4,\"position\":{\"x\":1,\"y\":1}}\n]\n\n/*\n\n```\nYou can use the resulting grid to plot icons, the data points will be arranged like this\n\n![layout 1](images/layout1.png)\n\n\u003ca href=\"#widthFirst\" name=\"widthFirst\"\u003e#\u003c/a\u003e layout\u003cb\u003e.widthFirst\u003c/b\u003e([boolean])\n\nThis function sets the order in which points are arranged in the grid. if widthFirst is set to true rows will be filled before starting the next, if it's false columns in the layout will be filled first. if no argument is provided it returns the current value.\n\nexample\n```\nvar layout = d3_iconarray.layout()\n\t\t\t\t\t.widthFirst(true);\n\nvar grid = layout([1,2,3,4]); \n```\n\nthe resulting in the resulting grid the icons will be arranged like this\n\n![layout 2](images/layout2.png)\n\nwith ` .widthFirst(false)` they'll be arranged like this\n\n![layout 3](images/layout3.png)\n\n\u003ca href=\"http://bl.ocks.org/tomgp/a2c34418f2341f078624\"\u003ewhen to use the widthFirst switch (UK election results)\u003c/a\u003e\n\n\u003ca href=\"#width\" name=\"width\"\u003e#\u003c/a\u003e layout\u003cb\u003e.width\u003c/b\u003e([integer])\n\nthe width function defines the maximum number of elements the grid will have in a given row. if no argument is provided it returns the current value.\n\nexample\n\n```\nvar layout = d3_iconarray.layout().width(3);\nvar grid = layout([1,2,3,4,5,6,7,8,9,10,11,12,13,14,15]);\n```\nresults in a grid like\n\n![layout width restriction](images/layoutwidth.png)\n\n\u003ca href=\"#height\" name=\"height\"\u003e#\u003c/a\u003e layout\u003cb\u003e.height\u003c/b\u003e([integer])\n\nthe height function sets the maximum number of elements the grid will have in a given row. if no argument is provided it returns the current value.\n\nexample\n```\nvar layout = d3_iconarray.layout().height(3);\nvar grid = layout([1,2,3,4,5,6,7,8,9,10,11,12,13,14,15]);\n```\n\nresults in a grid like\n\n![layout height restriction](images/layoutheight.png)\n\n\u003ca href=\"#position\" name=\"position\"\u003e#\u003c/a\u003e layout\u003cb\u003e.position\u003c/b\u003e([integer])\n\ngiven the a number representing an array element this function will tell you it's {x, y} location in the grid. \nThis function needs some dimension of the grid (height or width) to have been set explicitly (by \u003ca href=\"#height\"\u003eheight\u003c/a\u003e or \u003ca href=\"#width\"\u003ewidth\u003c/a\u003e) or implicitly by passing a data array to the layout function\n\nexample\n\n```\nvar layout = d3_iconarray.layout();\nvar grid = layout([1,2,3,4,5,6,7,8,9,10,11,12,13,14,15]);\n\nvar p = layout.position(7);\n// p is {x: 3, y: 1}\n\n```\n\n\u003ca href=\"#maxDimension\" name=\"maxDimension\"\u003e#\u003c/a\u003e layout\u003cb\u003e.maxDimension\u003c/b\u003e([integer])\n\nA bit like \u003ca href=\"#position\"\u003eposition\u003c/a\u003e but given a number will return the maximum extent of the lyout if it were to have that many elements. THis is useful for setting the domain of scales.\n\n\n### Scale\n\nYou can use any kind of scale to draw your grid to the screen. The scale provided by the plugin can let you add breaks to your icon array to improve legibility e.g. here's a 2500 element array grouped in to blocks of 100.\n\n![blocks of 100](images/scaleexample.png)\n\n\u003ca href=\"#scale\" name=\"scale\"\u003e#\u003c/a\u003e d3_iconarray\u003cb\u003e.scale\u003c/b\u003e()\n\nCreates a scale function just like good ol' \u003ca href=\"https://github.com/d3/d3-scale#linear-scales\"\u003ed3.scaleLinear()\u003c/a\u003e etc.\n\n\u003ca href=\"#_scale\" name=\"_scale\"\u003e#\u003c/a\u003e \u003cb\u003escale\u003c/b\u003e(x)\n\nGiven a value x in the input domain, returns the corresponding value in the output range.\n\n\u003ca href=\"#domain\" name=\"domain\"\u003e#\u003c/a\u003e scale\u003cb\u003e.domain\u003c/b\u003e([numbers])\n\nSet the input domain, an array of 2 numbers.\n\nIf no arguments are provided this returns the current value.\n\n\u003ca href=\"#range\" name=\"range\"\u003e#\u003c/a\u003e scale\u003cb\u003e.range\u003c/b\u003e([numbers])\n\nSet the output range, an array of 2 numbers.\n\nIf no arguments are provided this returns the current value.\n\n\u003ca href=\"#gapInterval\" name=\"gapInterval\"\u003e#\u003c/a\u003e scale\u003cb\u003e.gapInterval\u003c/b\u003e(x)\n\nThis function accepts a number which sets at what interval a gaps appear in the output range. i.e. if _x_ is 10 there will be an extra gap after every ten items in the output range.\n\nIf no arguments are provided this returns the current value. \n\n\u003ca href=\"http://bl.ocks.org/tomgp/f891cc72ecb5d6015a5d\"\u003esee this example\u003c/a\u003e\n\n\u003ca href=\"#gapSize\" name=\"gapSize\"\u003e#\u003c/a\u003e scale\u003cb\u003e.gapSize\u003c/b\u003e(x)\n\nThis sets how big the gaps in the output range will be relative to the normal spacing. So if the normal spacing between two whole numbers is 10px and the gap size is set to 1.5 the extra wide space will be 15px.\n\nIf no arguments are provided this returns the current value.\n\n\u003ca href=\"http://bl.ocks.org/tomgp/f891cc72ecb5d6015a5d\"\u003esee this example\u003c/a\u003e\n\n## Why?\n\u003ca href=\"#why\" name=\"why\"\u003e#\u003c/a\u003e \n\u003eTwenty years ago, a psychological study compared for the first time rudimentary icon displays for communicating risk. Today, we have dozens of randomized experiments to support the use of icon arrays (sometimes referred to as “pictographs”) as an evidence-based standard in medical risk communication.\n\n[Why use Icon Arrays](http://www.iconarray.com/why)\n\n\u003eIcon arrays are particularly effective, and are apparently less likely to increase patient anxiety than other graphical techniques.\n\n[Scientific American: Inadequate Data Visualization Leaves Patients Undereducated](http://blogs.scientificamerican.com/sa-visual/inadequate-data-visualization-leaves-patients-undereducated/)\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftomgp%2Fd3-iconarray","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftomgp%2Fd3-iconarray","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftomgp%2Fd3-iconarray/lists"}