{"id":2390,"date":"2026-10-25T15:10:04","date_gmt":"2026-10-25T07:10:04","guid":{"rendered":"https:\/\/xlwings.net\/blog\/?p=2390"},"modified":"2026-03-29T10:12:03","modified_gmt":"2026-03-29T10:12:03","slug":"how-to-use-rangedataseries-in-the-xlwings-api-way","status":"publish","type":"post","link":"https:\/\/xlwings.net\/blog\/how-to-use-rangedataseries-in-the-xlwings-api-way\/","title":{"rendered":"How to use Range.DataSeries in the xlwings API way"},"content":{"rendered":"\n

The DataSeries<\/strong> member of the Range<\/strong> object in Excel VBA is a powerful feature for creating and manipulating data series within charts. When using xlwings<\/strong> in Python, this functionality is accessed through the api<\/code> property, which exposes the underlying VBA object model. The DataSeries<\/strong> object itself is typically a collection (SeriesCollection<\/code>) associated with a Chart<\/code> object, but it is often referenced from a specific range of data that defines the series values or categories. In xlwings, you primarily interact with chart series via the Chart<\/code> object, but understanding how ranges feed into data series is crucial.<\/p>\n\n\n\n

Functionality:<\/strong>
The DataSeries<\/strong> (or more precisely, a series within a SeriesCollection<\/code>) represents a single data series in a chart, such as a line in a line chart or a set of columns in a column chart. Key operations include defining the source data range for series values (e.g., y-values) and category labels (e.g., x-values), formatting the series, and modifying its properties. Through xlwings, you can automate the creation and customization of charts by setting these ranges programmatically.<\/p>\n\n\n\n

Syntax and Parameters:<\/strong>
In xlwings, you typically work with the Series<\/code> object from a chart’s series_collection<\/code>. To set or get the range defining the series values, you use the values<\/code> property. For category labels, use the x_values<\/code> property. These properties accept a range address string or an xlwings Range<\/code> object. The general approach is:<\/p>\n\n\n\n

series = chart.series_collection[0] # Access the first series\nseries.values = sheet.range(\"B2:B10\").api # Set values range via .api\nseries.x_values = sheet.range(\"A2:A10\").api # Set categories range via .api<\/code><\/pre>\n\n\n\n
Here, chart<\/code> is an xlwings Chart<\/code> object, and sheet<\/code> is an xlwings Sheet<\/code> object. The .api<\/code> property returns the underlying VBA-compatible object, allowing you to assign ranges directly. Parameters:<\/p>\n\n\n\n
    \n
  • values<\/code>: Specifies the range containing the data points (y-values) for the series. It can be a string like \"Sheet1!B2:B10\"<\/code> or a VBA Range object.<\/li>\n\n\n\n
  • x_values<\/code>: Specifies the range for category labels (x-values). It is optional; if omitted, Excel uses sequential numbers.<\/li>\n<\/ul>\n\n\n\n
    Example Code:<\/strong>
    Suppose you have an Excel workbook with sales data in columns A (Month) and B (Sales), and you want to create a line chart. The following xlwings code demonstrates how to define the data series from a range:<\/p>\n\n\n\n
    import xlwings as xw\n\n# Connect to the active workbook and sheet\nwb = xw.Book.active\nsheet = wb.sheets[\"Sheet1\"]\n\n# Create a chart object\nchart = sheet.charts.add(left=100, top=10, width=400, height=300)\nchart.set_source_data(sheet.range(\"A1:B10\")) # Set overall data range\n\n# Access the first series in the chart and modify its data range via .api\nseries = chart.api.SeriesCollection(1) # Using .api for VBA-like access\nseries.Values = sheet.range(\"B2:B10\").api # Set values to Sales column\nseries.XValues = sheet.range(\"A2:A10\").api # Set categories to Month column\n\n# Alternatively, use xlwings' higher-level methods (if available) for simplicity\n# For instance, you can also set series data directly during chart creation:\nchart = sheet.charts.add()\nchart.chart_type = \"line\"\nchart.series_collection.add(sheet.range(\"B2:B10\"), rowcol=\"columns\", series_from=\"columns\")<\/code><\/pre>\n\n\n\n
    <\/p>\n","protected":false},"excerpt":{"rendered":"
    The **DataSeries** member of the **Range** object in Excel VBA is a powerful feature for creating an…<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[25],"tags":[],"class_list":["post-2390","post","type-post","status-publish","format-standard","hentry","category-xlwings-api-reference"],"_links":{"self":[{"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/posts\/2390","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/comments?post=2390"}],"version-history":[{"count":1,"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/posts\/2390\/revisions"}],"predecessor-version":[{"id":3638,"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/posts\/2390\/revisions\/3638"}],"wp:attachment":[{"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/media?parent=2390"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/categories?post=2390"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/tags?post=2390"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}