{"id":29625262,"url":"https://github.com/novartis/gridvar","last_synced_at":"2025-07-21T06:07:48.333Z","repository":{"id":14352492,"uuid":"17062084","full_name":"Novartis/gridvar","owner":"Novartis","description":"GridVar is a jQuery plugin that visualizes multi-dimensional datasets as layers organized in a row-column format.","archived":false,"fork":false,"pushed_at":"2014-02-21T18:09:14.000Z","size":184,"stargazers_count":14,"open_issues_count":0,"forks_count":8,"subscribers_count":8,"default_branch":"master","last_synced_at":"2024-04-16T11:10:09.473Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Novartis.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2014-02-21T16:24:19.000Z","updated_at":"2023-08-21T16:47:12.000Z","dependencies_parsed_at":"2022-09-13T15:51:26.118Z","dependency_job_id":null,"html_url":"https://github.com/Novartis/gridvar","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/Novartis/gridvar","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Novartis%2Fgridvar","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Novartis%2Fgridvar/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Novartis%2Fgridvar/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Novartis%2Fgridvar/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Novartis","download_url":"https://codeload.github.com/Novartis/gridvar/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Novartis%2Fgridvar/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266248501,"owners_count":23899056,"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":[],"created_at":"2025-07-21T06:07:48.226Z","updated_at":"2025-07-21T06:07:48.311Z","avatar_url":"https://github.com/Novartis.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"[GridVar][examples]\n=======================\n\n![GridVar screenshot](/docs/img/gridVarExample.png \"GridVar screenshot\")\n\nGridVar is a jQuery plugin that visualizes multi-dimensional datasets as layers organized in a row-column format. At each cell (i.e., rectangle at the intersection of a row and column), GridVar displays your data as a background color (like a color/heat map) and/or a glyph (shape). This enables different characteristics of your dataset to be layered on top of each other. \n\nPlease view our [examples page][examples] to see GridVar in action.\n\nFeatures\n--------\n\n* Display of multi-dimensional data through colors and/or glyphs.\n* Animated transitions when reordering rows and columns.\n* Histogram for aggregate data analysis.\n* Tooltips for more information about the cell.\n* Export visualization to SVG.\n\nGetting Started\n---------------\n\nDownload the javascript and css:\n* [GridVar Zip][zipball] \n \nGridVar has a few **dependencies** that need to be included:\n\n* [d3][d3] 2.0+\n* [jQuery][jquery] 1.8+\n* [jQuery UI][jquery-ui] 1.8+\n* [Underscore][underscore] 1.0+\n\n**Additional functionality** can be activated by including the following libraries:\n\n* [QTip][qtip]: if this is not included, you don't get the qtip-styled tooltips\n* [Filesaver][filesaver]: if this is not included, export to SVG option will be disabled\n* [Blob.js][blob]: some older browser versions need Blob.js for FileSaver.js to function properly\n\nUsage\n-----\n\n### Renderers\n\nRenderers come in two forms, [Built-in Renderers][built-in-renderers] and [Custom Renderers][custom-renderers].\n\n#### Built-in Renderers\n\nBuilt-in renderers consist of two types, backgrounds and glyphs. You can specify a background renderer by providing a\nRGB hex color code preceded by a '#' like '#AAFFAA'. You can specify a built-in glyph render by providing renderer type\n(for example, 'xRenderer'). The built-in renderers provide default styles and attributes. Override these with values or\nfunctions of your own choosing by providing styles and/or attribute data. Provide a function for dynamically generated\nattributes and styles. The format for the styles and attributes take the following base form:\n\n```javascript\n{ attrs : { d : 'builtInRendererName'}, styles : { stroke : '#0000ff' }}\n```\n\nChange the stroke color of the xRenderer render like so:\n\n```javascript\n{ attrs : { d : 'xRenderer'}, styles : { stroke :'#0000ff' }}\n```\n\nThis set of attributes and styles results in a blue xRenderer:\n\nStyle functions will be passed the data, width, and height of the cell. For example, if you wish to scale the\nstroke-width according to the size of the cell, define the following parameters:\n\n```javascript\n{\n  attrs : {\n    d : 'xRenderer'\n    },\n  styles : {\n    'stroke-width' : function (data,width,height) {\n            return Math.floor(Math.sqrt( width * height) / 10);\n          }\n    }\n}\n```\n\nThis will result in the following dynamic stroke-width of the xRender defined by the the cell size for example:\n\n* 20x20 cell scaled: ![xRenderer 20x20 Scaled](/docs/img/xRenderer20Scaled.png)\n* 40x40 cell scaled: ![xRenderer 40x40 Scaled](/docs/img/xRenderer40Scaled.png)\n* 40x40 cell default: ![xRenderer 40x40 Normal](/docs/img/xRenderer40Normal.png)\n\n#### Custom Renderers\n\nThere are two ways to provide a custom renderer to the GridVar plugin:\n\n* Simple custom renderer: a function that returns an SVG path\n* Complete custom renderer: a function and set of attributes and or styles\n\nSimple custom renderers are functions which return the 'd' value for an [SVG path][svg-path]. A function will be passed the data for\nthe cell, the width of the cell, and the height of the cell. For example, to draw a simple diagonal line from the top\nleft corner of the cell to the bottom right corner of the cell, provide the following simple custom renderer:\n\n```javascript\nDataTypeValue: function(value,width,height) {return 'M0,0L' + width + ',' + height;}\n```\n\nThis will result in the following custom renderer: ![Simple Custom Renderer](/docs/img/simpleCustom.png)\n\n##### Simple Custom Renderer Example\n\nSimple custom renderers are created using a function that returns a SVG path. \nUsing an SVG editor (e.g. Google's [svg-edit][svg-edit]) is an easy solution for editing an SVG path.\n\nCopy the SVG path to the results of a function in the mappings object (see example below). This function will be passed three arguments, the data associated with the cell for the renderer data type, along with the width and height of the cell.\n\n```javascript\n{\n dataType: 'cloudy',\n mappings: {\n    cloudy: function(data, width, height) {\n        return \"m3.2863,7.40575c-0.72778,0 -1.31805,-0.68071 -1.31805,-1.52l0,0c ...\";\n       }\n     }\n}\n```\n\n##### Complete Custom Renderers\n\nComplete custom renderers provide additional functionality for customizing the styles and attributes of the glyph, such as stroke color, stroke width, opacity, etc. At a minimum, the complete custom renderer must provide the path function as part of the attributes object. For example, the complete form of the diagonal line from above becomes:\n\n```javascript\nDataTypeValue: {\n    attrs : {\n        d: function(value,width,height) {\n            return 'M0,0L' + width + ',' + height;\n        }\n    }\n}\n```\n\nTo customize styles, such as stroke color, provide the styles object with the stroke value:\n\n```javascript\nDataTypeValue: {\n    attrs : {\n        d : function (value, width, height) {\n            return 'M0,0L' + width + ',' + height;\n        }\n    },\n    styles : {\n        stroke : '#0000ff'\n    }\n}\n```\n\nThis results in the following custom glyph: ![Custom Glyph](/docs/img/completeCustomRendererDefault.png)\n\nYou can override any style attribute. For example, to adjust the stroke-width:\n\n```javascript\nDataTypeValue: {\n    attrs: {\n        d: function (value, width, height) {\n            return 'M0,0L' + width + ',' + height;\n        }\n    },\n    styles: {\n        stroke: '#0000ff',\n        'stroke-width': 3\n    }\n}\n```\n\nThis results in the following custom glyph: ![Custom Glyph Thick](/docs/img/completeCustomThick.png)\n\nTo dynamically generate glyphs, provide a function for attributes or styles. For example, to scale the stroke-width by the size of the cell:\n\n```javascript\nDataTypeValue: {\n    attrs: {\n        d: function (value, width, height) {\n            return 'M0,0L' + width + ',' + height;\n        }\n    },\n    styles: {\n        stroke: '#0000ff',\n        'stroke-width': function (data, width, height) {\n            return Math.floor(Math.sqrt(width * height) / 10);\n        }\n    }\n}\n```\n\nThis results in the following scalable custom glyph: ![Custom Glyph Scaled](/docs/img/completeRendererScaled.png)\n\n#### Server-Side SVG Rastering\n\nServer-side scripts should handle SVG file uploads, use a tool such as Apache Batik or CairoSVG to rasterize them, and return a link where the new image can be retrieved.\nA simple PHP implementation:\n\n```php\n\u003c ?php\n\t$fileName = $_FILES['data']['tmp_name'];\n\t$batikPath = 'batik/batik-rasterizer.jar';\n\t$downloadLink = 'retrieve.php?token=' . $fileName;\n\n\tif (is_uploaded_file($fileName)) {\n\t\texec('java -jar ' . $batikPath . ' -d /tmp/' . $fileName . '.png ' . $fileName);\n\t\techo $downloadLink;\n\t} else {\n\t\theader('400 Bad Request', true, 400);\n\t}\n?\u003e\n```\n\n...and:\n\n```php\n\u003c ?php\n\t$fileName = '/tmp/' . $_GET['token'];\n\tif (file_exists($fileName)) {\n\t\theader('Content-Type: image/png');\n\t\theader('Content-Disposition: attachment; filename=' . $fileName);\n\t\theader('Pragma: no-cache');\n\t\treadfile($fileName);\n\t} else {\n\t \theader('410 File Not Found', true, 410);\n\t}\n?\u003e\n```\n\n### Options\nGridVar built using the [jQuery UI Widget Factory][jquery-ui-widget-factory].  The following options are provided for supplying data to and customizing GridVar.\n\n#### `cellHeight` (optional)\n\n* type: Number\n* default: 12px\n\nHeight in pixels of each cell and height of the rows.\n\n#### `cellTip` (optional)\n\n* type: Function\n* default: undefined\n\nFunction that is called to fill in the 'title' field of each cell. This function will have one parameter, function(cellData), that contains a row of data as provided by the dataMapping option. For example, this may look like:\n\n```javascript\nfunction(cellData) {\n\treturn ['\u003cstrong\u003e',cellData.join(', '),'\u003c/strong\u003e'].join('');\n}\n```\n\nIf qtip is available, then this is displayed as a tooltip when the user hovers over the cell.\n\n#### `cellWidth` (optional)\n* type: Number\n* default: 12\n\nWidth in pixels of each cell and width of the columns.\n\n#### `columnKeysToLabel` (optional)\n* type: Object\n* default: undefined\n\nObject that maps column key to the column display name. If this isn't provided, the column key will be displayed.\n\n```javascript\nvar columnKeysToLabel = {\n\t4235: 'This is a column label',\n\tmyKey: 'Column Label'\n};\n```\n\n#### `columnOrder`\n* type: Array of Strings\n* default: undefined\n\nOrdered array of the keys of the column data. These should be consistent across the dataset itself and the data mappings. Updating this option animates the reordering. Example:\n\n```javascript\n$('#gridVar').gridVar('option', 'columnOrder',\n\t['firstColumnKey', 'secondColumnKey', 'thirdColumnKey']);\n```\n\n#### `dataDisplayMapping`\n* type: Object\n* default: undefined\n\nAn array of objects that maps the data type to either a user-provided glyph drawing function, built-in glyph, or a color mapping--the visual encoding. Each of these objects has 3 fields: `dataType`, `mappings`, and `labelMapping`.\n\nThe `dataType` field corresponds to the dataIndex (see the dataMapping option) and this indicates for which data this mapping encodes.\n\nThe `mappings` field translates the data value to either a color or a glyph. Colors are the hex encoding and start with a #. Glyphs defined by a string value, shown in the Renderers table below (ex. 'xRenderer'), or a user function that returns an SVG path given the value, cell width, and cell height. For example:\n\n```javascript\nmappings: {\n\thighValue: function(value, width, height){\n\t\treturn 'M0,0L' + width + ',' + height;\n\t}\n};\n```\n\nThe 'labelMapping' is optional and is used for displaying text on the legend. If you find that the data value would be better displayed in a different format, you can specify the translation in a map from key to field. For example:\n\n```javascript\nvar labelMapping = {\n\tlow: 'Low Value',\n\thigh: 'High',\n\tunknown: 'Unknown'\n};\n```\n\nAltogether, this might look like:\n\n```javascript\nvar mappings = [{\n    dataType: 'mutation',\n    mappings: {\n        missense: '#FEC44F',\n        nonsense: '#ADDD8E',\n        unknown: '#b1b1b1'\n    },\n    labelMapping: {\n    \tmissense: 'Missense Mutation',\n    \tnonsense: 'Nonsense Mutation',\n    \tunknown: 'Unknown'\n    }\n},\n{\n    dataType: 'copyNumber',\n    mappings: {\n        amplified: function(value, width, height){\n        \treturn 'M0,0L' + width + ',' + height;\n       \t},\n        deleted: 'minusRenderer',\n        none: { attrs: {d : 'circleRenderer'} , styles : { stroke: 'black'}}\n    },\n    labelMapping: {\n    \tamplified: 'Amplified',\n    \tdeleted: 'Deleted',\n    \tnone: 'Unknown'\n    }\n}\n];\n```\n\nFor more details see Renderers\n\n#### `dataMapping`\n* value: Object\n* default: undefined\n\nThis object holds a data index mapping and the dataset. `dataIndex` maps `dataType` to the array position of the\narrays provided to `data`. The data index must have `rowKey` and `columnKey` fields. For example:\n\n```javascript\nvar dataIndex = {\n\trowKey: 0, // position 0\n \tcolumnKey: 1,\n \tcopyNumber: 2,\n \tmutation: 3\n};\n```\n\nThe `data` field points to an array of arrays of data. The innermost array corresponds to a row of data with row and\ncolumn keys along with the actual data fields that you, for example, paired with the 'dataIndex' above, the data might look like:\n\n```javascript\nvar data = [\n \t['23123', 'TCGA-23123', ['amplified'], ['missense']],\n \t['94982', 'TCGA-SAMPL', ['deleted'], ['nonsense']],\n \t['55555', 'TCGA-DSJEN', ['neutral'], ['missense']]\n];\n```\n\nThe `dataMapping` wraps the above variables into the fields `dataIndex` and `data`.\n\n```javascript\nvar dataMapping = {\n\tdata: data,\n\tdataIndex: dataIndex\n};\n```\n\n#### `exportOptions` (optional)\n* type: Object\n* default: undefined\n\nParameters that specify GridVar's internal SVG rendering and external PNG rasterizing capabilities. Supply a CSS\nstylesheet to enable SVG export and a server-side script to enable PNG transcoding in addition to the optional libraries\nin the panel to the right. Download links appear above the legend, if and only if the following options are defined.\n\n```javascript\nexportOptions: {\n\tstyle: 'GridVar/plugin/gridvar.css',\n\tserver: 'upload.php'\n}\n```\n\n#### `histogramMapping` (optional)\n* type: Object\n* default: undefined\n\nLike the `dataMapping` option, this option maps the optional histogram data to the rows. It also includes an\noptional `label` that will be displayed at the bottom of the histogram. The `data` field maps a row key to a\npercent value. For example:\n\n```javascript\nvar histogramMapping = {\n    data: {\n    \tmyRowKey: 0.24, // 24%\n    \tanotherRowKey: 1.0 // 100%\n   \t},\n    label: 'Frequency'\n};\n```\n\n#### `multipleLegendLines` (optional)\n* type: Object\n* default: undefined\n\nObject with two values: a boolean to determine if the legend will be split into multiple lines, one for each category,\nand an array of labels for each of those categories.\n\n```javascript\nvar multipleLegendLines = {\n    include: true,\n    labels: ['Temperature: ', 'Cloud Levels: ']\n};\n```\n\n#### `rowKeysToLabel` (optional)\n* type: Object\n* default: undefined\n\nObject that maps row key to the column display name. If this isn't provided, the row key will be displayed.\n\n```javascript\nvar rowKeysToLabel = {\n\t4235: 'This is a row label',\n\tmyRowKey: 'Row Label'\n};\n```\n\n#### `rowOrder`\n* type: Array of Strings\n* default: undefined\n\nOrdered array of the keys of the row data. These should be consistent across the dataset itself and the data mappings. Updating this option animates the reordering. Example:\n\n```javascript\n$('#gridVar').gridVar('option', 'rowOrder', ['firstRowKey', 'firstRowKey', 'firstRowKey']);\n```\n\n### Events\n\n#### `columnLabelClicked`\n* parameters: `event`:Event, `columnKey`:String\n\nThis is fired when a column label is clicked. `event` is a jQuery Event. `columnKey` is the key that identifies that column.\n\n#### `rowLabelClicked`\n* parameters: `event`:Event, `rowKey`:String\n\nThis is fired when a row label is clicked. `event` is a jQuery Event. `rowKey` is the key that identifies that row.\n\n### Renderers\n\nThe following built-in renderers are available for displaying glyphs within cells.\n\n* `circleRenderer`: ![Circle Glyph](/docs/img/circleGlyph.png)\n* `dotRenderer`: ![Dot Glyph](/docs/img/dotGlyph.png)\n* `minusRenderer`: ![Minus Glyph](/docs/img/minusGlyph.png)\n* `plusRenderer`: ![Plus Glyph](/docs/img/plusGlyph.png)\n* `rectRenderer`: ![Rectangle Glyph](/docs/img/rectGlyph.png)\n* `xRenderer`: ![X Glyph](/docs/img/xGlyph.png)\n\nIssues\n------\n\nIf you find bugs or have feature requests, please create [issues][issues] on GitHub.\n\nTesting\n-------\n\nTests are written using [QUnit][qunit]. Open the test page (/src/tests/qunit-test.html) in a web browser to run the tests in the browser, or run `$ grunt test` to run the test suite with PhantomJS. Visual tests can be inspected by opening the visual test page (/src/tests/visual-test.html) in a browser.\n\nDevelopers\n----------\n\nBefore building and testing GridVar, install dependencies using `$ npm install`. The following tasks can be run using [Grunt][grunt]:\n\n* `grunt build` – Builds GridVar from source, generates a minified source, generates CSS using [Compass][compass], runs linting, and runs tests.\n* `grunt lint` – Runs source and test files through JSHint.\n* `grunt test` – Runs the test suite with PhantomJS.\n\nLicense\n-------\n\nCopyright 2014 [Novartis Institutes for BioMedical Research, Inc.][nibr].\n\nLicensed under the BSD 3-Clause License.\n\n\u003c!-- NIBR links --\u003e\n[examples]: http://opensource.nibr.com/gridvar/\n[nibr]: http://nibr.com\n\n\u003c!-- assets --\u003e\n[zipball]: https://github.com/Novartis/gridvar/releases/download/v1.0.0/jquery.nibrGridVar.js.zip\n\n\u003c!-- github links --\u003e\n[issues]: http://github.com/Novartis/gridvar/issues\n\n\u003c!-- deep links --\u003e\n[built-in-renderers]: #built-in-renderers\n[custom-renderers]: #custom-renderers\n\n\u003c!-- links to third party projects --\u003e\n[jQuery]: http://jquery.com/\n[jquery-ui-widget-factory]: http://jqueryui.com/widget/\n[jquery-ui]: http://jqueryui.com/\n[d3]: https://github.com/mbostock/d3\n[qunit]: http://qunitjs.com/\n[underscore]: http://underscorejs.org/\n[qtip]: http://qtip2.com/download\n[filesaver]: https://github.com/eligrey/FileSaver.js/\n[blob]: https://github.com/eligrey/Blob.js/\n[compass]: http://compass-style.org/\n[svg-path]: http://www.w3schools.com/svg/svg_path.asp\n[svg-edit]: https://code.google.com/p/svg-edit/\n[grunt]: http://gruntjs.com/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnovartis%2Fgridvar","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnovartis%2Fgridvar","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnovartis%2Fgridvar/lists"}