Charts and Visualization

# Chart types available via workbook.add_chart()
CHART_TYPES = {
    'area': 'Area charts',
    'bar': 'Bar charts (horizontal)',
    'column': 'Column charts (vertical)', 
    'doughnut': 'Doughnut charts',
    'line': 'Line charts',
    'pie': 'Pie charts',
    'radar': 'Radar charts',
    'scatter': 'Scatter (XY) charts',
    'stock': 'Stock charts'
}

# Chart creation through workbook
def add_chart(self, options):
    """
    Create a chart object.
    
    Args:
        options (dict): Chart configuration:
            - type (str): Chart type ('column', 'line', 'pie', etc.)
            - subtype (str, optional): Chart subtype for variations
            
    Returns:
        Chart: Chart object of the specified type
    """

def add_series(self, options=None):
    """
    Add a data series to the chart.
    
    Args:
        options (dict, optional): Series configuration:
            - categories (str): Range for category labels (X-axis)
            - values (str): Range for data values (Y-axis)
            - name (str): Name for the series (legend)
            - name_formula (str): Formula for series name
            - line (dict): Line formatting options
            - border (dict): Border formatting options
            - fill (dict): Fill formatting options
            - marker (dict): Data point marker options
            - trendline (dict): Trendline configuration
            - y_error_bars (dict): Y error bars configuration
            - x_error_bars (dict): X error bars configuration
            - data_labels (dict): Data labels configuration
            - points (list): Individual point formatting
            - smooth (bool): Smooth line for line charts
            - invert_if_negative (bool): Invert colors for negative values
    """

def set_title(self, options=None):
    """
    Set the chart title.
    
    Args:
        options (dict, optional): Title configuration:
            - name (str): Title text
            - name_font (dict): Font formatting for title
            - overlay (bool): Allow title to overlay chart
            - layout (dict): Position and size settings
            - none (bool): Remove default title
    """

def set_x_axis(self, options):
    """
    Configure the primary X-axis.
    
    Args:
        options (dict): X-axis configuration:
            - name (str): Axis title
            - name_font (dict): Title font formatting
            - num_font (dict): Number font formatting
            - line (dict): Axis line formatting
            - fill (dict): Axis area fill
            - min (float): Minimum axis value
            - max (float): Maximum axis value
            - minor_unit (float): Minor tick interval
            - major_unit (float): Major tick interval
            - crossing (float): Axis crossing point
            - reverse (bool): Reverse axis direction
            - log_base (int): Logarithmic scale base
            - major_gridlines (dict): Major gridline formatting
            - minor_gridlines (dict): Minor gridline formatting
            - visible (bool): Show/hide axis
            - position_axis (str): Axis position ('on_tick'/'between_tick')
            - label_position (str): Label position ('high'/'low'/'next_to')
            - major_tick_mark (str): Major tick mark type
            - minor_tick_mark (str): Minor tick mark type
            - num_format (str): Number format for axis labels
            - text_axis (bool): Treat as text axis
            - date_axis (bool): Treat as date axis
    """

def set_y_axis(self, options):
    """Configure the primary Y-axis (same options as set_x_axis)."""

def set_x2_axis(self, options):
    """Configure the secondary X-axis (same options as set_x_axis)."""

def set_y2_axis(self, options):
    """Configure the secondary Y-axis (same options as set_x_axis)."""

def set_legend(self, options):
    """
    Configure the chart legend.
    
    Args:
        options (dict): Legend configuration:
            - position (str): Legend position:
                'bottom', 'top', 'right', 'left', 'overlay_right', 'overlay_left', 'none'
            - font (dict): Legend font formatting
            - border (dict): Legend border formatting
            - fill (dict): Legend background fill
            - layout (dict): Custom position and size
            - delete_series (list): Hide specific series from legend
    """

def set_plotarea(self, options):
    """
    Configure the plot area (data area of the chart).
    
    Args:
        options (dict): Plot area configuration:
            - border (dict): Plot area border formatting
            - fill (dict): Plot area background fill
            - layout (dict): Custom position and size
    """

def set_chartarea(self, options):
    """
    Configure the chart area (entire chart including axes and legend).
    
    Args:
        options (dict): Chart area configuration:
            - border (dict): Chart area border formatting
            - fill (dict): Chart area background fill
    """

def set_style(self, style_id):
    """
    Set a built-in chart style.
    
    Args:
        style_id (int): Style ID (1-48) corresponding to Excel's chart styles
    """

def show_blanks_as(self, option):
    """
    Configure how blank cells are displayed in the chart.
    
    Args:
        option (str): Display option:
            - 'gap': Show as gaps in the data
            - 'zero': Treat as zero values
            - 'span': Connect across blank cells
    """

def show_na_as_empty_cell(self):
    """Display #N/A errors as empty cells in the chart."""

def show_hidden_data(self):
    """Include hidden cell data in the chart."""

def set_size(self, options=None):
    """
    Set chart size and position.
    
    Args:
        options (dict, optional): Size configuration:
            - width (int): Chart width in pixels
            - height (int): Chart height in pixels
            - x_scale (float): X-axis scaling factor
            - y_scale (float): Y-axis scaling factor
    """

def set_table(self, options=None):
    """
    Add a data table to the chart.
    
    Args:
        options (dict, optional): Table configuration:
            - show_keys (bool): Show legend keys in table
            - horizontal (bool): Show horizontal lines
            - vertical (bool): Show vertical lines  
            - outline (bool): Show table outline
            - font (dict): Table font formatting
    """

def set_up_down_bars(self, options=None):
    """
    Add up/down bars to line charts.
    
    Args:
        options (dict, optional): Up/down bars configuration:
            - up_bar_line (dict): Up bar line formatting
            - up_bar_fill (dict): Up bar fill formatting
            - down_bar_line (dict): Down bar line formatting
            - down_bar_fill (dict): Down bar fill formatting
    """

def set_drop_lines(self, options=None):
    """
    Add drop lines to line charts.
    
    Args:
        options (dict, optional): Drop lines configuration:
            - line (dict): Drop line formatting
    """

def set_high_low_lines(self, options=None):
    """
    Add high-low lines to line charts.
    
    Args:
        options (dict, optional): High-low lines configuration:
            - line (dict): High-low line formatting
    """

def combine(self, chart=None):
    """
    Combine this chart with another chart.
    
    Args:
        chart (Chart): Another chart object to combine with
        
    This allows creating combination charts like column-line charts.
    """

import xlsxwriter

workbook = xlsxwriter.Workbook('charts.xlsx')
worksheet = workbook.add_worksheet()

# Add sample data
data = [
    ['Quarter', 'Sales', 'Expenses'],
    ['Q1', 1000, 600],
    ['Q2', 1200, 700], 
    ['Q3', 1500, 800],
    ['Q4', 1800, 900]
]

for row, row_data in enumerate(data):
    worksheet.write_row(row, 0, row_data)

# Create a column chart
chart = workbook.add_chart({'type': 'column'})

# Add data series
chart.add_series({
    'categories': '=Sheet1!$A$2:$A$5',
    'values': '=Sheet1!$B$2:$B$5',
    'name': 'Sales'
})

chart.add_series({
    'categories': '=Sheet1!$A$2:$A$5', 
    'values': '=Sheet1!$C$2:$C$5',
    'name': 'Expenses'
})

# Configure chart
chart.set_title({'name': 'Quarterly Results'})
chart.set_x_axis({'name': 'Quarter'})
chart.set_y_axis({'name': 'Amount ($)'})

# Insert chart
worksheet.insert_chart('E2', chart)

workbook.close()

# Create a line chart with full formatting
chart = workbook.add_chart({'type': 'line'})

# Add series with extensive formatting
chart.add_series({
    'categories': '=Sheet1!$A$2:$A$5',
    'values': '=Sheet1!$B$2:$B$5',
    'name': 'Revenue',
    'line': {
        'color': 'blue',
        'width': 3,
        'dash_type': 'dash'
    },
    'marker': {
        'type': 'circle',  
        'size': 8,
        'border': {'color': 'red'},
        'fill': {'color': 'yellow'}
    },
    'data_labels': {
        'value': True,
        'font': {'name': 'Arial', 'size': 10}
    }
})

# Comprehensive chart formatting
chart.set_title({
    'name': 'Sales Trends',
    'name_font': {
        'name': 'Arial',
        'size': 16,
        'bold': True,
        'color': 'blue'
    }
})

chart.set_x_axis({
    'name': 'Time Period',
    'name_font': {'size': 12, 'bold': True},
    'num_font': {'size': 10, 'italic': True},
    'major_gridlines': {
        'visible': True,
        'line': {'color': 'gray', 'width': 0.5}
    }
})

chart.set_legend({
    'position': 'bottom',
    'font': {'size': 10}
})

chart.set_plotarea({
    'border': {'color': 'black', 'width': 1},
    'fill': {'color': '#FFFFCC'}
})

worksheet.insert_chart('E2', chart, {'x_scale': 1.5, 'y_scale': 1.2})

# Pie chart
pie_chart = workbook.add_chart({'type': 'pie'})
pie_chart.add_series({
    'categories': '=Sheet1!$A$2:$A$5',
    'values': '=Sheet1!$B$2:$B$5', 
    'data_labels': {'percentage': True}
})

# Scatter chart
scatter_chart = workbook.add_chart({'type': 'scatter'})
scatter_chart.add_series({
    'categories': '=Sheet1!$B$2:$B$5',
    'values': '=Sheet1!$C$2:$C$5',
    'marker': {'type': 'circle', 'size': 10}
})

# Area chart
area_chart = workbook.add_chart({'type': 'area'})
area_chart.add_series({
    'categories': '=Sheet1!$A$2:$A$5',
    'values': '=Sheet1!$B$2:$B$5'
})

# Bar chart (horizontal)
bar_chart = workbook.add_chart({'type': 'bar'})
bar_chart.add_series({
    'categories': '=Sheet1!$A$2:$A$5',
    'values': '=Sheet1!$B$2:$B$5'
})

# Create primary chart (column)
primary_chart = workbook.add_chart({'type': 'column'})
primary_chart.add_series({
    'categories': '=Sheet1!$A$2:$A$5',
    'values': '=Sheet1!$B$2:$B$5',
    'name': 'Sales Volume'
})

# Create secondary chart (line)
secondary_chart = workbook.add_chart({'type': 'line'})
secondary_chart.add_series({
    'categories': '=Sheet1!$A$2:$A$5',
    'values': '=Sheet1!$C$2:$C$5',
    'name': 'Profit Margin',
    'y2_axis': True  # Use secondary Y-axis
})

# Combine charts
primary_chart.combine(secondary_chart)

# Configure axes
primary_chart.set_y_axis({'name': 'Volume'})
primary_chart.set_y2_axis({'name': 'Margin (%)'})

worksheet.insert_chart('E2', primary_chart)

# Stacked column chart
stacked_chart = workbook.add_chart({
    'type': 'column',
    'subtype': 'stacked'
})

# 100% stacked column chart
percent_stacked_chart = workbook.add_chart({
    'type': 'column', 
    'subtype': 'percent_stacked'
})

# 3D pie chart
pie_3d_chart = workbook.add_chart({
    'type': 'pie',
    'subtype': '3d'
})

# Smooth line chart
smooth_line_chart = workbook.add_chart({
    'type': 'line',
    'subtype': 'smooth'
})