Package 'filters.trade'

filters.trade Package

Description

A filter system for selecting trading instruments. add_filter() and apply_filter() are the two entry points of the package.

Author(s)

Maintainer: Joe Zhu [email protected]

Authors:

• Joe Zhu [email protected]

---

Add a New Filter Definition

Description

Add a new filter definition or overwrite an existing one. A filter binds an unevaluated condition to a target dataset so that it can be applied later by apply_filter(). Unless character_only = TRUE, condition is captured with substitute() and therefore written without quotes.

Usage

add_filter(
  id,
  title,
  target,
  condition,
  character_only = FALSE,
  overwrite = FALSE
)

Arguments

id	character The id of this filter. Only upper case letters and numbers are allowed, e.g. "LARGECAP".
title	character The title of the filter
target	character The target dataset of the filter, e.g. "TICKERS" or "PRICES"
condition	The filter condition
character_only	logical. Is condition a string? Defaults to FALSE.
overwrite	logical Should existing filters be overwritten? Defaults to FALSE.

Value

A list of title, target and condition, invisibly

Examples

add_filter(
  id = "LARGECAP",
  title = "Large Cap",
  target = "TICKERS",
  condition = MARKET_CAP >= 1e10
)

add_filter(
  id = "TECH",
  title = "Technology Sector",
  target = "TICKERS",
  condition = "SECTOR == 'Technology'",
  character_only = TRUE
)

---

Apply a Filter to a Dataset or List of Datasets

Description

Apply a Filter to a Dataset or List of Datasets

Usage

apply_filter(data, ...)

## Default S3 method:
apply_filter(data, ...)

## S3 method for class 'data.frame'
apply_filter(data, id, target = deparse(substitute(data)), verbose = TRUE, ...)

## S3 method for class 'list'
apply_filter(data, id, verbose = TRUE, ...)

Arguments

data	data.frame or named list of data.frames
...	Not used.
id	character. The ID of one or more filters defined with add_filter(), combined with underscores. An empty string applies no filter.
target	character. The name of the dataset, e.g. "TICKERS" or "PRICES"
verbose	logical. Should informative messages be printed? Defaults to TRUE.

Value

A new data.frame or list of data.frames filtered based upon the condition defined for id. When the master trading code dataset is among the filter targets, every other dataset is restricted to the surviving trading codes.

Examples

tickers <- data.frame(
  SYMBOL = c("AAA", "BBB", "CCC"),
  SECTOR = c("Technology", "Energy", "Technology"),
  stringsAsFactors = FALSE
)
prices <- data.frame(
  SYMBOL = c("AAA", "BBB", "CCC"),
  CLOSE = c(10, 20, 30),
  stringsAsFactors = FALSE
)

add_filter(
  id = "TECH",
  title = "Technology Sector",
  target = "TICKERS",
  condition = SECTOR == "Technology",
  overwrite = TRUE
)

apply_filter(tickers, "TECH", target = "TICKERS")
apply_filter(list(tickers = tickers, prices = prices), "TECH")

---

Get a Filter Definition

Description

Get a Filter Definition

Usage

get_filter(id)

Arguments

id	character. The filter ID

Value

A list with elements title, target and condition

Examples

add_filter(
  id = "LARGECAP",
  title = "Large Cap",
  target = "TICKERS",
  condition = MARKET_CAP >= 1e10,
  overwrite = TRUE
)
get_filter("LARGECAP")

## Filter `FOO` does not exist
try(get_filter("FOO"))

---

Get Multiple Filter Definitions

Description

Filter IDs are combined into a single string separated by underscores, so "US_LARGECAP" requests the two filters US and LARGECAP.

Usage

get_filters(ids)

Arguments

ids	character. The filter IDs as a single string separated by underscores

Value

A named list of filter definitions

Examples

add_filter(
  id = "US",
  title = "US Listed",
  target = "TICKERS",
  condition = EXCHANGE %in% c("NYSE", "NASDAQ"),
  overwrite = TRUE
)
get_filters("US_LARGECAP")

---

List All Filters

Description

List all filter definitions currently held in the registry.

Usage

list_all_filters()

Value

A data.frame with columns id, title, target and condition

Examples

list_all_filters()

---

Load Filter Definitions

Description

Load filter definitions from a yaml file. Each top level key is a filter id and maps to the fields title, target and condition.

Usage

load_filters(yaml_file, overwrite = FALSE)

Arguments

yaml_file	character. A path to a yaml file containing filter definitions
overwrite	logical. Should existing filter definitions be overwritten? Defaults to FALSE.

Value

On success, load_filters() returns TRUE invisibly

Examples

filter_definitions <- system.file("filters_eg.yaml", package = "filters.trade")
if (interactive()) file.edit(filter_definitions)
load_filters(filter_definitions, overwrite = TRUE)

---

New Zealand Exchange (NZX) trading instruments

Description

A master list of trading instruments listed on New Zealand's Exchange (NZX), in the shape filters.trade expects of the master trading-code dataset. The join key is the SYMBOL column; every other column is an attribute that a filter condition can reference unquoted.

Usage

nz_data

Format

A data.frame with 168 rows and 7 columns:

SYMBOL

Trading code, e.g. "ACE.NZ". The code column.

NAME

Company or instrument name.

EXCHANGE

Exchange code; always "NZX".

SECTOR

Sector classification.

MARKET_CAP

Market capitalisation in NZD.

DIV_YIELD

Dividend yield in percent.

ADV_20D

Average daily volume over 20 days, in shares.

Source

SYMBOL and NAME are from ⁠~/homepage-stock/data/nz_list.csv⁠. EXCHANGE, SECTOR, MARKET_CAP, DIV_YIELD and ADV_20D are synthetic placeholders generated in data-raw/nz_data.R for example use.

---