dispositionEffect: behavioral Analysis on Financial Data

Description

The dispositionEffect package allows to perform different types of behavioral analysis using financial market and experimental data. The analysis of disposition effect, portfolio-driven disposition effect, and time series disposition effect can be performed with four different implemented methods.

Main functions

• portfolio_compute is a wrapper function that compute realized and paper gains and losses from the investor's transactions and the market prices of the traded assets and updates the investor's portfolio

• gains_losses is the core function of the package. It performs all the necessary calculations and can be used for real-time processing (it is intended for advanced users only)

• disposition_effect Compute the disposition effect based on realized and paper gains and losses

• disposition_difference Compute the disposition difference based on realized gains and losses

• disposition_computeand disposition_summaryinterfaces that allow to easily compute disposition effect and summary statistics.

Author(s)

L. Mazzucchelli & M. Zanotti

References

• An, Li and Engelberg, Joseph and Henriksson, Matthew and Wang, Baolian and Williams, Jared, 2019, "The Portfolio-Driven Disposition Effect".

• Filippin, Mazzucchelli and Zanotti, 2021, "An analysis of the short selling impact on the disposition effect extended in the portfolio framework" (working paper).

• Mazzucchelli, 2021, "An Analysis of Short Selling and Volatility Impact on the Disposition Effect" (working paper).

• Odean, Terrance, 1998, "Are investors reluctant to realize their losses?" Journal of Finance 53:5, 1775-98.

• Sakaguchi, Hiroaki and Stewart, Neil and Walasek, Lukasz, 2019, "The Disposition Effect Varies with Portfolio Composition Because People Take Gain-Loss-Domain-Level Sell Decisions".

• Shefrin, Hersh, and Meir Statman, 1985, "The disposition to sell winners too early and ride losers too long", Journal of Finance 40:3, 777-90.

• Weber, Martin, and Colin F. Camerer, 1998, "The disposition effect in securities trading: An experimental analysis", Journal of Economic Behavior and Organization 33:2, 167-84.

Pipe operator

Description

See magrittr::%>% for details.

Real sample data for Disposition Effect analysis

Description

A sample dataset containing 10 investors, their market transactions and the market prices of the traded assets.

Usage

DEanalysis

Format

A list containing two data frames: transactions and marketprices.

investor

id of the investor

type

binary variable indicating the type of operation, B = buy and S = sell

asset

id of the traded asset

quantity

quantity of the traded asset

price

market price of the traded asset

datetime

timestamp of the operation

Checks functions

Description

Functions to perform checks on arguments.

Usage

check_values(
  input_values,
  target_values,
  no_exception = FALSE,
  weak_target = FALSE
)

check_gainloss(df)

release_questions()

Arguments

Value

A result message or NULL.

Functions

• check_values: Check consistency of values against targets and vice versa.

• check_gainloss: Check consistency of gains and losses "values" results.

• release_questions: Release questions

Closest market price

Description

Find the market price closest to a certain datetime and for specific assets.

Usage

closest_market_price(
  asset,
  datetime,
  market_prices,
  price_only = FALSE,
  exact = FALSE,
  substitute_datetime = FALSE
)

Arguments

Value

The data frame of closest market prices.

See Also

evaluate, lubridate::round_date

Difference in time

Description

Financial implementation of base::difftime, that takes into account trading day horizons (including pre and after market hours.)

Usage

difftime_financial(
  from,
  to,
  pre_market = 8,
  after_market = 22,
  units = "hours"
)

difftime_compare(from, to, time_threshold = "0 mins")

Arguments

Value

difftime_financial

returns a numeric value in hours. To convert in a different time unit use base::as.numeric and specify the units argument (units = c("secs", "mins", "hours", "days", "weeks")).

difftime_compare

returns a character string whose possible values are "greater" or "smaller", indicating whether the difftime_financial evaluated between the two dates is greater or smaller than the chosen threshold.

Functions

• difftime_financial: Extension of the base::difftime function to calculate the actual financial difftime taking into account pre and after market moments and financial markets closing days.

• difftime_compare: Comparison of the difftime_financial with respect to a given time threshold.

See Also

base::difftime

Disposition Effect

Description

Compute the disposition effect and the disposition difference.

Usage

disposition_effect(realized_gains, paper_gains, realized_losses, paper_losses)

disposition_difference(gains, losses)

disposition_compute(
  gainslosses,
  dispdiff_value = FALSE,
  aggregate_fun = NULL,
  ...
)

disposition_compute_ts(gainslosses, aggregate_fun = NULL, ...)

disposition_summary(gainslosses, dispdiff_value = FALSE)

disposition_summary_ts(de_timeseries)

Arguments

Details

The disposition effect is defined as DE = (Realized Gain / (Realized Gain - Paper Gain)) - (Realized Loss / (Realized Loss + Paper Loss))

The disposition difference is defined as DD = Realized Gain - |Realized Loss| or DD = Paper Gain - |Paper Loss|

Value

Numeric vector (or scalar) with the value(s) of disposition effect(s) or disposition difference(s).

Functions

• disposition_effect: Compute the disposition effect

• disposition_difference: Compute the disposition difference

• disposition_compute: Compute the disposition effect directly on the investor's portfolio containing realized and paper gains and losses results.

• disposition_compute_ts: Compute the time series disposition effect on the gains and losses results.

• disposition_summary: Wrapper that returns the most important summary statistics related to the disposition effect.

• disposition_summary_ts: Wrapper that returns the most important summary statistics related to the time series disposition effect.

Portfolio evaluation

Description

Calculate the portfolio value as the sum of each asset portfolio quantity times the excess return of each asset with respect to the market.

Usage

evaluate_portfolio(portfolio, market_prices)

Arguments

Value

The portfolio value.

See Also

portfolio_compute, gains_losses, closest_market_price

Gains & Losses

Description

Calculation of the realized gains and losses and the paper gains and losses.

Usage

gains_losses(
  portfolio,
  market_prices,
  transaction_type,
  transaction_asset,
  transaction_quantity,
  transaction_price,
  transaction_datetime,
  previous_datetime,
  time_threshold = "0 mins",
  method = "all",
  allow_short = FALSE,
  verbose = FALSE
)

Arguments

Details

It is essentially a wrapper around paper_compute and realized_compute functions. It is the function that can be used for streaming computations of gains and losses.

Value

A data frame containing the values of realized and paper gains and losses computed by means of the chosen method on each portfolio assets.

See Also

realized_compute, paper_compute, portfolio_compute

Initializers functions

Description

Initializers functions

Usage

initializer_portfolio(investor, assets)

initializer_realized_and_paper(investor, assets, method = "all")

initializer_timeseries_DE(investor, assets, datetimes, method)

Arguments

Value

Empty data.frame of either investor's portfolio, investor's realized and paper gains and losses results, or time series Disposition Effect based on the chosen method.

Functions

• initializer_portfolio: Empty data.frame of investor's portfolio.

• initializer_realized_and_paper: Empty data.frame of investor's realized and paper gains and losses results based on the chosen method.

• initializer_timeseries_DE: Empty data.frame of investor's time series disposition effect based on the chosen method.

Sample investor financial transactions

Description

A sample dataset containing 19 transactions over time.

Usage

investor

Format

A data frame with 19 rows and 6 variables:

investor

id of the investor

type

binary variable indicating the type of operation, B = buy and S = sell

asset

id of the traded asset

quantity

quantity of the traded asset

price

market price of the traded asset

datetime

timestamp of the operation

Pre-process transactions and market prices data frames

Description

These functions allows to pre-process transactions and market prices data frames performing aggregation and subsetting operations.

Usage

aggregate_transactions(portfolio_transactions, unit = "1 mins")

reduce_transactions(portfolio_transactions, unit = "1 mins")

clean_transactions(portfolio_transactions, unit = "1 mins", reduce = FALSE)

aggregate_market_prices(market_prices, unit = NULL, aggregate_price_fun = mean)

subset_market_prices(
  market_prices,
  portfolio_assets,
  portfolio_datetimes,
  unit = NULL
)

generate_data(
  portfolio_transactions,
  market_prices,
  investor_name = NULL,
  unit = NULL,
  subset = FALSE
)

Arguments

Value

A modified version of the input data frame.

Functions

• aggregate_transactions: Aggregate the data frame of investors' transactions that happened at the same datetime.

• reduce_transactions: Reduce the data frame of investors' transactions by aggregating those transactions that happened within a time interval.

• clean_transactions: Clean the data frame of investors' transactions.

• aggregate_market_prices: Aggregate the data frame of market prices with a specific aggregate function within a time interval.

• subset_market_prices: Subset the data frame of market prices based on investor's traded assets and datetimes of transactions.

• generate_data: Generate investors' data from transactions and market prices.

See Also

closest_market_price, lubridate::round_date

Market prices of assets traded by the sample investor

Description

A sample dataset containing 6895 market prices of 5 different assets over time.

Usage

marketprices

Format

A data frame with 6895 rows and 4 variables:

asset

id of the asset

datetime

timestamp of market price

price

market price of the asset

Negative match operator

Description

See base::%in% for details on the match operator. The negative match operator is simply the negation of the match operator obtained via the base::Negate function.

Usage

x %!in% table

Arguments

Value

Logical vector.

Papers' estimation

Description

Compute paper gains and paper losses as either simple counts, total quantities, expected returns and financial duration.

Usage

paper_count(
  portfolio_quantity,
  portfolio_price,
  market_price,
  allow_short = TRUE
)

paper_total(
  portfolio_quantity,
  portfolio_price,
  market_price,
  allow_short = TRUE
)

paper_value(
  portfolio_quantity,
  portfolio_price,
  market_price,
  allow_short = TRUE
)

paper_duration(
  portfolio_quantity,
  portfolio_price,
  market_price,
  datetime_difference = NULL,
  previous_datetime = NULL,
  transaction_datetime = NULL,
  allow_short = TRUE
)

paper_compute(
  portfolio_quantity,
  portfolio_price,
  market_price,
  previous_datetime,
  transaction_datetime,
  assets,
  allow_short = TRUE,
  method = "all"
)

Arguments

Value

The described functions have different return behaviors

• paper_compute returns a data frame containing the values of paper gains and paper losses computed by means of the chosen method on each portfolio assets.

• paper_count returns a named vector containing the values of paper gains and paper losses computed using the count method.

• paper_total returns a named vector containing the values of paper gains and paper losses computed using the total method.

• paper_value returns a named vector containing the values of paper gains and paper losses computed using the value method.

• paper_duration returns a named vector containing the values of paper gains and paper losses computed using the duration method.

In particular:

• RG_"method" contains Realized Gains results

• RL_"method" contains Realized Losses results

• PG_"method" contains Paper Gains results

• PL_"method" contains Paper Losses results

Functions

• paper_count: Computation of paper gains and paper losses as simple counts (default method).

• paper_total: Computation of paper gains and paper losses as total quantity of assets.

• paper_value: Computation of paper gains and paper losses as expected return of assets.

• paper_duration: Computation of paper gains and paper losses as financial duration.

• paper_compute: Wrapper that calls other paper_. functions to compute paper gains and paper losses based on the chosen method.

See Also

realized_compute, gains_losses

Portfolio Compute

Description

Computation of all the transaction updates and the realized and paper gains and losses for each assets.

Usage

portfolio_compute(
  portfolio_transactions,
  market_prices,
  method = "count",
  allow_short = TRUE,
  time_threshold = "0 mins",
  exact_market_prices = TRUE,
  portfolio_driven_DE = FALSE,
  time_series_DE = FALSE,
  assets_time_series_DE = NULL,
  verbose = c(0, 0),
  progress = FALSE
)

Arguments

Value

A data frame containing the investor's portfolio and the values of realized and paper gains and losses computed by means of the chosen method on each portfolio assets.

If time_series_DE is set to TRUE, then also time series disposition effect results are returned.

See Also

realized_compute, paper_compute, gains_losses

Realized and paper results

Description

Results obtained by means of portfolio_compute on the data sets investor and marketprices.

Usage

portfolio_results

Format

A data frame with 5 rows and 21 variables:

investor

id of the investor

asset

id of the traded asset

quantity

quantity of the traded asset at the end of the portfolio updating process

price

last market price of the traded asset

datetime

timestamp of the last operation

RG_count

realized gains via count method

RL_count

realized losses via count method

PG_count

paper gains via count method

PL_count

paper losses via count method

RG_total

realized gains via total method

RL_total

realized losses via total method

PG_total

paper gains via total method

PL_total

paper losses via total method

RG_value

realized gains via value method

RL_value

realized losses via value method

PG_value

paper gains via value method

PL_value

paper losses via value method

RG_duration

realized gains via duration method

RL_duration

realized losses via duration method

PG_duration

paper gains via duration method

PL_duration

paper losses via duration method

Realized and paper results

Description

Results obtained by means of portfolio_compute on the data sets investor and marketprices with time_series_DE = TRUE.

Usage

portfolio_results_ts

Format

A data frame with 19 rows and 6 variables:

investor

id of the investor

datetime

timestamp of the last operation

DEts_count

Partial disposition effect computed at time t

DETs_count

Complete disposition effect computed after updating at time t

DEts_value

Partial disposition difference computed at time t

DETs_value

Complete disposition difference computed after updating at time t

Realized estimation

Description

Compute realized gains and realized losses as either simple counts, total quantities, expected returns and financial duration.

Usage

realized_count(
  portfolio_quantity,
  portfolio_price,
  transaction_quantity,
  transaction_price,
  transaction_type,
  allow_short = TRUE,
  realized_only = FALSE
)

realized_total(
  portfolio_quantity,
  portfolio_price,
  transaction_quantity,
  transaction_price,
  transaction_type,
  allow_short = TRUE,
  realized_only = FALSE
)

realized_value(
  portfolio_quantity,
  portfolio_price,
  transaction_quantity,
  transaction_price,
  transaction_type,
  allow_short = TRUE,
  realized_only = FALSE
)

realized_duration(
  portfolio_quantity,
  portfolio_price,
  transaction_quantity,
  transaction_price,
  transaction_type,
  previous_transaction_datetime,
  previous_datetime,
  transaction_datetime,
  allow_short = TRUE,
  realized_only = FALSE
)

realized_compute(
  portfolio_quantity,
  portfolio_price,
  transaction_quantity,
  transaction_price,
  transaction_type,
  previous_transaction_datetime,
  previous_datetime,
  transaction_datetime,
  transaction_asset,
  allow_short = TRUE,
  realized_only = FALSE,
  method = "all"
)

realized_empty(transaction_asset, method = "all")

Arguments

Value

The described functions have different return behaviors

• realized_compute returns a data frame containing the values of realized and paper gains and losses computed by means of the chosen method on each portfolio assets.

• realized_count returns a named vector containing the values of realized and paper gains and losses computed using the count method.

• realized_total returns a named vector containing the values of realized and paper gains and losses computed using the total method.

• realized_value returns a named vector containing the values of realized and paper gains and losses computed using the value method.

• realized_duration returns a named vector containing the values of realized and paper gains and losses computed using the duration method.

• realized_empty returns a named vector containing empty values of realized and paper gains and losses computed using the chosen method.

In particular:

• RG_"method" contains Realized Gains results

• RL_"method" contains Realized Losses results

• PG_"method" contains Paper Gains results

• PL_"method" contains Paper Losses results

Functions

• realized_count: Computation, as simple counts, of realized gains and realized losses of the traded asset.

• realized_total: Computation, as total quantity, of realized gains and realized losses of the traded asset.

• realized_value: Computation, as expected return, of realized gains and realized losses of the traded asset.

• realized_duration: Computation, as financial duration, of realized gains and realized losses of the traded asset.

• realized_compute: Wrapper that calls other realized_. functions to compute realized gains and realized losses of the traded asset based on the chosen method.

• realized_empty: Simple function to obtain empty results for realized and paper computations based on the chosen method.

See Also

paper_compute, gains_losses

Update results over time

Description

Update investor's portfolio, realized and paper results and time series disposition effect computations.

Usage

update_price(
  portfolio_quantity,
  portfolio_price,
  transaction_quantity,
  transaction_price,
  transaction_type
)

update_datetime(
  portfolio_quantity,
  portfolio_datetime,
  transaction_quantity,
  transaction_datetime,
  transaction_type
)

update_quantity(portfolio_quantity, transaction_quantity)

update_portfolio(
  portfolio,
  transaction_asset,
  transaction_quantity,
  transaction_price,
  transaction_datetime,
  transaction_type
)

update_realized_and_paper(realized_and_paper, new_realized_and_paper, method)

update_timeseries_DE(
  timeseries_DE,
  realized_and_paper,
  gainslosses,
  transaction_id,
  assets_time_series_DE = NULL,
  method
)

update_expectedvalue(realized_and_paper, num_transaction_assets)

Arguments

Value

The updated input data.

Functions

• update_price: Update the portfolio price of the traded asset.

• update_datetime: Update the portfolio datetime of the traded asset.

• update_quantity: Update the portfolio quantity of the traded asset.

• update_portfolio: Update the portfolio with the new quantity, price and datetime of the traded asset.

• update_realized_and_paper: Update the realized and paper gains and losses results with the results obtained on the last occurred transaction.

• update_timeseries_DE: Update the time series disposition effect averaging values over time.

• update_expectedvalue: Update the realized and paper gains and losses results averaging the total value by the number of transactions for each asset.

Utilities

Description

Utilities functions

Usage

ewise_mean(x, y, na.rm = FALSE, zero.substitute = FALSE)

Arguments

Value

Numeric vector.

Functions

• ewise_mean: Element-wise mean calculation.