Integrated Employment Timeline and Career Metrics Visualization

Creates a unified ggplot visualization that combines employment timelines with career metrics in a single, perfectly aligned plot. This function solves alignment issues that occur with multi-panel approaches by using a shared y-axis coordinate system. The visualization displays employment periods as a Gantt chart on the left portion and career metrics as heatmap or bar elements on the right portion, ensuring perfect person-to-person alignment across both sections.

The function provides a comprehensive solution for visualizing both temporal employment patterns and summary career performance indicators simultaneously, making it ideal for career trajectory analysis, comparative studies, and reporting dashboards.

Usage

plot_integrated_employment_metrics(
  employment_data,
  career_metrics = NULL,
  person_ids = NULL,
  max_persons = 10,
  metrics_to_show = c("career_success_index", "career_advancement_index",
    "employment_security_index", "career_complexity_index"),
  timeline_width = 0.7,
  metrics_width = 0.3,
  title = "Integrated Employment Timeline and Career Metrics",
  person_col = "cf",
  time_col = "inizio",
  end_col = "fine",
  status_col = "stato",
  duration_col = "durata",
  date_breaks = "6 months",
  show_gaps = TRUE,
  palette = "employment",
  use_bw = FALSE,
  base_size = 11,
  person_order = "metrics"
)

Arguments

employment_data

A data.table containing employment records processed by the vecshift package. Must include columns for person identifiers, employment start/end dates, employment status, and duration. Each row represents an employment period for an individual.

career_metrics

Optional data.table containing career performance metrics, typically generated by calculate_comprehensive_career_metrics. If NULL, only the employment timeline will be displayed. Must contain a person identifier column matching the employment data and numeric metric columns.

person_ids

Optional character vector of specific person identifiers to include in the visualization. If NULL (default), the function will automatically select persons based on data availability and max_persons. When specified, overrides automatic selection.

max_persons

Integer specifying the maximum number of individuals to include when using automatic person selection. Default is 10. Ignored if person_ids is explicitly provided. Used to prevent overcrowded plots with large datasets.

metrics_to_show

Character vector specifying which career metrics to display in the right panel. Default includes the four core career indices: "career_success_index", "career_advancement_index", "employment_security_index", and "career_complexity_index". Only metrics present in both this parameter and the career_metrics data will be displayed.

timeline_width

Numeric value between 0 and 1 specifying the proportion of total plot width allocated to the employment timeline section. Default is 0.7 (70% of width). Must sum with metrics_width to 1.0 for proper layout.

metrics_width

Numeric value between 0 and 1 specifying the proportion of total plot width allocated to the career metrics section. Default is 0.3 (30% of width). Must sum with timeline_width to 1.0 for proper layout.

title

Character string for the plot title. Default is "Integrated Employment Timeline and Career Metrics". Set to NULL or empty string to suppress the title.

person_col

Character string specifying the column name containing person identifiers in the employment data. Default is "cf" (codice fiscale). This column is used to group records by individual and must match the identifier column in career_metrics if provided.

time_col

Character string specifying the column name containing employment period start dates in the employment data. Default is "inizio". Should contain Date or POSIXct values for proper timeline rendering.

end_col

Character string specifying the column name containing employment period end dates in the employment data. Default is "fine". Should contain Date or POSIXct values. Used to calculate period durations and create Gantt chart segments.

status_col

Character string specifying the column name containing employment status information. Default is "stato". Used for color coding and categorizing employment periods in the timeline visualization.

duration_col

Character string specifying the column name containing pre-calculated period durations (typically in days). Default is "durata". If not available, durations will be calculated from start and end dates.

date_breaks

Character string specifying the interval for x-axis date breaks in the timeline. Default is "6 months". Common values include "3 months", "1 year", or "2 years" depending on the time span of data.

show_gaps

Logical indicating whether to display unemployment periods (gaps between employment spells) in the timeline. Default is TRUE. When FALSE, only active employment periods are shown.

palette

Character string specifying the color palette to use for employment status visualization. Default is "employment". Should correspond to predefined palettes in the vecshift color system.

use_bw

Logical indicating whether to use black and white color scheme instead of the color palette. Default is FALSE. Useful for publications or presentations requiring monochrome output.

base_size

Numeric specifying the base text size for all plot elements. Default is 11. Affects titles, axis labels, legends, and annotations. Larger values increase readability but may require more plot space.

person_order

Character string specifying how to order individuals on the y-axis. Options are "alphabetical" (by person identifier), "metrics" (by career performance metrics, default), or "timeline" (by employment chronology). Affects the visual grouping and comparison of similar profiles.

Value

A ggplot2 object containing the integrated visualization. The plot features a shared y-axis with person identifiers, employment timeline as Gantt chart segments on the left portion, and career metrics as colored elements on the right portion. The object can be further customized using standard ggplot2 syntax or saved using ggsave().

Details

This function addresses a common challenge in employment data visualization: maintaining perfect alignment between temporal employment patterns and summary career metrics. Unlike approaches using separate plots or faceting, this single-plot solution guarantees that each person appears at exactly the same y-coordinate in both the timeline and metrics sections.

The visualization handles missing data gracefully:

• If career_metrics is NULL, displays timeline only

• If specific metrics are missing, shows available metrics with warnings

• If employment gaps exist, optionally displays them as distinct periods

Visual encoding follows consistent conventions:

• Timeline uses Gantt chart representation with color-coded employment status

• Metrics use intensity or categorical encoding depending on metric type

• Shared legend explains both timeline and metric encodings

• Consistent person ordering facilitates pattern recognition

See also

calculate_comprehensive_career_metrics for generating career metrics, plot_employment_gantt and plot_employment_gantt_advanced for timeline-only visualizations that may have alignment issues when combined with separate metric plots, theme_vecshift for the underlying plot theme system

Examples

if (FALSE) { # \dontrun{
# Load employment data processed by vecshift
employment_data <- readRDS("data/sample.rds")

# Calculate comprehensive career metrics
career_metrics <- calculate_comprehensive_career_metrics(employment_data)

# Basic integrated visualization with default settings
plot_integrated_employment_metrics(
  employment_data = employment_data,
  career_metrics = career_metrics
)

# Timeline-only visualization when metrics are not available
plot_integrated_employment_metrics(
  employment_data = employment_data,
  career_metrics = NULL,
  max_persons = 15
)

# Custom metric selection with adjusted layout proportions
plot_integrated_employment_metrics(
  employment_data = employment_data,
  career_metrics = career_metrics,
  metrics_to_show = c("career_success_index", "employment_security_index"),
  timeline_width = 0.75,
  metrics_width = 0.25,
  title = "Career Success and Security Analysis"
)

# Focus on specific individuals with custom styling
plot_integrated_employment_metrics(
  employment_data = employment_data,
  career_metrics = career_metrics,
  person_ids = c("PERSON001", "PERSON002", "PERSON003"),
  person_order = "alphabetical",
  base_size = 12,
  date_breaks = "1 year"
)

# Black and white version for publication
plot_integrated_employment_metrics(
  employment_data = employment_data,
  career_metrics = career_metrics,
  use_bw = TRUE,
  show_gaps = FALSE,
  max_persons = 8
)
} # }