Help for package APCI

Type:

Package

Title:

A New Age-Period-Cohort Model for Describing and Investigating Inter-Cohort Differences and Life Course Dynamics

Version:

1.0.8

Maintainer:

Jiahui Xu <jpx5053@psu.edu>

Depends:

R (≥ 3.6.0)

Description:

It implemented Age-Period-Interaction Model (APC-I Model) proposed in the paper of Liying Luo and James S. Hodges in 2019. A new age-period-cohort model for describing and investigating inter-cohort differences and life course dynamics.

Imports:

survey, magrittr, dplyr, ggplot2, data.table, ggpubr, stringr, gee

License:

GPL-2

Encoding:

UTF-8

LazyData:

true

RoxygenNote:

7.2.3

NeedsCompilation:

Packaged:

2024-09-02 18:10:13 UTC; jiahuixu

Author:

Jiahui Xu [aut, cre], Liying Luo [aut]

Repository:

CRAN

Date/Publication:

2024-09-02 20:20:06 UTC

Get the cohort index matrix for any age and period groups

Description

This function returns the cohort index matrix for any age and period groups. The cohort index matrix will then be used to extract the cohort effects.

Usage

ageperiod_group(
  age_range,
  period_range,
  age_interval = NULL,
  period_interval = NULL,
  age_group = NULL,
  period_group = NULL
)

Arguments

age_range, period_range

Numeric vector indicating the actual age and period range (e.g., 10 to 59 years old from 2000 to 2019).

age_interval, period_interval, age_group, period_group

Numeric values or character vectors indicating how age and period are grouped. age_interval and period_interval are numbers indicating the width of age and period groups respectively. age_group and period_group are character vectors explicitly listing all potential age and period groups. Either age_interval(period_interval) or age_group (period_group) have to be defined when unequal_interval is TRUE.

Value

a matrix respresenting the relationship among age, period, and cohort groups under the current setting.

Examples

## age and period groups have equal width
ageperiod_group(age_range = 10:59, period_range = 2000:2019,
                age_interval = 5, period_interval = 5)
ageperiod_group(age_range = 10:59, period_range = 2000:2019,
                age_group = c("10-14","15-19","20-24","25-29",
                              "30-34","35-39","40-44","45-49",
                              "50-54","55-59"),
                period_group = c("2000-2004","2005-2009","2010-2014",
                                 "2015-2019"))

## age and period groups have unequal width
ageperiod_group(age_range = 10:59, period_range = 2000:2019,
                age_interval = 10, period_interval = 5)
ageperiod_group(age_range = 10:59, period_range = 2000:2019,
                age_group = c("10-19","20-29","30-39","40-49","50-59"),
                period_group = c("2000-2004","2005-2009",
                                 "2010-2014","2015-2019"))

Run APC-I model

Description

Run APC-I model

Usage

apci(
  outcome = "inlfc",
  age = "acc",
  period = "pcc",
  cohort = NULL,
  weight = NULL,
  covariate = NULL,
  data,
  family = "quasibinomial",
  dev.test = TRUE,
  print = TRUE,
  gee = FALSE,
  id = NULL,
  corstr = "exchangeable",
  unequal_interval = FALSE,
  age_range = NULL,
  period_range = NULL,
  age_interval = NULL,
  period_interval = NULL,
  age_group = NULL,
  period_group = NULL,
  ...
)

Arguments

outcome

An object of class character containing the name of the outcome variable. The outcome variable can be continuous, categorical, or count.

age

An object of class character representing the age group index taking on a small number of distinct values in the data. Usually, the vector should be converted to a factor (or the terms of "category" and "enumerated type").

period

An object of class character, similar to the argument of age, representing the time period index in the data.

cohort

An optional object of class character representing cohort membership index in the data. Usually, the cohort index can be generated from the age group index and time period index in the data because of the intrinsic relationship among these three time-related indices.

weight

An optional vector of sample weights to be used in the model fitting process. If non-NULL, the weights will be used in the first step to estimate the model. Observations with negative weights will be automatically dropped in modeling.

covariate

An optional vector of characters, representing the name(s) of the user-specified covariate(s) to be used in the model. If the variable(s) are not found in data, there will be an error message reminding the users to check the data again.

data

A data frame containing the outcome variable, age group indicator, period group indicator, and covariates to be used in the model. If the variable(s) are not found in data, there will be an error message reminding the users to check the input data again.

family

Used to specify the statistical distribution of the error term and link function to be used in the model. Usually, it is a character string naming a family function. For example, family can be "binomial", "multinomial"", or "gaussian". Users could also check R package glm for more details of family functions.

dev.test

Logical, specifying if the global F test should be implemented before fitting the APC-I model. If TRUE, apci will first run the global F test and report the test results; otherwise, apci will skip this step and return NULL. The default setting is TRUE. However, users should be aware that the algorithm will not automatically stop even if there is no significant age-by-period interactions based on the global F test.

print

Logical, specifying if the intermediate results should be displayed in the console when fitting the model. The default setting is TRUE to display the results of each procedure.

gee

Logical, indicating if the data is cross-sectional data or longitudinal/panel data. If TRUE, the generalized estimating equation will be used to correct the standard error estimates. The default is FALSE, indicating that the data are cross-sectional.

id

A vector of character, specifying the cluster index in longitudinal data. It is required when gee is TRUE. The length of the vector should be the same as the number of observations.

corstr

A character string, specifying a possible correlation structure in the error terms when gee is TRUE. The following are allowed: independence, fixed, stat\_M\_dep, non\_stat\_M\_dep, exchangeable, AR-M and unstructured. The default value is exchangeable.

unequal_interval

Logical, indicating if age and period groups are of the same interval width. The default is set as TRUE.

age_range, period_range

Numeric vector indicating the actual age and period range (e.g., 10 to 59 years old from 2000 to 2019).

age_interval, period_interval, age_group, period_group

...

Additional arguments to be passed to the function.

Value

A list containing:

model

The fitted generalized linear model.

intercept

The overall intercept.

age_effect

The estimated age main effect.

period_effect

The estimated period main effect.

cohort_average

The estimated inter-cohort average deviations from age and period main effects.

cohort_slope

The estimated intra-cohort life-course linear slopes.

int_matrix

A matrix containing the estimated coefficients for age-by-period interactions.

cohort_index

Indices indicating different cohorts.

data

Data used for fitting APC-I model.

Examples

# load package
library("APCI")
# load data
test_data <- APCI::women9017
test_data$acc <- as.factor(test_data$acc)
test_data$pcc <- as.factor(test_data$pcc)
test_data$educc <- as.factor(test_data$educc)
test_data$educr <- as.factor(test_data$educr)

# fit APC-I model
APC_I <- APCI::apci(outcome = "inlfc",
                    age = "acc",
                    period = "pcc",
                    cohort = "ccc",
                    weight = "wt",
                    data = test_data,dev.test=FALSE,
                    print = TRUE,
                    family = "gaussian")
summary(APC_I)

# explore the raw data pattern
apci.plot.raw(data = test_data, outcome_var = "inlfc",age = "acc",
              period = "pcc")
## alternatively,
apci.plot(data = test_data, outcome_var = "inlfc", age = "acc",model=APC_I,
          period = "pcc", type = "explore")

# visaulze estimated cohort effects with bar plot
apci.bar(model = APC_I, age = "acc",
         period = "pcc", outcome_var = "inlfc")

# visaulze estimated cohort effects with heatmap plot
apci.plot.heatmap(model = APC_I, age = "acc",period = "pcc")
## alternatively,
apci.plot(data = test_data, outcome_var = "inlfc", age = "acc",model=APC_I,
          period = "pcc")

Make barplot for cohort effect

Description

Visualize cohort effects estimated by APC-I model with bar plots.

Usage

apci.bar(model, age, period, outcome_var, cohort_label = NULL, ...)

Arguments

model

A list recording the results from function apci.

age

period

An object of class character, similar to the argument of age, representing the time period index in the data.

outcome_var

An object of class character indicating the name of the outcome variable used in the model. The outcome variable can be a continuous, binary, categorical, or count variable.

cohort_label

An optional vector, representing the labels of cohort groups in the x asix.

...

Additional arguments to be passed to the function.

Value

A bar plot visualizing the cohort effects estimated by APC-I model.

Examples

# load package
library("APCI")
# load data
test_data <- APCI::women9017
test_data$acc <- as.factor(test_data$acc)
test_data$pcc <- as.factor(test_data$pcc)
test_data$educc <- as.factor(test_data$educc)
test_data$educr <- as.factor(test_data$educr)

# fit APC-I model
APC_I <- APCI::apci(outcome = "inlfc",
                    age = "acc",
                    period = "pcc",
                    cohort = "ccc",
                    weight = "wt",
                    data = test_data,dev.test=FALSE,
                    print = TRUE,
                    family = "gaussian")
summary(APC_I)

## visualizing estimated cohort effects with bar plot
apci.bar(model = APC_I, age = "acc", period = "pcc")

Plotting age and period raw scores and APC-I model results

Description

Arranging data exploration and model results representation in a harmonized way.

Usage

apci.plot(
  model,
  age,
  period,
  outcome_var,
  type = "model",
  quantile = NULL,
  ...
)

Arguments

model

A list recording the results from function apci.

age

period

An object of class character, similar to the argument of age, representing the time period index in the data.

outcome_var

An object of class character indicating the name of the outcome variable used in the model. The outcome variable can be a continuous, binary, categorical, or count variable.

type

Character, "explore" or "model". If type is "explore", plots for age and period raw scores will be generated. If type is "model", model results will be plotted. The default setting is "model".

quantile

A number valued between 0 and 1, representing the desirable percentiles to be used in visualizing the data or model. If NULL, the original scale of the outcome variable will be used.

...

Additional arguments to be passed to the function.

Value

A plot with three panels showing the raw scores or APC-I model results.

Examples

# load package
library("APCI")
# load data
test_data <- APCI::women9017
test_data$acc <- as.factor(test_data$acc)
test_data$pcc <- as.factor(test_data$pcc)
test_data$educc <- as.factor(test_data$educc)
test_data$educr <- as.factor(test_data$educr)

# fit APC-I model
APC_I <- APCI::apci(outcome = "inlfc",
                    age = "acc",
                    period = "pcc",
                    cohort = "ccc",
                    weight = "wt",
                    data = test_data,dev.test=FALSE,
                    print = TRUE,
                    family = "gaussian")
summary(APC_I)

## plot the raw pattern
apci.plot(data = test_data, outcome_var = "inlfc", age = "acc",model=APC_I,
          period = "pcc", type = "explore")
## plot the model results
apci.plot(data = test_data, outcome_var = "inlfc", age = "acc",model=APC_I,
          period = "pcc", type = "model")

Plot the heatmap for APC-I model

Description

Plot the heatmap to visualize cohort effects estimated by APC-I model.

Usage

apci.plot.heatmap(
  model,
  age,
  period,
  color_map = NULL,
  color_scale = NULL,
  quantile = NULL,
  ...
)

Arguments

model

A list recording the results from function apci.

age

period

An object of class character, similar to the argument of age, representing the time period index in the data.

color_map

A vector, representing the color palettes to be used in the figure. The default setting is greys if color_map is NULL. Alternations, for example, can be c("blue", "yellow"), blues, etc.

color_scale

A vector including two numbers indicating the limit of the values to be plotted. The first number is the minimum value to be visualized and the second is the maximum value to be visualized. If NULL, the algorithm will automatically select the limits from the data (estimation results) to set up the scale.

quantile

A number valued between 0 and 1, representing the desirable percentiles to be used in visualizing the data or model. If NULL, the original scale of the outcome variable will be used.

...

Additional arguments to be passed to the function.

Value

A heatmap visualizing cohort effects estimated by APC-I model.

Examples

# load package
library("APCI")
# load data
test_data <- APCI::women9017
test_data$acc <- as.factor(test_data$acc)
test_data$pcc <- as.factor(test_data$pcc)
test_data$educc <- as.factor(test_data$educc)
test_data$educr <- as.factor(test_data$educr)

# fit APC-I model
APC_I <- APCI::apci(outcome = "inlfc",
                    age = "acc",
                    period = "pcc",
                    cohort = "ccc",
                    weight = "wt",
                    data = test_data,dev.test=FALSE,
                    print = TRUE,
                    family = "gaussian")
summary(APC_I)

# plot heatmap
apci.plot.heatmap(model=APC_I,age="acc",period="pcc",first_age = 20,
                  first_period = 1940, interval = 5)

Plot the hexagram heatmap

Description

Plot the cohort effect in the style of hexagram

Usage

apci.plot.hexagram(
  model,
  age,
  period,
  first_age,
  first_period,
  interval,
  first_age_isoline = NULL,
  first_period_isoline = NULL,
  isoline_interval = NULL,
  color_scale = NULL,
  color_map = NULL,
  line_width = 0.5,
  line_color = "grey",
  label_size = 0.5,
  label_color = "black",
  scale_units = "Quintile",
  wrap_cohort_labels = TRUE,
  quantile = NULL
)

Arguments

model

A list recording the results from function apci.

age

period

An object of class character, similar to the argument of age, representing the time period index in the data.

first_age

The first age group.

first_period

The first period group.

interval

The width of age and period groups.

first_age_isoline

Isoline for the first age group.

first_period_isoline

Isoline for the first period group.

isoline_interval

Interval of isoline.

color_scale

color_map

A vector, representing the color palettes to be used in the figure. The default setting is greys if color_map is NULL. Alternations, for example, can be c("blue", "yellow"), blues, etc.

line_width

Width of lines. Default is 0.5.

line_color

Line colors. Default is grey.

label_size

Axis label size. Default is 0.5.

label_color

Axis label color. Default is Black.

scale_units

Units of scales.

wrap_cohort_labels

Display the cohort label or not. The default is TRUE.

quantile

A number valued between 0 and 1, representing the desirable percentiles to be used in visualizing the data or model. If NULL, the original scale of the outcome variable will be used.

Value

A hexagram visualizing the APC-I model results.

Examples

# load package
library("APCI")
# load data
test_data <- APCI::women9017
test_data$acc <- as.factor(test_data$acc)
test_data$pcc <- as.factor(test_data$pcc)
test_data$educc <- as.factor(test_data$educc)
test_data$educr <- as.factor(test_data$educr)

# fit APC-I model
APC_I <- APCI::apci(outcome = "inlfc",
                    age = "acc",
                    period = "pcc",
                    cohort = "ccc",
                    weight = "wt",
                    data = test_data,dev.test=FALSE,
                    print = TRUE,
                    family = "gaussian")
summary(APC_I)

# plot hexagram
apci.plot.hexagram(model=APC_I,age="acc",period="pcc",first_age = 20,
                   first_period = 1940, interval = 5)

Plotting age and period patterns

Description

Visualize the age and period patterns by plotting the raw scores in each age and period square.

Usage

apci.plot.raw(data, outcome_var, age, period, ...)

Arguments

data

outcome_var

An object of class character indicating the name of the outcome variable used in the model. The outcome variable can be a continuous, binary, categorical, or count variable.

age

period

An object of class character, similar to the argument of age, representing the time period index in the data.

...

Additional arguments to be passed to the function.

Value

A plot with two panels showing the age and period trends separately.

Examples

# load package
library("APCI")
# load data
test_data <- APCI::women9017
test_data$acc <- as.factor(test_data$acc)
test_data$pcc <- as.factor(test_data$pcc)
test_data$educc <- as.factor(test_data$educc)
test_data$educr <- as.factor(test_data$educr)

# fit APC-I model
APC_I <- APCI::apci(outcome = "inlfc",
                    age = "acc",
                    period = "pcc",
                    cohort = "ccc",
                    weight = "wt",
                    data = test_data,dev.test=FALSE,
                    print = TRUE,
                    family = "gaussian")
summary(APC_I)

# plot the raw pattern
apci.plot.raw(data = test_data, outcome_var = "inlfc",age = "acc",
              period = "pcc")

Black Men

Description

the dataset for black men

Usage

data("blackmen")

Format

A data frame with 10000 observations on the following 7 variables.

asecwt: weight
year: a factor indicating period groups with levels 1 2 3 4 5 6
age: a factor indicating age groups with levels 1 2 3 4 5 6 7 8 9
labforce: labor Force participation rate
educ: education level
educr: education level
educc: education level

Black Women

Description

Dataset for black women

Usage

data("blackwomen")

Format

A data frame with 10000 observations on the following 7 variables.

asecwt: weight
year: a factor indicating period groups
age: a factor indicating age groups
labforce: labor Force participation rate
educ: education level
educr: education level
educc: education level

Calculate cohort deviation

Description

Calculate cohort deviation

Usage

cohortdeviation(
  A,
  P,
  C,
  model = temp6,
  weight = "wt",
  covariate,
  gee = FALSE,
  unequal_interval = FALSE,
  age_range = NULL,
  period_range = NULL,
  age_interval = NULL,
  period_interval = NULL,
  age_group = NULL,
  period_group = NULL,
  ...
)

Arguments

A, P, C

The numbers of age groups, period groups, and cohort groups separately.

model

A generalized linear regression model generated from the internal function temp_model

weight

covariate

gee

unequal_interval

Logical, indicating if age and period groups are of the same interval width. The default is set as TRUE.

age_range, period_range

Numeric vector indicating the actual age and period range (e.g., 10 to 59 years old from 2000 to 2019).

age_interval, period_interval, age_group, period_group

...

Additional arguments to be passed to the function.

Value

A list containing:

cohort_average

The estimated inter-cohort average deviations from age and period main effects.

cohort_slope

The estimated intra-cohort life-course linear slopes.

int_matrix

A matrix containing the estimated coefficients for age-by-period interactions.

cohort_index

Indices indicating different cohorts.

Calculate x coordinate value

Description

Calculate x coordinate value for plotting hexagram in visualizing APC-I results.

Usage

compute_xcoordinate(p)

Arguments

p

Period value.

Value

The coordinate value for x axis.

Calculate y coordinate value

Description

Calculate y coordinate value for plotting hexagram in visualizing APC-I results.

Usage

compute_ycoordinate(p, a)

Arguments

p

Period value

a

Age value

Value

The coordinate value for y axis.

Labor force participation data for men from 1990 to 1979 in CPS

Description

the dataset for men

Usage

data("cpsmen")

Format

A data frame with 10000 observations on the following 7 variables.

asecwt: weight
year: a factor indicating period groups with levels 1 2 3 4 5 6
age: a factor indicating age groups with levels 1 2 3 4 5 6 7 8 9
labforce: labor Force participation rate
educ: education level
educr: education level
educc: education level

Labor force participation data for women from 1990 to 1979 in CPS

Description

the dataset for women

Usage

data("cpswomen")

Format

A data frame with 10000 observations on the following 7 variables.

asecwt: weight
year: a factor indicating period groups with levels 1 2 3 4 5 6
age: a factor indicating age groups with levels 1 2 3 4 5 6 7 8 9
labforce: labor Force participation rate
educ: education level
educr: education level
educc: education level

Estimate age effect and period effect

Description

Estimate age and period effect from APCI model

Usage

maineffect(A, P, C, model = temp6, data, gee = FALSE, ...)

Arguments

A, P, C

The numbers of age groups, period groups, and cohort groups separately.

model

A generalized linear regression model generated from the internal function temp_model

data

gee

...

Additional arguments to be passed to the function.

Value

A list containing:

intercept

The overall intercept.

age_effect

The estimated age main effect.

period_effect

The estimated period main effect.

Simulated Dataset

Description

A simulated dataset for APC-I analysis.

Usage

data("simulation")

Format

A data frame with 10000 observations on the following 3 variables.

y: a numeric
age: a numeric
period: a numeric

Estimate APC-I model

Description

Estimate the APCI original model. This is a generalized linear regression model.

Usage

temp_model(
  data,
  outcome = "inlfc",
  age = "acc",
  period = "pcc",
  cohort = NULL,
  weight = NULL,
  covariate = NULL,
  family = "quasibinomial",
  gee = FALSE,
  id = NULL,
  corstr = "exchangeable",
  ...
)

Arguments

data

outcome

An object of class character containing the name of the outcome variable. The outcome variable can be continuous, categorical, or count.

age

period

An object of class character, similar to the argument of age, representing the time period index in the data.

cohort

weight

covariate

family

gee

id

A vector of character, specifying the cluster index in longitudinal data. It is required when gee is TRUE. The length of the vector should be the same as the number of observations.

corstr

...

Additional arguments to be passed to the function.

Value

A list containing:

A

Age group index.

P

Period group index.

C

Cohort group index.

model

Fitted APCI models of outcome on predictors.

Local and global F test

Description

Implement local and global F test for APC-I model

Usage

tests(
  model,
  age = "acc",
  period = "pcc",
  cohort = "ccc",
  A,
  P,
  C,
  data,
  weight = "wt",
  family,
  outcome,
  ...
)

Arguments

model

A generalized linear regression model generated from the internal function temp_model

age

period

An object of class character, similar to the argument of age, representing the time period index in the data.

cohort

A, P, C

The numbers of age groups, period groups, and cohort groups separately.

data

weight

family

outcome

An object of class character containing the name of the outcome variable. The outcome variable can be continuous, categorical, or count.

...

Additional arguments to be passed to the function.

Value

A list displaying the global F test results.

White Men

Description

A dataset for white men.

Usage

data("whitemen")

Format

A data frame with 10000 observations on the following 7 variables.

asecwt: weight
year: a factor indicating period groups
age: a factor indicating age groups
labforce: labor Force participation rate
educ: education level
educr: education level
educc: education level

White Women

Description

A dataset for white women.

Usage

data("whitewomen")

Format

A data frame with 10000 observations on the following 7 variables.

asecwt: weight
year: a factor indicating period groups
age: a factor indicating age groups
labforce: labor Force participation rate
educ: education level
educr: education level
educc: education level

women9017

Description

A sample dataset

Usage

women9017

Format

A data frame with 1000 observations on the following 23 variables.

ac: a numeric vector
acc: a numeric vector
age: a numeric vector
cc: a numeric vector
ccc: a numeric vector
cohort: a numeric vector
educ: a numeric vector
educc: a numeric vector
educr: a numeric vector
inlfc: a numeric vector
labforce: a numeric vector
lfc: a numeric vector
marst: a numeric vector
marstc: a numeric vector
marstr: a numeric vector
nc: a numeric vector
ncc: a numeric vector
nchild: a numeric vector
pc: a numeric vector
pcc: a numeric vector
wt: a numeric vector
wtsupp: a numeric vector
year: a numeric vector

Details

test

Source

CPS

References

Luo and Hodges (2019)