- \n
.from_csv(as_string_or_file)<\/code> This is always a class method which produces one or more instances, with data pulled from the CSV content found inas_string_or_file<\/code>.<\/li>\n.from_csv_in_rows(as_string_or_file)<\/code> This is always a class method which produces one instance for every row in the CSV (as_string_or_file<\/code>).<\/li>\n.load_from_csv(as_string_or_file)<\/code> This is an instance method which updates an instance with data read from theas_string_or_file<\/code> argument.<\/li>\n<\/ul>\nTip<\/b><\/p>\n
All three of these standard methods are packaged to have batteries included. This means that for simple use cases, you can simply pass a CSV to the method, and the method wlil attempt to determine the best way to deserialize the CSV into the appropriate Highcharts for Python<\/b> objects.<\/p>\n
However, if you find that you need more fine-grained control, the methods provide powerful tools to give you the control you need when you need it.<\/i><\/p>\n
These standard methods – with near-identical syntax – are available:<\/p>\n
- \n
- On all
series<\/code> classes (descended fromSeriesBase<\/code>)<\/li>\n- On the
Chart<\/code> class<\/li>\n<\/ul>\nPreparing Your CSV Data<\/h3>\n
So let\u2019s try a real-world example. Let\u2019s say you\u2019ve got some annual population counts stored in a CSV file named
'census-time-series.csv'<\/code> that looks like this:
\n![\"table](\"https:\/\/wp-assets.highcharts.com\/www-highcharts-com\/blog\/wp-content\/uploads\/2023\/10\/17212217\/table-with-all-population-US-states-from-2011-to-2019.jpg\")
<\/p>\nThe first column contains the names of geographic regions, while each of the subsequent columns contains the population counts for a given year. Now, let\u2019s say we wanted to visualize this data in various ways.<\/p>\n
Creating the Chart: Chart.from_csv()<\/h2>\n
Relying on the Defaults<\/h3>\n
The simplest way to create a chart from a CSV file is to call
Chart.from_csv()<\/code> like so:<\/p>\nmy_chart = Chart.from_csv('census-time-series.csv',\r\n wrapper_character = '\"')\r\nmy_chart.display()<\/pre>\n![\"Simple](\"https:\/\/wp-assets.highcharts.com\/www-highcharts-com\/blog\/wp-content\/uploads\/2023\/10\/17193624\/Line-chart.jpg\")
<\/p>\nAs you can see, we haven\u2019t provided any more instructions besides telling it to generate a chart from the file
'census-time-series.csv'<\/code>, and to interpret a single quotation mark as a wrapper character. The result is a line chart, with one series for each year, and one point for each region.<\/p>\nTip<\/b><\/p>\n
Unless instructed otherwise, Highcharts for Python<\/b> will default to using a line chart.<\/i><\/p>\n
Setting the Series Type<\/h3>\n
Why don\u2019t we switch it to a bar chart?<\/p>\n
my_chart = Chart.from_csv('census-time-series.csv',\r\n series_type = 'bar',\r\n wrapper_character = '\"')<\/pre>\n![\"bar](\"https:\/\/wp-assets.highcharts.com\/www-highcharts-com\/blog\/wp-content\/uploads\/2023\/10\/17194007\/bar-chart-with-random-data.jpg\")
<\/p>\nNow the result is a little more readable, but still not great: After all, there are more than fifty geographic regions represented for each year, which makes the chart super crowded. Besides, maybe we\u2019re only interested in a specific year: 2019.<\/p>\n
Let\u2019s try focusing our chart.<\/p>\n
Basic Property Mapping<\/h3>\n
my_chart = Chart.from_csv('census-time-series.csv',\r\n series_type = 'bar',\r\n property_column_map = {\r\n 'x': 'Geographic Area',\r\n 'y': '2019'\r\n })<\/pre>\n![\"bar](\"https:\/\/wp-assets.highcharts.com\/www-highcharts-com\/blog\/wp-content\/uploads\/2023\/10\/17194236\/bar-chart-with-random-data-using-blue-color.jpg\")
<\/p>\nMuch better! We\u2019ve now added a
property_column_map<\/code> argument to the.from_csv()<\/code> method call. This argument tells Highcharts for Python how to map columns in your data to properties in the resulting chart. In this case, the keys'x'<\/code> and'y'<\/code> tell Highcharts for Python<\/b> that you want to map the'Geographic Area'<\/code> column to the resulting series\u2019 data points\u2019.x<\/code>, and to map the'2019'<\/code> column to the .y properties, respectively.<\/p>\nThe net result is that my_chart contains one BarSeries whose .data property contains a BarDataCollection instance populated with the data from the
'Geographic Area'<\/code> and ‘2019'<\/code> columns incensus-time-series.csv<\/code>.<\/p>\nBut maybe we actually want to compare a couple different years? Let\u2019s try that.<\/p>\n
Tip<\/b><\/p>\n
Not all CSV data contains a header row. If your CSV data does not contain a header row,
property_column_map<\/code> acceptsint<\/code> values, which indicate the index of the column that you want to map. So the method call above would be equivalent to:<\/p>\nmy_chart = Chart.from_csv('census-time-series.csv',\r\n series_type = 'bar',\r\n property_column_map = {\r\n 'x': 0,\r\n 'y': 10\r\n })<\/pre>\n<\/i><\/p>\n
Property Mapping with Multiple Series<\/h3>\n
my_chart = Chart.from_csv('census-time-series.csv',\r\n series_type = 'column',\r\n property_column_map = {\r\n 'x': 'Geographic Area',\r\n 'y': ['2017', '2018', '2019']\r\n })<\/pre>\n![\"Column](\"https:\/\/wp-assets.highcharts.com\/www-highcharts-com\/blog\/wp-content\/uploads\/2023\/10\/17194838\/Column-chart-with-random-data-using-blue-color.jpg\")
<\/p>\nNow we\u2019re getting somewhere! We\u2019ve added a list of column names to the
'y'<\/code> key in theproperty_column_map<\/code> argument. Each of those columns has now produced a separateBarSeries<\/code> instance – but they\u2019re all still sharing the'Geographic Area'<\/code> column as their.x<\/code> value.<\/p>\nNote<\/b><\/p>\n
You can supply multiple values to any property in the
property_column_map<\/code>. The example provided above is equivalent to:<\/p>\nmy_chart = Chart.from_csv('census-time-series.csv',\r\n series_type = 'column',\r\n property_column_map = {\r\n 'x': ['Geographic Area', 'Geographic Area', 'Geographic Area'],\r\n 'y': ['2017', '2018', '2019']\r\n })<\/pre>\nThe only catch is that the ultimate number of values for each key must match. If there\u2019s only one value, then it will get repeated for all of the others. But if there\u2019s a mismatch, then Highcharts for Python<\/b> will throw a
HighchartsCSVDeserializationError<\/code>.<\/i><\/p>\nBut so far, we\u2019ve only been using the
'x'<\/code> and'y'<\/code> keys in ourproperty_column_map<\/code>. What if we wanted to configure additional properties? Easy!<\/p>\nConfiguring Additional Properties<\/h3>\n
my_chart = Chart.from_csv('census-time-series.csv',\r\n series_type = 'bar',\r\n property_column_map = {\r\n 'x': 'Geographic Area',\r\n 'y': ['2017', '2018', '2019'],\r\n 'id': 'some other column'\r\n })<\/pre>\nNow, our CSV is pretty simple does not contain a column named “\u2019some other column\u2019. But *if* it did, then it would use that column to set the :meth:.id
<highcharts_core.options.series.data.bar.BarData.id><\/code>` property of each data point.<\/p>\nNote<\/b><\/p>\n
You can supply any property you want to the
property_map<\/code>. If the property is not supported by the series type you\u2019ve selected, then it will be ignored.<\/i><\/p>\nBut our chart is still looking a little basic – why don\u2019t we tweak some series configuration options?<\/p>\n
Configuring Series Options<\/h3>\n
my_chart = Chart.from_csv('census-time-series.csv',\r\n series_type = 'bar',\r\n property_column_map = {\r\n 'x': 'Geographic Area',\r\n 'y': ['2017', '2018', '2019'],\r\n },\r\n series_kwargs = {\r\n 'point_padding': 5\r\n })<\/pre>\n![\"Column](\"https:\/\/wp-assets.highcharts.com\/www-highcharts-com\/blog\/wp-content\/uploads\/2023\/10\/17201507\/Column-chart-using-data-from-the-table-above-US-gerographic-population.jpg\")
<\/p>\nAs you can see, we supplied a new
series_kwargs<\/code> argument to the.from_csv()<\/code> method call. This argument receives a dict with keys that correspond to properties on the series. In this case, by supplying'point_padding'<\/code> we have set the resultingBarSeries.point_padding<\/code> property to a value of0.25<\/code> – leading to a bit more spacing between the bars.<\/p>\nBut our chart is still a little basic – why don\u2019t we give it a reasonable title?<\/p>\n
Configuring Options<\/h3>\n
my_chart = Chart.from_csv('census-time-series.csv',\r\n series_type = 'bar',\r\n wrapper_character = '\"',\r\n property_column_map = {\r\n 'x': 'Geographic Area',\r\n 'y': ['2017', '2018', '2019']\r\n },\r\n series_kwargs = {\r\n 'point_padding': 5\r\n },\r\n options_kwargs = {\r\n 'title': {\r\n 'text': 'This Is My Chart Title'\r\n }\r\n })<\/pre>\n![\"Column](\"https:\/\/wp-assets.highcharts.com\/www-highcharts-com\/blog\/wp-content\/uploads\/2023\/10\/17201743\/Column-chart-with-a-title-using-data-from-the-table-above-US-gerographic-population.jpg\")
<\/p>\nAs you can see, we\u2019ve now given our chart a title. We did this by adding a new
options_kwargs<\/code> argument, which likewise takes a dict<\/code> with keys that correspond to properties on the chart\u2019sHighchartsOptions<\/code> configuration.`<\/p>\nNow let\u2019s say we wanted our chart to render in an HTML
<div><\/code> with an id of'my_target_div<\/code> – we can configure that in the same method call.<\/p>\nConfiguring Chart Setting<\/h3>\n
my_chart = Chart.from_csv('census-time-series.csv',\r\n series_type = 'bar',\r\n wrapper_character = '\"',\r\n property_column_map = {\r\n 'x': 'Geographic Area',\r\n 'y': ['2017', '2018', '2019'],\r\n },\r\n series_kwargs = {\r\n 'point_padding': 0.25\r\n },\r\n options_kwargs = {\r\n 'title': {\r\n 'text': 'This Is My Chart Title'\r\n }\r\n },\r\n chart_kwargs = {\r\n 'container': 'my_target_div'\r\n })<\/pre>\nWhile you can\u2019t really see the difference here, by adding the
chart_kwargs<\/code> argument to the method call, we now set the.container<\/code> property onmy_chart<\/code>.<\/p>\nBut maybe we want to do something a little different – like compare the change in population over time. Well, we can do that easily by visualizing each row of
census-time-series.csv<\/code> rather than each column.`<\/p>\nVisualizing Data in Rows<\/h2>\n
my_chart = Chart.from_csv('census-time-series.csv',\r\n series_type = 'line',\r\n series_in_rows = True,\r\n wrapper_character = '\"')<\/pre>\n![\"Line](\"https:\/\/wp-assets.highcharts.com\/www-highcharts-com\/blog\/wp-content\/uploads\/2023\/10\/17203041\/Line-chart-using-data-from-the-table-above-US-gerographic-population.jpg\")
<\/p>\nOkay, so here we removed some of the other arguments we\u2019d been using to simplify the example. You\u2019ll see we\u2019ve now added the
series_in_rows<\/code> argument, and set it toTrue<\/code>. This tells Highcharts for Python<\/b> that we expect to produce one series for every row incensus-time-series.csv<\/code>.<\/p>\nBecause we have not specified a
property_column_map<\/code>, the series.name<\/code> values are populated from the'Geographic Area'<\/code> column, while the data point.x<\/code> values come from each additional column (e.g. ‘2010’, ‘2011’, ‘2012’, etc.)
\nTip<\/b><\/p>\nTo simplify the code further, any class that supports the
.from_csv()<\/code> method also supports the.from_csv_in_rows()<\/code> method. The latter method is equivalent to passingseries_in_rows = True<\/code> to.from_csv()<\/code>.<\/p>\nFor more information, please see:<\/p>\n
- \n
Chart.from_csv_in_rows()<\/code><\/li>\nSeriesBase.from_csv_in_rows()<\/code><\/li>\n<\/ul>\n<\/i><\/p>\n
But maybe we don\u2019t want all geographic areas shown on the chart – maybe we only want to compare a few.<\/p>\n
Filtering Rows<\/h2>\n
my_chart = Chart.from_csv('census-time-series.csv',\r\n series_type = 'line',\r\n series_in_rows = True,\r\n wrapper_character = '\"',\r\n series_index = slice(7, 10))<\/pre>\n![\"Line](\"https:\/\/wp-assets.highcharts.com\/www-highcharts-com\/blog\/wp-content\/uploads\/2023\/10\/17203516\/Line-chart-using-data-from-the-table-above-US-gerographic-population-for-3-states.jpg\")
<\/p>\nWhat we did here is we added a
series_index<\/code> argument, which tells Highcharts for Python<\/b> to only include the series found at that index in the resulting chart. In this case, we supplied aslice<\/code> object, which operates just likelist_of_series[7:10]<\/code>. The result only returns those series between index 7 and 10.<\/p>\nCreating Series: .from_csv() and .from_csv_in_rows()<\/h2>\n
All Highcharts for Python<\/b>
series<\/code> descend from theSeriesBase<\/code> class. And they all therefore support the.from_csv()<\/code> class method.<\/p>\nWhen called on a series class, it produces one or more series from the CSV supplied. The method supports all of the same options as
Chart.from_csv()<\/code> except foroptions_kwargs<\/code> andchart_kwargs<\/code>. This is because the.from_csv()<\/code> method on a series class is only responsible for creating series instances – not the chart itself.<\/p>\nCreating Series from Columns<\/h2>\n
So let\u2019s say we wanted to create one series for each of the years in
census-time-series.csv<\/code>. We could do that like so:<\/p>\nmy_series = BarSeries.from_csv('census-time-series.csv')<\/pre>\nUnlike when calling
Chart.from_csv()<\/code>, we did not have to specify aseries_type<\/code> – that\u2019s because the.from_csv()<\/code> class method on a series class already knows the series type.<\/p>\nIn this case,
my_series<\/code> now contains ten separateBarSeries<\/code> instances, each corresponding to one of the year columns incensus-time-series.csv<\/code>.<\/p>\nBut maybe we wanted to create our series from rows instead?<\/p>\n
Creating Series from Rows<\/h2>\n
my_series = LineSeries.from_csv_in_rows('census-time-series.csv')<\/pre>\nThis will produce one
LineSeries<\/code> instance for each row incensus-time-series.csv<\/code>, ultimately producing a list of 57LineSeries<\/code> instances.<\/p>\nNow what if we don\u2019t need all 57, but instead only want the first five?<\/p>\n
Filtering Series Created from Rows<\/h2>\n
my_series = LineSeries.from_csv_in_rows('census-time-series.csv', series_index = slice(0, 5))<\/pre>\nThis will return the first five series in the list of 57.<\/b><\/p>\n
Updating an Existing Series: .load_from_csv()<\/h2>\n
So far, we\u2019ve only been creating new series and charts. But what if we want to update the data within an existing series? That\u2019s easy to do using the
.load_from_csv()<\/code> method.<\/p>\nLet\u2019s say we take the first series returned in
my_series<\/code> up above, and we want to replace its data with the data from the 10th series. We can do that by:<\/p>\nmy_series[0].load_from_csv('census-time-series.csv',\r\n series_in_rows = True,\r\n series_index = 9)<\/pre>\nThe
series_in_rows<\/code> argument tells the method to generate series per row, and then theseries_index<\/code> argument tells it to only use the 10th series generated.<\/p>\nCaution<\/b><\/p>\n
While the
.load_from_csv()<\/code> method supports the same arguments as.from_csv()<\/code>, it expects that the arguments supplied lead to an unambiguous single series. If they are ambiguous – meaning they lead to multiple series generated from the CSV – then the method will throw aHighchartsCSVDeserializationError<\/code>
\n<\/i><\/p>\n\u00a0<\/p>\n
Related posts<\/strong><\/h2>\n
- \n
- Line chart vs bar chart: choosing the right one for your objectives and data<\/a><\/li>\n
- Pareto chart: what is it and what does it suggest<\/a><\/li>\n
- Polygon chart using Highcharts<\/a><\/li>\n
- Choropleth map examples using Highcharts<\/a><\/li>\n
- Lightning map: create your own using Highcharts<\/a><\/li>\n
- Maps with latitude longitude using Highcharts<\/a><\/li>\n<\/ul>\n
<\/p>\n","protected":false},"excerpt":{"rendered":"
CSV (Comma-Separated Value) is one of the most common formats for exchanging data files – both large and small. Because of its popularity, the Highcharts for Python Toolkit is designed to work seamlessly with it. General Approach The Highcharts for Python Toolkit provides a number of standard methods that are used to interact with CSV […]<\/p>\n","protected":false},"author":273,"featured_media":24337,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"meta_title":"","meta_description":"","hc_selected_options":[],"footnotes":""},"categories":[1105],"tags":[1094,885],"coauthors":[983,699],"class_list":["post-24320","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-integration","tag-highcharts-core","tag-python"],"_links":{"self":[{"href":"https:\/\/www.highcharts.com\/blog\/wp-json\/wp\/v2\/posts\/24320","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.highcharts.com\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.highcharts.com\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.highcharts.com\/blog\/wp-json\/wp\/v2\/users\/273"}],"replies":[{"embeddable":true,"href":"https:\/\/www.highcharts.com\/blog\/wp-json\/wp\/v2\/comments?post=24320"}],"version-history":[{"count":3,"href":"https:\/\/www.highcharts.com\/blog\/wp-json\/wp\/v2\/posts\/24320\/revisions"}],"predecessor-version":[{"id":26050,"href":"https:\/\/www.highcharts.com\/blog\/wp-json\/wp\/v2\/posts\/24320\/revisions\/26050"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/www.highcharts.com\/blog\/wp-json\/wp\/v2\/media\/24337"}],"wp:attachment":[{"href":"https:\/\/www.highcharts.com\/blog\/wp-json\/wp\/v2\/media?parent=24320"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.highcharts.com\/blog\/wp-json\/wp\/v2\/categories?post=24320"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.highcharts.com\/blog\/wp-json\/wp\/v2\/tags?post=24320"},{"taxonomy":"author","embeddable":true,"href":"https:\/\/www.highcharts.com\/blog\/wp-json\/wp\/v2\/coauthors?post=24320"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}
- Pareto chart: what is it and what does it suggest<\/a><\/li>\n
- On the