> ## Documentation Index
> Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Report Visualizations Guide

> Encore Health OS's report visualization system transforms data into interactive charts and graphs. Use pre-built chart widgets on dashboards or embed charts di…

## Overview

Encore Health OS's report visualization system transforms data into interactive charts and graphs. Use pre-built chart widgets on dashboards or embed charts directly into reports for enhanced data analysis.

## Chart Types

### Bar Charts

**Best For:**

* Comparing categories
* Showing rankings
* Year-over-year comparisons

**Features:**

* Vertical or horizontal orientation
* Grouped or stacked bars
* Custom color schemes
* Data labels on hover

**Example Use Cases:**

* Revenue by program
* Expenses by department
* Bed occupancy by site
* Employee count by role

### Line Charts

**Best For:**

* Time series data
* Trend analysis
* Multiple metrics over time

**Features:**

* Multiple data series
* Smooth curves or straight lines
* Area fill option
* Custom date ranges

**Example Use Cases:**

* Monthly revenue trends
* Census over time
* Budget vs actual by month
* Employee turnover rate

### Pie Charts

**Best For:**

* Part-to-whole relationships
* Percentage breakdowns
* Simple category proportions

**Features:**

* Percentage labels
* Legend with values
* Slice highlighting on hover
* Donut chart variant

**Example Use Cases:**

* Revenue by funding source
* Expense allocation by category
* Resident demographics
* Staff distribution by department

### Area Charts

**Best For:**

* Stacked time series
* Cumulative totals
* Multiple categories over time

**Features:**

* Stacked or overlapping areas
* Transparency control
* Multiple series
* Gradient fills

**Example Use Cases:**

* Cumulative admissions
* Stacked revenue sources
* Multi-site census comparison
* Layered expense categories

### Table Visualizations

**Best For:**

* Detailed data listings
* Sortable columns
* Precise values

**Features:**

* Sorting by column
* Search/filter
* Pagination
* Export to CSV
* Conditional formatting

## Creating Chart Widgets

### From Dashboard

1. Go to **Dashboard**
2. Click **Add Widget**
3. Select **Chart Widget**
4. Configure:
   * **Data Source**: Select report or table
   * **Chart Type**: Bar, Line, Pie, Area
   * **Dimensions**: X-axis, Y-axis, grouping
   * **Filters**: Date range, categories
   * **Title**: Widget name
5. **Preview** chart
6. **Save** to dashboard

### From Report Builder

1. Go to **Reports** → **Create Report**
2. Add data query (SQL or visual builder)
3. Click **Add Visualization**
4. Select chart type
5. Map data columns to chart axes
6. Configure appearance
7. Save report with embedded chart

## Chart Configuration

### Data Mapping

Map your data columns to chart elements:

**Bar Chart:**

* **Category** (X-axis): Text column (e.g., "Department Name")
* **Value** (Y-axis): Numeric column (e.g., "Total Expenses")
* **Series** (Optional): Grouping column (e.g., "Month")

**Line Chart:**

* **Date** (X-axis): Date/timestamp column
* **Value** (Y-axis): Numeric column
* **Series** (Optional): Multiple metric lines

**Pie Chart:**

* **Label**: Category names
* **Value**: Numeric values
* **Percentage**: Auto-calculated

### Appearance Options

Customize chart appearance:

#### Colors

* **Palette**: Choose from predefined color schemes
* **Custom**: Define specific colors per series
* **Theme**: Auto-adapt to light/dark mode

#### Labels

* **Axis Titles**: X and Y axis labels
* **Data Labels**: Show values on chart
* **Legend**: Position (top, bottom, right) or hide

#### Grid

* **Grid Lines**: Horizontal, vertical, or both
* **Grid Color**: Custom or theme color
* **Tick Marks**: Spacing and format

#### Animation

* **On Load**: Fade in, slide in, or none
* **On Update**: Smooth transition or instant
* **Duration**: Animation speed (ms)

## Interactive Features

### Hover Tooltips

Charts show detailed information on hover:

* Exact values
* Percentage (for pie charts)
* Multiple series values (for stacked charts)
* Custom formatting (currency, dates)

### Click Actions

Click chart elements to:

* **Drill Down**: View detailed data
* **Filter Dashboard**: Update other widgets
* **Navigate**: Go to related report or page
* **Open Details**: Show modal with full data

**Example:** Click a bar in "Revenue by Site" → Dashboard filters to that site

### Zoom and Pan

Time series charts support:

* **Zoom**: Mouse wheel or pinch gesture
* **Pan**: Drag to move along timeline
* **Reset**: Button to return to full view

### Legend Interaction

Click legend items to:

* **Show/Hide Series**: Toggle visibility
* **Isolate**: Show only that series
* **Highlight**: Emphasize in chart

## Data Refresh

### Automatic Refresh

Charts refresh automatically:

* **Real-time**: Every 30 seconds (websockets)
* **Live**: Every 5 minutes (polling)
* **Standard**: On page load only

Configure refresh rate per widget.

### Manual Refresh

Force immediate refresh:

* Click **Refresh** button on widget
* Or use keyboard shortcut: `Cmd+R` / `Ctrl+R`

### Cache Control

Control data caching:

* **No Cache**: Always fetch fresh data
* **5 Minutes**: Cache for 5 min
* **1 Hour**: Cache for 1 hour
* **1 Day**: Cache for 1 day

Balance performance vs. freshness.

## Exporting Charts

### Export Formats

Export charts as:

* **PNG**: High-resolution image
* **SVG**: Vector graphic (scalable)
* **PDF**: Single page document
* **CSV**: Underlying data only

**To Export:**

1. Click **⋯** menu on chart widget
2. Select **Export**
3. Choose format
4. Download file

### Embedding

Embed charts in other applications:

1. Click **⋯** menu on chart
2. Select **Embed**
3. Copy embed code:
   * **iFrame**: HTML embed
   * **Image URL**: Direct image link
   * **API Endpoint**: JSON data

**Security:** Embedded charts respect user permissions.

## Dashboard Integration

### Chart Widgets

Add chart widgets to dashboard:

* Fixed size or responsive
* Drag to rearrange
* Resize by dragging corners
* Group related charts

### Dashboard Filters

Apply global filters that affect all charts:

* **Date Range**: Last 7 days, last month, custom
* **Site**: All sites or specific
* **Department**: Filter by department
* **Custom**: Any report parameter

Charts automatically update when filters change.

### Layout Templates

Pre-built dashboard layouts:

**Executive Summary:**

* KPI cards (top row)
* Line chart (revenue trend)
* Pie chart (expense breakdown)
* Bar chart (site comparison)

**Financial Dashboard:**

* Budget vs actual line chart
* Expense by category pie chart
* Cash flow area chart
* Variance table

**Operations Dashboard:**

* Census line chart
* Occupancy by site bar chart
* Admissions vs discharges line chart
* Length of stay histogram

## Performance Optimization

### Large Datasets

For charts with 1000+ data points:

* **Sampling**: Display representative subset
* **Aggregation**: Group by week/month instead of day
* **Pagination**: Load data in chunks
* **Lazy Loading**: Load charts only when visible

### Responsive Design

Charts adapt to screen size:

* Mobile: Simplified view, fewer labels
* Tablet: Medium detail
* Desktop: Full detail and interactivity

### Caching Strategy

Optimize with smart caching:

* Cache expensive queries (1+ second)
* Invalidate on data changes
* Use stale-while-revalidate pattern

## Best Practices

1. **Choose Right Chart Type**: Match data to chart type
2. **Limit Series**: 5-7 series max for readability
3. **Clear Labels**: Use descriptive axis titles
4. **Consistent Colors**: Use organization color scheme
5. **Avoid 3D**: Stick to 2D for accuracy
6. **Show Zero Baseline**: Bar/line charts should start at zero
7. **Sort Data**: Order by value (descending) for bars
8. **Limit Pie Slices**: 5-7 max, group "Other"
9. **Use Annotations**: Mark important events/thresholds
10. **Test Mobile**: Ensure charts work on small screens

## Chart Examples

### Example 1: Revenue Trend

**Chart Type:** Line Chart\
**Data Source:** FA transactions\
**Configuration:**

* X-axis: Month (Jan - Dec)
* Y-axis: Total Revenue
* Series: Grant Revenue, Service Revenue, Donations
* Date Range: Last 12 months

**SQL Query:**

```sql theme={null}
SELECT 
  DATE_TRUNC('month', transaction_date) as month,
  revenue_type,
  SUM(amount) as total
FROM fa_transactions
WHERE transaction_date >= NOW() - INTERVAL '12 months'
  AND transaction_type = 'revenue'
GROUP BY month, revenue_type
ORDER BY month
```

### Example 2: Bed Occupancy by Site

**Chart Type:** Bar Chart\
**Data Source:** RH census\
**Configuration:**

* X-axis: Site Name
* Y-axis: Occupancy Percentage
* Color: Green (>80%), Yellow (60-80%), Red (\<60%)

**SQL Query:**

```sql theme={null}
SELECT 
  s.name as site_name,
  (COUNT(r.id)::FLOAT / s.total_beds * 100) as occupancy_pct
FROM pf_sites s
LEFT JOIN rh_residents r ON r.site_id = s.id 
  AND r.status = 'active'
GROUP BY s.id, s.name, s.total_beds
ORDER BY occupancy_pct DESC
```

### Example 3: Expense Allocation

**Chart Type:** Pie Chart\
**Data Source:** FA expenses\
**Configuration:**

* Label: Expense Category
* Value: Total Amount
* Show Percentage: Yes

**SQL Query:**

```sql theme={null}
SELECT 
  category,
  SUM(amount) as total
FROM fa_transactions
WHERE transaction_type = 'expense'
  AND transaction_date >= '2025-01-01'
GROUP BY category
ORDER BY total DESC
```

## Advanced Features

### Calculated Fields

Create new metrics from existing data:

* **Variance**: Budget - Actual
* **Percentage**: (Actual / Budget) \* 100
* **Growth Rate**: ((Current - Previous) / Previous) \* 100
* **Running Total**: SUM(amount) OVER (ORDER BY date)

### Conditional Formatting

Color chart elements based on rules:

* Red if variance > 10%
* Yellow if occupancy \< 80%
* Green if revenue meets target

### Drill-Through Reports

Click chart element → view detailed report:

* Bar chart bar → Transaction list
* Line chart point → Daily breakdown
* Pie chart slice → Category details

### Chart Combinations

Combine multiple chart types:

* Bar + Line: Expenses (bars) + Budget (line)
* Area + Line: Cumulative (area) + Daily (line)
* Dual Y-axis: Revenue (\$) + Occupancy (%)

## Troubleshooting

### Chart Not Displaying

**Check:**

* Data query returns results
* Columns mapped correctly
* No null values in key fields
* Browser console for errors

### Poor Performance

**Solutions:**

* Reduce date range
* Aggregate data (monthly vs daily)
* Add database indexes
* Enable caching

### Incorrect Values

**Check:**

* Data filters applied correctly
* Timezone conversions
* Currency formatting
* Aggregation function (SUM vs AVG)

### Chart Looks Wrong on Mobile

**Solutions:**

* Use responsive chart type
* Reduce data points for mobile
* Simplify labels
* Test on actual device

## Related Documentation

* [Report Builder](./reporting-guide.md)
* [Report Scheduling](./report-scheduling-guide.md)

***

**Version:** 1.0.0\
**Last Updated:** 2025-11-29