Charting library for The Phillipian's annual State of the Academy survey project by Samson Zhang EDE CXLII (@wwsalmon) and Anthony Kim Digital Editor CXLII,CXLIII (@createandbuild). Built on d3.
-
Include d3.js and masonry.js (to use createSections, section selectors, and sotaMasonry), as well as
dist/sota.min.js, in your<head>:<script src="PATH/TO/d3.min.v5.js"></script> <script src="PATH/TO/masonry.pkgd.min.js"></script> <script src="PATH/TO/sota.min.js"></script>Or, using CDNs:
<script src="https://unpkg.com/d3@5.16.0/dist/d3.min.js"></script> <script src="https://unpkg.com/masonry-layout@4/dist/masonry.pkgd.min.js"></script> <script src="PATH/TO/sota.min.js"></script> -
In your app or index js, configure
sotaConfigand call setup functions likesetColorsandsetStyles, andcreateSectionsandsotaNavbarif desired. As an example, here is a snippet fromdemo/index.js:// required for graphs to look okay -- specify at minimum a slug and array of colors sota.sotaConfig.sections = [ {"slug": "sotajs", "name": "sota.js", "colors": sota.colorInterpolate("#222222")}, {"slug": "politics", "name": "Politics & Worldview", "blurb": "test blurb", "colors": sota.colorInterpolate("#660066", "#dac7d8", 5, true)}, {"slug": "wellness", "name": "Health & Wellness", "colors": sota.colorInterpolate("#6cb643", "#cae3cb", 5, true)}, {"slug": "discipline", "name": "Discipline", "colors": sota.colorInterpolate("#b43432", "#f0d1ca", 5, true)} ] // required for graphs to look okay -- call functions to inject color, style CSS based on sotaConfig sota.setColors(sota.sotaConfig); sota.setStyles(sota.sotaConfig); // required only if you want to generate default layout containers. Can also specify directly through HTML and use selectors for graphs sota.createSections(sota.sotaConfig); // optional, render navbar based on sotaConfig.sections // make sure you call createSections first! sota.sotaNavbar(sota.sotaConfig, "sota.js Demo", "szlogo.png", false, "https://www.samsonzhang.com/");See usage for specifics on these functions.
-
After calling setup functions, call all the chart-rendering functions you want inside
window.onload(to ensure that these functions can find containers and selectors being dynamically created). After all your chart-rendering functions, callsotaMasonryto arrange the layout.See usage for specifics on these functions, as well as each of the chart-rendering functions.
// render graphs inside window.onload so they will be able to find parent containers dynamically created above window.onload = () => { sota.barChart({title: "What does a graph look like?", subtitle: "Here's a bar chart", section: "sotajs", dataFile: "data/ethnicity", totalResp: 1052, maxVal: true, displayPercentage: true}); sota.multiLineGraph({section: "sotajs", title: "Multilinegraph", dataFile: "data/gpaXincome", maxVal: 30}); ... sota.stackedColumnChart({ section: "politics", title: "Reverse Racism Percentage by Gender", subtitle: "Do you believe that reverse racism exists?", dataFile: "data/reverse-racism-gender", totalResp: 1032 }); // after everything has loaded, use Masonry to fix up layout sota.sotaMasonry(); }If you're not using
sota-sectionparent containers or if you're using selectors that are hard-coded rather than dynamically created, you can foregowindow.onloadandsotaMasonry.
I haven't tested using npm and believe there are some problems with dependencies, so I would advise against using npm for now.
Run:
npm i sota.js
d3 and masonry are dependencies, so you don't have to worry about them separately.
In your app, you can now use the functions of the sota object just as you would in plain js.
- barChart(dataFile, [selector], [section], [title], [subtitle], [inputIsPercentage], [showXAxis], [showSeparators], [displayPercentage], [totalResp], [maxVal], [minVal], [margin])
Render sota.js bar chart
- bigNumber(title, number, subtitle, [selector], [section])
Render big number with subtitle. Not really a chart, no SVG involved, but using JS helps keep ordering correct
- columnChart(dataFile, [selector], [section], [title], [subtitle], [inputIsPercentage], [displayPercentage], [totalResp], [maxVal], [minVal], [mainHeight], [showLegend], [margin])
Render sota.js column chart
- contentModule(title, content, subtitle, [selector], [section])
Render big number with subtitle. Not really a chart, no SVG involved, but using JS helps keep ordering correct
- customBarChart(dataFile, [selector], [section], [title], [subtitle], shapeFile, shapeWidth, [inputIsPercentage], [margin])
Render sota.js custom bar chart, using an SVG path as the base
- customColumnChart(dataFile, [selector], [section], [title], [subtitle], shapeFile, shapeHeight, [inputIsPercentage], [margin])
Render sota.js custom column chart, using an SVG path as the base
- groupedBarChart(dataFile, [selector], [section], [title], [subtitle], [inputIsPercentage], [displayPercentage], [totalResp], [maxVal], [minVal], [margin])
Render sota.js grouped bar chart
- lineGraph(dataFile, [selector], [section], [title], [subtitle], [inputIsPercentage], [maxVal], [minVal], [margin], [height])
Render sota.js line graph
- multiLineGraph(dataFile, [selector], [section], [title], [subtitle], [inputIsPercentage], [displayPercentage], [maxVal], [minVal], [height], [showLegend], [margin])
- pieChart(dataFile, [selector], [section], [title], [subtitle], [inputIsPercentage], [sorted], [pieRad], [pieThick], [margin])
Render sota.js pie chart
- stackedBarChart(dataFile, [selector], [section], [title], [subtitle], [inputIsPercentage], [showXAxis], [labelStyle], [groupLabelStyle], [showLegend], [margin])
Render sota.js stacked bar chart
- stackedColumnChart(dataFile, [selector], [section], [title], [subtitle], [inputIsPercentage], [displayPercentage], [maxVal], [minVal], [mainHeight], [margin])
Render sota.js stacked column chart
- sotaMasonry()
Function to generate masonry layout on sota containers and modules
- sotaNavbar(sotaConfig, [text], [logo], [textLink], [logoLink])
Function to render navbar. Run after createSections
- createSections(sotaConfig)
Function to render sections. Run before sotaNavbar
- setStyles(sotaConfig)
Function to inject inline styling for sota charts, navbar, layout, etc.
- setColors(sotaConfig)
Function to set colors for sota charts, layout, navbar, etc.
- colorInterpolate(start, [end], [steps], [includeLast])
Function that generates an array of hex codes interpolating between start and end hex codes
barChart(dataFile, [selector], [section], [title], [subtitle], [inputIsPercentage], [showXAxis], [showSeparators], [displayPercentage], [totalResp], [maxVal], [minVal], [margin])
Render sota.js bar chart
Kind: global function
| Param | Type | Default | Description |
|---|---|---|---|
| dataFile | string |
Relative path to csv data file, excluding file extension, i.e. "data/datafile" | |
| [selector] | string |
Either this or section param is required. Query selector for container div to render chart in, i.e. "#selector." | |
| [section] | string |
Either this or selector param is required. Slug for section to add .sota-module container and chart to | |
| [title] | string |
Title to be rendered in h3 tag. Only rendered if section param is used and not selector | |
| [subtitle] | string |
Subtitle to be rendered in .sota-subtitle div. Only rendered if section param is used and not selector | |
| [inputIsPercentage] | boolean |
false |
Whether or not input data is in percentages |
| [showXAxis] | boolean |
true |
Whether or not to render x axis |
| [showSeparators] | boolean |
true |
Whether or not to show separators between bars |
| [displayPercentage] | boolean |
true |
Whether to display percentage or value on bar |
| [totalResp] | number |
Number of total responses. Specify if categories are non-exclusive, i.e. if there are less total items than the sum of data points. | |
| [maxVal] | number | boolean |
By default, either 100 for percentages or max of data for non-percentages is used as scale maximum value. If maxVal is set to true, max of dataset is used for percentages instead of 100. If a number is specified, that number is used as the max. | |
| [minVal] | number | boolean |
By default, either 0 for percentages or min of data for non-percentages is used as scale minimum value. If minVal is set to true, min of dataset is used for percentages instead of 0. If a number is specified, that number is used as the min. | |
| [margin] | Object |
Object containing top, left, bottom, right margins for chart. Defaults to values from sotaConfig |
Render big number with subtitle. Not really a chart, no SVG involved, but using JS helps keep ordering correct
Kind: global function
| Param | Type | Description |
|---|---|---|
| title | string |
Title to be rendered in h3 tag |
| number | string |
Number to be rendered in .sota-big |
| subtitle | string |
Subtitle to follow number |
| [selector] | string |
Either this or section param is required. Query selector for container div to render chart in, i.e. "#selector." |
| [section] | string |
Either this or selector param is required. Slug for section to add .sota-module container and chart to |
columnChart(dataFile, [selector], [section], [title], [subtitle], [inputIsPercentage], [displayPercentage], [totalResp], [maxVal], [minVal], [mainHeight], [showLegend], [margin])
Render sota.js column chart
Kind: global function
| Param | Type | Default | Description |
|---|---|---|---|
| dataFile | string |
Relative path to csv data file, excluding file extension, i.e. "data/datafile" | |
| [selector] | string |
Either this or section param is required. Query selector for container div to render chart in, i.e. "#selector." | |
| [section] | string |
Either this or selector param is required. Slug for section to add .sota-module container and chart to | |
| [title] | string |
Title to be rendered in h3 tag. Only rendered if section param is used and not selector | |
| [subtitle] | string |
Subtitle to be rendered in .sota-subtitle div. Only rendered if section param is used and not selector | |
| [inputIsPercentage] | boolean |
false |
Whether or not input data is in percentages |
| [displayPercentage] | boolean |
true |
Whether to display percentage or values on axis |
| [totalResp] | number |
Number of total responses. Specify if categories are non-exclusive, i.e. if there are less total items than the sum of data points. | |
| [maxVal] | number | boolean |
By default, either 100 for percentages or max of data for non-percentages is used as scale maximum value. If maxVal is set to true, max of dataset is used for percentages instead of 100. If a number is specified, that number is used as the max. | |
| [minVal] | number | boolean |
By default, either 0 for percentages or min of data for non-percentages is used as scale minimum value. If minVal is set to true, min of dataset is used for percentages instead of 0. If a number is specified, that number is used as the min. | |
| [mainHeight] | number |
Height of the chart. Defaults to value from sotaConfig | |
| [showLegend] | boolean |
false |
Whether to show legend or bottom text labels |
| [margin] | Object |
Object containing top, left, bottom, right margins for chart. Defaults to values from sotaConfig |
Render big number with subtitle. Not really a chart, no SVG involved, but using JS helps keep ordering correct
Kind: global function
| Param | Type | Description |
|---|---|---|
| title | string |
Title to be rendered in h3 tag |
| content | string |
HTML conetnt to be rendered beneath subtitle |
| subtitle | string |
Subtitle to follow number |
| [selector] | string |
Either this or section param is required. Query selector for container div to render chart in, i.e. "#selector." |
| [section] | string |
Either this or selector param is required. Slug for section to add .sota-module container and chart to |
customBarChart(dataFile, [selector], [section], [title], [subtitle], shapeFile, shapeWidth, [inputIsPercentage], [margin])
Render sota.js custom bar chart, using an SVG path as the base
Kind: global function
| Param | Type | Default | Description |
|---|---|---|---|
| dataFile | string |
Relative path to csv data file, excluding file extension, i.e. "data/datafile" | |
| [selector] | string |
Either this or section param is required. Query selector for container div to render chart in, i.e. "#selector." | |
| [section] | string |
Either this or selector param is required. Slug for section to add .sota-module container and chart to | |
| [title] | string |
Title to be rendered in h3 tag. Only rendered if section param is used and not selector | |
| [subtitle] | string |
Subtitle to be rendered in .sota-subtitle div. Only rendered if section param is used and not selector | |
| shapeFile | string |
Relative path to svg shape file, excluding file extension, i.e. "shapes/shapefile" | |
| shapeWidth | number |
Width of shape for chart | |
| [inputIsPercentage] | boolean |
false |
Whether or not input data is in percentages |
| [margin] | Object |
Object containing top, left, bottom, right margins for chart. Defaults to values from sotaConfig |
customColumnChart(dataFile, [selector], [section], [title], [subtitle], shapeFile, shapeHeight, [inputIsPercentage], [margin])
Render sota.js custom column chart, using an SVG path as the base
Kind: global function
| Param | Type | Default | Description |
|---|---|---|---|
| dataFile | string |
Relative path to csv data file, excluding file extension, i.e. "data/datafile" | |
| [selector] | string |
Either this or section param is required. Query selector for container div to render chart in, i.e. "#selector." | |
| [section] | string |
Either this or selector param is required. Slug for section to add .sota-module container and chart to | |
| [title] | string |
Title to be rendered in h3 tag. Only rendered if section param is used and not selector | |
| [subtitle] | string |
Subtitle to be rendered in .sota-subtitle div. Only rendered if section param is used and not selector | |
| shapeFile | string |
Relative path to svg shape file, excluding file extension, i.e. "shapes/shapefile" | |
| shapeHeight | number |
Height of shape for chart | |
| [inputIsPercentage] | boolean |
false |
Whether or not input data is in percentages |
| [margin] | Object |
Object containing top, left, bottom, right margins for chart. Defaults to values from sotaConfig |
groupedBarChart(dataFile, [selector], [section], [title], [subtitle], [inputIsPercentage], [displayPercentage], [totalResp], [maxVal], [minVal], [margin])
Render sota.js grouped bar chart
Kind: global function
| Param | Type | Default | Description |
|---|---|---|---|
| dataFile | string |
Relative path to csv data file, excluding file extension, i.e. "data/datafile" | |
| [selector] | string |
Either this or section param is required. Query selector for container div to render chart in, i.e. "#selector." | |
| [section] | string |
Either this or selector param is required. Slug for section to add .sota-module container and chart to | |
| [title] | string |
Title to be rendered in h3 tag. Only rendered if section param is used and not selector | |
| [subtitle] | string |
Subtitle to be rendered in .sota-subtitle div. Only rendered if section param is used and not selector | |
| [inputIsPercentage] | boolean |
false |
Whether or not input data is in percentages |
| [displayPercentage] | boolean |
true |
Whether to display percentage or value on axis |
| [totalResp] | number |
Number of total responses. Specify if categories are non-exclusive, i.e. if there are less total items than the sum of data points. | |
| [maxVal] | number | boolean |
By default, either 100 for percentages or max of data for non-percentages is used as scale maximum value. If maxVal is set to true, max of dataset is used for percentages instead of 100. If a number is specified, that number is used as the max. | |
| [minVal] | number | boolean |
By default, either 0 for percentages or min of data for non-percentages is used as scale minimum value. If minVal is set to true, min of dataset is used for percentages instead of 0. If a number is specified, that number is used as the min. | |
| [margin] | Object |
Object containing top, left, bottom, right margins for chart. Defaults to values from sotaConfig |
lineGraph(dataFile, [selector], [section], [title], [subtitle], [inputIsPercentage], [maxVal], [minVal], [margin], [height])
Render sota.js line graph
Kind: global function
| Param | Type | Default | Description |
|---|---|---|---|
| dataFile | string |
Relative path to csv data file, excluding file extension, i.e. "data/datafile" | |
| [selector] | string |
Either this or section param is required. Query selector for container div to render chart in, i.e. "#selector." | |
| [section] | string |
Either this or selector param is required. Slug for section to add .sota-module container and chart to | |
| [title] | string |
Title to be rendered in h3 tag. Only rendered if section param is used and not selector | |
| [subtitle] | string |
Subtitle to be rendered in .sota-subtitle div. Only rendered if section param is used and not selector | |
| [inputIsPercentage] | boolean |
false |
Whether or not input data is in percentages |
| [maxVal] | number | boolean |
By default, either 100 for percentages or max of data for non-percentages is used as scale maximum value. If maxVal is set to true, max of dataset is used for percentages instead of 100. If a number is specified, that number is used as the max. | |
| [minVal] | number | boolean |
By default, either 0 for percentages or min of data for non-percentages is used as scale minimum value. If minVal is set to true, min of dataset is used for percentages instead of 0. If a number is specified, that number is used as the min. | |
| [margin] | Object |
Object containing top, left, bottom, right margins for chart. Defaults to values from sotaConfig | |
| [height] | number |
300 |
Height of the chart. Defaults to 300 |
multiLineGraph(dataFile, [selector], [section], [title], [subtitle], [inputIsPercentage], [displayPercentage], [maxVal], [minVal], [height], [showLegend], [margin])
Kind: global function
| Param | Type | Default | Description |
|---|---|---|---|
| dataFile | string |
Relative path to csv data file, excluding file extension, i.e. "data/datafile" | |
| [selector] | string |
Either this or section param is required. Query selector for container div to render chart in, i.e. "#selector." | |
| [section] | string |
Either this or selector param is required. Slug for section to add .sota-module container and chart to | |
| [title] | string |
Title to be rendered in h3 tag. Only rendered if section param is used and not selector | |
| [subtitle] | string |
Subtitle to be rendered in .sota-subtitle div. Only rendered if section param is used and not selector | |
| [inputIsPercentage] | boolean |
false |
Whether or not input data is in percentages |
| [displayPercentage] | boolean |
true |
Whether to display percentage or value on axis |
| [maxVal] | number | boolean |
By default, either 100 for percentages or max of data for non-percentages is used as scale maximum value. If maxVal is set to true, max of dataset is used for percentages instead of 100. If a number is specified, that number is used as the max. | |
| [minVal] | number | boolean |
By default, either 0 for percentages or min of data for non-percentages is used as scale minimum value. If minVal is set to true, min of dataset is used for percentages instead of 0. If a number is specified, that number is used as the min. | |
| [height] | number |
300 |
Height of the graph |
| [showLegend] | boolean |
true |
Whether or not to show legend |
| [margin] | Object |
Object containing top, left, bottom, right margins for chart. Defaults to values from sotaConfig |
pieChart(dataFile, [selector], [section], [title], [subtitle], [inputIsPercentage], [sorted], [pieRad], [pieThick], [margin])
Render sota.js pie chart
Kind: global function
| Param | Type | Default | Description |
|---|---|---|---|
| dataFile | string |
Relative path to csv data file, excluding file extension, i.e. "data/datafile" | |
| [selector] | string |
Either this or section param is required. Query selector for container div to render chart in, i.e. "#selector." | |
| [section] | string |
Either this or selector param is required. Slug for section to add .sota-module container and chart to | |
| [title] | string |
Title to be rendered in h3 tag. Only rendered if section param is used and not selector | |
| [subtitle] | string |
Subtitle to be rendered in .sota-subtitle div. Only rendered if section param is used and not selector | |
| [inputIsPercentage] | boolean |
false |
Whether or not input data is in percentages |
| [sorted] | boolean |
true |
Whether or not to sort order of slices by size |
| [pieRad] | number |
150 |
Radius of pie in chart |
| [pieThick] | number |
80 |
Thickness of pie slices (this is actually a donut chart) |
| [margin] | Object |
Object containing top, left, bottom, right margins for chart. Defaults to values from sotaConfig |
stackedBarChart(dataFile, [selector], [section], [title], [subtitle], [inputIsPercentage], [showXAxis], [labelStyle], [groupLabelStyle], [showLegend], [margin])
Render sota.js stacked bar chart
Kind: global function
| Param | Type | Default | Description |
|---|---|---|---|
| dataFile | string |
Relative path to csv data file, excluding file extension, i.e. "data/datafile" | |
| [selector] | string |
Either this or section param is required. Query selector for container div to render chart in, i.e. "#selector." | |
| [section] | string |
Either this or selector param is required. Slug for section to add .sota-module container and chart to | |
| [title] | string |
Title to be rendered in h3 tag. Only rendered if section param is used and not selector | |
| [subtitle] | string |
Subtitle to be rendered in .sota-subtitle div. Only rendered if section param is used and not selector | |
| [inputIsPercentage] | boolean |
false |
Whether or not input data is in percentages |
| [showXAxis] | boolean |
true |
Whether or not to render x axis |
| [labelStyle] | "none" | "onBar" | "aboveBar" |
"onBar" |
Style of labels for sub-groups (slices of bars). None hides all labels. onBar displays values on the bars, and hides any that don’t fit. aboveBar draws labels above the bar with pointing lines |
| [groupLabelStyle] | "none" | "onBar" |
"none" |
Style of labels for groups. None hides all labels. onBar displays labels above bars |
| [showLegend] | boolean |
true |
Whether or not to show legend |
| [margin] | Object |
Object containing top, left, bottom, right margins for chart. Defaults to values from sotaConfig |
stackedColumnChart(dataFile, [selector], [section], [title], [subtitle], [inputIsPercentage], [displayPercentage], [maxVal], [minVal], [mainHeight], [margin])
Render sota.js stacked column chart
Kind: global function
| Param | Type | Default | Description |
|---|---|---|---|
| dataFile | string |
Relative path to csv data file, excluding file extension, i.e. "data/datafile" | |
| [selector] | string |
Either this or section param is required. Query selector for container div to render chart in, i.e. "#selector." | |
| [section] | string |
Either this or selector param is required. Slug for section to add .sota-module container and chart to | |
| [title] | string |
Title to be rendered in h3 tag. Only rendered if section param is used and not selector | |
| [subtitle] | string |
Subtitle to be rendered in .sota-subtitle div. Only rendered if section param is used and not selector | |
| [inputIsPercentage] | boolean |
false |
Whether or not input data is in percentages |
| [displayPercentage] | boolean |
true |
Whether to display percentage or value on axis |
| [maxVal] | number | boolean |
By default, either 100 for percentages or max of data for non-percentages is used as scale maximum value. If maxVal is set to true, max of dataset is used for percentages instead of 100. If a number is specified, that number is used as the max. | |
| [minVal] | number | boolean |
By default, either 0 for percentages or min of data for non-percentages is used as scale minimum value. If minVal is set to true, min of dataset is used for percentages instead of 0. If a number is specified, that number is used as the min. | |
| [mainHeight] | number |
Height of the chart. Defaults to value from sotaConfig | |
| [margin] | Object |
Object containing top, left, bottom, right margins for chart. Defaults to values from sotaConfig |
Function to generate masonry layout on sota containers and modules
Function to render navbar. Run after createSections
Kind: global function
| Param | Type | Default | Description |
|---|---|---|---|
| sotaConfig | sotaConfig object | ||
| [text] | string | boolean |
false |
Text to display in navbar |
| [logo] | string | boolean |
false |
Relative path to logo to display in navbar |
| [textLink] | string | boolean |
false |
Link for navbar text |
| [logoLink] | string | boolean |
false |
Link for navbar logo |
Function to render sections. Run before sotaNavbar
Kind: global function
| Param | Description |
|---|---|
| sotaConfig | sotaConfig object |
Function to inject inline styling for sota charts, navbar, layout, etc.
Kind: global function
| Param | Description |
|---|---|
| sotaConfig | sotaConfig object |
Function to set colors for sota charts, layout, navbar, etc.
Kind: global function
| Param | Description |
|---|---|
| sotaConfig | sotaConfig object |
Function that generates an array of hex codes interpolating between start and end hex codes
Kind: global function
| Param | Type | Default | Description |
|---|---|---|---|
| start | string |
6-digit hex code for starting color, including "#" at beginning | |
| [end] | string |
"#ffffff" |
6-digit hex code for ending color, including "#" at beginning |
| [steps] | number |
8 |
Number of steps, equal to the length of the returned array |
| [includeLast] | boolean |
false |
Whether or not to include the given end value in the final array |