Package 'FinNet' reference manual

Title:	Quickly Build and Manipulate Financial Networks
Description:	Providing classes, methods, and functions to deal with financial networks. Users can easily store information about both physical and legal persons by using pre-made classes that are studied for integration with scraping packages such as 'rvest' and 'RSelenium'. Moreover, the package assists in creating various types of financial networks depending on the type of relation between its units depending on the relation under scrutiny (ownership, board interlocks, etc.), the desired tie type (valued or binary), and renders them in the most common formats (adjacency matrix, incidence matrix, edge list, 'igraph', 'network'). There are also ad-hoc functions for the Fiedler value, global network efficiency, and cascade-failure analysis.
Authors:	Fabio Ashtar Telarico [aut, cre]
Maintainer:	Fabio Ashtar Telarico <[email protected]>
License:	GPL (>= 3)
Version:	0.2.2
Built:	2024-10-31 18:20:43 UTC
Source:	https://github.com/fatelarico/finnet

Coerce into (a list of) `firm` object(s)

Description

Generic function to coerce other other classes into the S4 class firm representing a firm (legal person)

Usage

as.firm(x, ...)
as.firm(x, ...)

Arguments

`x`	The object to coerce
`...`	Arguments passed to class-specific methods

Value

An object of class firm or a (usually named) list of them, depending on the available method for the object being coerced.

Author(s)

Telarico, Fabio Ashtar

Coerce a `financial_matrix` object into a list of `firm` objects

Description

'as.firm' method for an object of class financial_matrix

Usage

## S4 method for signature 'financial_matrix'
as.firm(x, ...)
## S4 method for signature 'financial_matrix'
as.firm(x, ...)

Arguments

`x`	The `financial_matrix` object to coerce
`...`	Optional arguments

Value

A (usually named) list of firm objects the length of which equals the number of rows and columns of the provided financial_matrix

Author(s)

Telarico, Fabio Ashtar

Compute Bonacich centrality on a Firm-Firm network

Description

Based in part on the earlier work of Katz (1953) and Hubbell (1965), Bonacich (1972a, 1972b) argued that a point's centrality in a network should depend on three criteria: (1) the number of links to other points; (2) the intensity of the links; and (3) the centrality of those with whom one is linked. This centrality has been applied to board interlocks for the first time by Mizruchi and Bunting (1981).

Usage

bonacich(FF, exo = 1, alpha = NULL, tol = 1e-07)
bonacich(FF, exo = 1, alpha = NULL, tol = 1e-07)

Arguments

`FF`	An object of class `financial_matrix` or an object of class `igraph_financial` (or `network_financial`) produced by `FF` and related functions to represent the relations between firms (legal person).
`exo`	A value for the exogenous parameter of the Bonacich centrality. Defaults to `1`.
`alpha`	A value for the alpha parameter of the Bonacich centrality. Defaults to a function of the matrix's largest eigenvalue.
`tol`	A value for the tolerance of the Bonacich centrality. Defaults to `1e-07`.

Value

A scalar vector with the Bonacich centrality of each firm.

Author(s)

Telarico, Fabio Ashtar

References

Katz, Leo. 1953. “A new status index derived from sociometric analysis.” Psychometrika 18: 39-43 doi:10.1007/BF02289026.

Bonacich, Phillip. 1972a. “Technique for Analyzing Overlapping Memberships.” Sociological Methodology 4: 176–85. doi:10.2307/270732.

Bonacich, Phillip. 1972b. “Factoring and Weighting Approaches to Status Scores and Clique Identification.” The Journal of Mathematical Sociology 2 (1): 113–20. doi:10.1080/0022250X.1972.9989806.

Mizruchi, Mark S., and David Bunting. 1981. “Influence in Corporate Networks: An Examination of Four Measures.” Administrative Science Quarterly 26, no. 3: 475–89. doi:10.2307/2392519.

Examples

# Find the Bonacich centralities for all the companies that Berkshire Hathaway holds
data('firms_BKB')
FF_BKB <- FF.norm.ownership(firms_BKB)
bonacich(FF_BKB)

# Find the Bonacich centralities for all the companies that Berkshire Hathaway holds
data('firms_BKB')
FF_BKB <- FF.norm.ownership(firms_BKB)
bonacich(FF_BKB)

Perform cascade failure analysis

Description

Cascade failure analysis (CFA) involves understanding how failures in one part of the network might cascade to other parts. Networks capable of isolating such failures or minimizing their effects demonstrate higher robustness.

Usage

cfa(
  ...,
  ordering = "tot",
  custom.order = NULL,
  decreasing = TRUE,
  Rcpp = ifelse(requireNamespace("Rcpp", quietly = TRUE), yes = TRUE, no = FALSE)
)
cfa(
  ...,
  ordering = "tot",
  custom.order = NULL,
  decreasing = TRUE,
  Rcpp = ifelse(requireNamespace("Rcpp", quietly = TRUE), yes = TRUE, no = FALSE)
)

Arguments

`...`	Firm-Firm network in one of the following classes: `financial_matrix` produced by `FF` and family; `network_financial` or `network` if the relevant package is installed; `igraph_financial` or `igraph` if the relevant package is installed.
`ordering`	In what order to remove the firms, the completing ordering is always returned as part of the result. Take the following values: `random` - Random order, corresponds to percolation theory `out` - By out-degree `in` - By in-degree `tot` - By sum of in- and out-degre (default) `custom` - Customised ordering via `custom.order`
`custom.order`	Order in which to remove the firms. If `ordering` is not 'custom', it is ignored. Defaults to `NULL`.
`decreasing`	Logical, defaults to `TRUE`. Only evaluated if `ordering` is neither 'custom' nor 'random'. if `TRUE` - the ordering is by decreasing degree and higher in-/out-/total-degree firms are removed first if `FALSE` - the ordering is by increasing degree and higher in-/out-/total-degree firms are removed last
`Rcpp`	Whether to use the `C++` or native-`R` version of the search algorithm. Defaults to `TRUE` if the package `Rcpp` is installed.

Value

A data.frame with one row for the result of the CFA after each node is removed. The columns report:

l_scc - Size of the largest strongly connected component
rem_id - ID of the firm removed
rem_pos - Position of the firm removed (row/column number)
n_scc - Number of strongly connected components
n_rem - Number of firms removed
n_left - Number of firms left

Author(s)

Telarico, Fabio Ashtar

References

Elliott, Matthew, Benjamin Golub, and Matthew O. Jackson. ‘Financial Networks and Contagion’. American Economic Review 104, no. 10 (1 October 2014): 3115–53. doi:10.1257/aer.104.10.3115.

Examples

# Create a matrix
mat <- matrix(c(
    0, 1, 0, 1, 0, 1, 0, 0,
    0, 0, 1, 0, 0, 0, 0, 0,
    1, 0, 0, 0, 0, 0, 0, 0,
    0, 1, 1, 0, 1, 0, 0, 0,
    0, 0, 0, 1, 0, 1, 0, 0,
    0, 0, 1, 0, 0, 0, 1, 0,
   0, 0, 0, 0, 0, 1, 0, 0,
    0, 0, 0, 0, 1, 0, 1, 1
  ),ncol = 8, byrow = TRUE)
# Add rownames
rownames(mat) <- paste0("Firm", LETTERS[1:ncol(mat)])

# Create a FF matrix
mat <- methods::new('financial_matrix',
                    M = mat,
                    relation = c('own'),
                    legal_form = c('JSC'),
                    sector = c('A.01'),
                    revenues = c(NA),
                    capitalisation = c(NA),
                    currency = c('USD'))

# Notice the differnce between:
# a. CFA with ordering by in-degree (decreasing)
# b. CFA with ordering by in-degree (increasing)
cfa(mat, ordering = 'in', decreasing = FALSE)
# But ordering by increasing (decreasing) in-degree is the
# same as ordering by decreasing (increasing) out-degree and
# vice versa!
cfa(mat, ordering = 'out', decreasing = FALSE) # By out-degree (increasing)

# Create a matrix
mat <- matrix(c(
    0, 1, 0, 1, 0, 1, 0, 0,
    0, 0, 1, 0, 0, 0, 0, 0,
    1, 0, 0, 0, 0, 0, 0, 0,
    0, 1, 1, 0, 1, 0, 0, 0,
    0, 0, 0, 1, 0, 1, 0, 0,
    0, 0, 1, 0, 0, 0, 1, 0,
   0, 0, 0, 0, 0, 1, 0, 0,
    0, 0, 0, 0, 1, 0, 1, 1
  ),ncol = 8, byrow = TRUE)
# Add rownames
rownames(mat) <- paste0("Firm", LETTERS[1:ncol(mat)])

# Create a FF matrix
mat <- methods::new('financial_matrix',
                    M = mat,
                    relation = c('own'),
                    legal_form = c('JSC'),
                    sector = c('A.01'),
                    revenues = c(NA),
                    capitalisation = c(NA),
                    currency = c('USD'))

# Notice the differnce between:
# a. CFA with ordering by in-degree (decreasing)
# b. CFA with ordering by in-degree (increasing)
cfa(mat, ordering = 'in', decreasing = FALSE)
# But ordering by increasing (decreasing) in-degree is the
# same as ordering by decreasing (increasing) out-degree and
# vice versa!
cfa(mat, ordering = 'out', decreasing = FALSE) # By out-degree (increasing)

Create any firm-firm (FF) matrix

Description

General function to create a firm-firm (FF) matrix

Usage

FF(..., who, ties, id_as_firm_name = NULL, Matrix = NULL, self_ties = FALSE)
FF(..., who, ties, id_as_firm_name = NULL, Matrix = NULL, self_ties = FALSE)

Arguments

`...`	Either multiple objects of class `firm` or a list of such objects
`who`	Whether to take into account: (`ownership`) co-ownership ; (`management`) board interlocks, or `both` (recognises minimum unambiguous strings).
`ties`	Type of ties to create. Possible values: `binary`; `naive`; `share` (see Details).
`id_as_firm_name`	Whether to use the ticker as the firm's name. Defaults to `TRUE` if all firms' id is neither `NULL` nor `NA`.
`Matrix`	Whether to use the `Matrix` package. Defaults to `TRUE` when any matrix in the pipeline contains more than 10,000 cells and the package is installed.
`self_ties`	Whether to allow self-ties (a 'loop' in graph theory). Defaults to `FALSE`.

Details

See more specific functions for a detailed overview:

for board interlocks (who == 'management'):

FF.binary.management, if ties = 'binary';
FF.binary.management, if ties = 'naive';
FF.norm.management, if ties = 'share'.

for co-ownership (who == 'ownership'):

FF.binary.ownership, if ties = 'binary';
FF.naive.ownership, if ties = 'naive';
FF.norm.ownership, if ties = 'share'.

for both co-ownership and board interlocks (who == 'both'):

FF.binary.both, if ties = 'binary';
FF.naive.both, if ties = 'naive';
FF.norm.both, if ties = 'share'.

Value

A matrix object of class financial_matrix(possibly using the Matrix package)

Author(s)

Telarico, Fabio Ashtar

Examples


# Create the normalised FF matrix of Berkshire Hathaway's holdings by boards interlocks
data('firms_BKB')
FF <- FF(firms_BKB, who = 'man', ties = 'share')

# Create the normalised FF matrix of Berkshire Hathaway's holdings by boards interlocks
data('firms_BKB')
FF <- FF(firms_BKB, who = 'man', ties = 'share')

Basic methods for objects of class `financial_matrix`

Description

Basic methods for objects of class financial_matrix

Usage

## S4 method for signature 'financial_matrix'
rownames(x, do.NULL = TRUE, prefix = "row")

## S4 method for signature 'financial_matrix'
colnames(x, do.NULL = TRUE, prefix = "row")
## S4 method for signature 'financial_matrix'
rownames(x, do.NULL = TRUE, prefix = "row")

## S4 method for signature 'financial_matrix'
colnames(x, do.NULL = TRUE, prefix = "row")

Arguments

`x`	The `financial_matrix` object to operate on
`do.NULL`	Whether to use `NULL` names. Defaults to `FALSE`
`prefix`	Prefix for created names (if `do.NULL` is `FALSE` and names are `NULL`)

Details

Mind that usually the rows and columns are named after the firm's tickers.

Value

A character vector of length equal to the number of rows (or columns) in the financial_matrix corresponding to the names of the rows (or columns)

Author(s)

Telarico, Fabio Ashtar

Basic method to check to compare values in a `financial_matrix` object

Description

Basic method to check to compare values in a financial_matrix object

Usage

## S4 method for signature 'financial_matrix,logical'
duplicated(x, incomparables = FALSE, ...)

## S4 method for signature 'financial_matrix,logical'
unique(x, incomparables = FALSE, ...)
## S4 method for signature 'financial_matrix,logical'
duplicated(x, incomparables = FALSE, ...)

## S4 method for signature 'financial_matrix,logical'
unique(x, incomparables = FALSE, ...)

Arguments

x

The financial_matrix object to operate on

incomparables

Either:

a vector of values that cannot be compared
or FALSE, in which case all values can be compared

...

Arguments passed to the relevant matrix method

Value

duplicated: A logical array with the same dimensions and dimnames of the financial_matrix's matrix component.
unique: The matrix component is coerced into a vector and then returned, but with only one copy of each duplicated element.

Author(s)

Telarico, Fabio Ashtar

Mathematical methods for `financial_matrix` objects

Description

isSymmetric checks only the matrix-like part summary operates on all numeric attributes and the matrix-like part

Usage

## S4 method for signature 'financial_matrix'
isSymmetric(object, ...)

## S4 method for signature 'financial_matrix'
summary(object, ...)
## S4 method for signature 'financial_matrix'
isSymmetric(object, ...)

## S4 method for signature 'financial_matrix'
summary(object, ...)

Arguments

`object`	The `financial_matrix` object to operate on
`...`	Arguments passed to the relevant `matrix` method

Details

Mathematical methods for financial_matrix objects

Value

isSymmetric: a boolean, TRUE if the matrix is symmetric, FALSE otherwise;
summary: a list of length equal to the number of numeric attributes possed by the financial_matrix (maximum three, the matrix itself, revenues, and capitalisation) assumed as measured on the same scale and denominated in the same currency). Each element of the list of class c('summaryDefault', 'table') which has specialized format and print methods

Author(s)

Telarico, Fabio Ashtar

Number of rows/columns in a `financial_matrix` object

Description

Unlike most other methods (i.e., duplicated, isSymmetric, summary, rownames, and colnames), these methods act on both the matrix-like and the other components of a financial_matrix object.

Usage

## S4 method for signature 'financial_matrix'
ncol(x)

## S4 method for signature 'financial_matrix'
nrow(x)
## S4 method for signature 'financial_matrix'
ncol(x)

## S4 method for signature 'financial_matrix'
nrow(x)

Arguments

`x`	The `financial_matrix` object to operate on

Details

Checks if the length of the names matches that of the other attributes that are not NA or structurally of unitary length (i.e., the slots M and relation).

Value

A single numeric, the number of rows (columns) in the matrix. It also prints a message to the console if any of the object's other attributes (e.g., capitalisation) is not conformed to the matrix's dimensions

Author(s)

Telarico, Fabio Ashtar

Method to subset a `financial_matrix`

Description

Subsets all components of a financial_matrix object

Usage

## S4 method for signature 'financial_matrix'
subset(x, ...)
## S4 method for signature 'financial_matrix'
subset(x, ...)

Arguments

`x`	The `financial_matrix` object to operate on
`...`	Arguments passed to the relevant `matrix` method

Value

A financial_matrix object, subsetted to the desired firms

Author(s)

Telarico, Fabio Ashtar

Create a complete binary firm-firm (FF) matrix

Description

Function to create a binary firm-firm (FF) matrix based on both common ownership and board interlocks

Usage

FF.binary.both(
  ...,
  id_as_firm_name = NULL,
  Matrix = NULL,
  self_ties = FALSE,
  combining = "sum"
)
FF.binary.both(
  ...,
  id_as_firm_name = NULL,
  Matrix = NULL,
  self_ties = FALSE,
  combining = "sum"
)

Arguments

`...`	Either multiple objects of class `firm` or a list of such objects
`id_as_firm_name`	Whether to use the ticker as the firm's name. Defaults to `TRUE` if all firms' id is neither `NULL` nor `NA`.
`Matrix`	Whether to use the `Matrix` package. Defaults to `TRUE` when any matrix in the pipeline contains more than 10,000 cells and the package is installed.
`self_ties`	Whether to allow self-ties (a 'loop' in graph theory). Defaults to `FALSE`.
`combining`	How to combine the FF matrix for managers and that for owners. Possible values: `sum`; `mean` or `average`; `min`; `max`;

Details

The ties' value will be: $1$ if there is at least one common manager or owner, $0$ otherwise.

Value

A matrix object of class financial_matrix(possibly using the Matrix package)

Author(s)

Telarico, Fabio Ashtar

Examples


# Create the complete binary firm-firm matrix for the companies held by Berkshire Hathaway
data('firms_BKB')
FF <- FF.binary.both(firms_BKB)


# Create the complete binary firm-firm matrix for the companies held by Berkshire Hathaway
data('firms_BKB')
FF <- FF.binary.both(firms_BKB)

Create a binary firm-firm (FF) matrix for board interlocks

Description

Function to create a binary firm-firm (FF) matrix based on board interlocks

Usage

FF.binary.management(
  ...,
  id_as_firm_name = NULL,
  Matrix = NULL,
  self_ties = FALSE
)
FF.binary.management(
  ...,
  id_as_firm_name = NULL,
  Matrix = NULL,
  self_ties = FALSE
)

Arguments

`...`	Either multiple objects of class `firm` or a list of such objects
`id_as_firm_name`	Whether to use the ticker as the firm's name. Defaults to `TRUE` if all firms' id is neither `NULL` nor `NA`.
`Matrix`	Whether to use the `Matrix` package. Defaults to `TRUE` when any matrix in the pipeline contains more than 10,000 cells and the package is installed.
`self_ties`	Whether to allow self-ties (a 'loop' in graph theory). Defaults to `FALSE`.

Value

A matrix object of class financial_matrix(possibly using the Matrix package)

Author(s)

Telarico, Fabio Ashtar

Examples


# Create the binary FF matrix of Berkshire Hathaway's holdings by boards interlock
data('firms_BKB')
FF <- FF.binary.management(firms_BKB)


# Create the binary FF matrix of Berkshire Hathaway's holdings by boards interlock
data('firms_BKB')
FF <- FF.binary.management(firms_BKB)

Create a binary firm-firm (FF) matrix for common ownership

Description

Function to create a binary firm-firm (FF) matrix based on common ownership

Usage

FF.binary.ownership(
  ...,
  id_as_firm_name = NULL,
  Matrix = NULL,
  self_ties = FALSE
)
FF.binary.ownership(
  ...,
  id_as_firm_name = NULL,
  Matrix = NULL,
  self_ties = FALSE
)

Arguments

`...`	Either multiple objects of class `firm` or a list of such objects
`id_as_firm_name`	Whether to use the ticker as the firm's name. Defaults to `TRUE` if all firms' id is neither `NULL` nor `NA`.
`Matrix`	Whether to use the `Matrix` package. Defaults to `TRUE` when any matrix in the pipeline contains more than 10,000 cells and the package is installed.
`self_ties`	Whether to allow self-ties (a 'loop' in graph theory). Defaults to `FALSE`.

Value

A matrix object of class financial_matrix(possibly using the Matrix package)

Author(s)

Telarico, Fabio Ashtar

Examples


# Create the binary FF matrix of Berkshire Hathaway's holdings by common ownership
data('firms_BKB')
FF <- FF.binary.ownership(firms_BKB)


# Create the binary FF matrix of Berkshire Hathaway's holdings by common ownership
data('firms_BKB')
FF <- FF.binary.ownership(firms_BKB)

Easily represent a firm-firm (FF) network using the package `igraph`

Description

Create an object of class igraph from the package igraph using a FF matrix of class financial_matrix using all the default aesthetic options

Usage

FF.graph(x, aesthetic = c("simple", "nice"))
FF.graph(x, aesthetic = c("simple", "nice"))

Arguments

`x`	A matrix-like object produced by `FF` and related functions.
`aesthetic`	Choose a pre-set for the graph's look. Either `'simple'` or `'nice'` (see Details).

Details

This function does not allow for any of the additional arguments that can be passed to FF.graph.custom.

Value

A network in the desired format

Loops and values

Loops will be allowed if at least one of the matrix's diagonal entries is not zero. The igraph will be valued if at least one entry of the matrix is neither zero nor one.

Instead, if aesthetic is set to 'simple':

The width of the ties is 1;
The colour of the ties is #b4b4b4 (Philippine Silver);
The size of the nodes is 5;
The colour of the nodes is #081677 (Gentian blue).

Otherwise, if aesthetic is set to 'nice':

The width of the ties is 1;
The colour of the ties is a grey scale reflecting tie strength if the graph is valued, otherwise it is #b4b4b4 (Philippine Silver);
The size of the nodes reflects their capitalisation if all firms have data on it and ranges between 1 and 5, otherwise it is 5 for all nodes;
The colour of the nodes reflects their sector if all firms have data on it is taken from a built-in palette, otherwise it is #081677 (Gentian blue).

Author(s)

Telarico, Fabio Ashtar

Examples

# Create a nice graph representation of the binary FF of
# Berkshire Hataway's holdings based on common ownership
data("firms_BKB")
x <- FF.naive.ownership(firms_BKB)
FF.graph(x = x, aesthetic = 'nice')

# Create a nice graph representation of the binary FF of
# Berkshire Hataway's holdings based on common ownership
data("firms_BKB")
x <- FF.naive.ownership(firms_BKB)
FF.graph(x = x, aesthetic = 'nice')

Represent a firm-firm (FF) network using the package `igraph`

Description

Create an object of class graph from the package igraph using a FF matrix of class financial_matrix

Usage

FF.graph.custom(
  x,
  vertex.size = NULL,
  vertex.colour = NULL,
  edge.width = NULL,
  edge.greyscale = NULL,
  directed = TRUE,
  loops = FALSE,
  weighted = any(x@M %in% c(0, 1)),
  ...
)
FF.graph.custom(
  x,
  vertex.size = NULL,
  vertex.colour = NULL,
  edge.width = NULL,
  edge.greyscale = NULL,
  directed = TRUE,
  loops = FALSE,
  weighted = any(x@M %in% c(0, 1)),
  ...
)

Arguments

`x`	A matrix-like object produced by `FF` and related functions
`vertex.size`	Which piece of information on the firms should be used to represent the nodes' size (see Details).
`vertex.colour`	Which piece of information on the firms should be used to represent the nodes' colours (see Details).
`edge.width`	Whether to use the edges' width to represent tie strength. Defaults to `FALSE`.
`edge.greyscale`	Whether to use the edges' colour to represent tie strength through a grey scale. Defaults to `TRUE` if the matrix is valued.
`directed`	Whether the network should be directed. Defaults to `TRUE`
`loops`	Whether the network should have loops. Defaults to `FALSE`
`weighted`	Whether the ties/edges should be weighted. Defaults to `TRUE` if any element of the matrix equals neither 0 nor 1
`...`	Aliases to the other parameters and additional settings (see Details).

Details

This function allows for a number of additional arguments.

Value

A network in the desired format

What can be passed to `vertex.colour` and `vertex.size`

The pieces of information that is possible to pass to vertex.size and vertex.colour are:

capitalisation, will be arranged into steps (see capitalisation.bins below)
revenue, will be arranged into steps (see revenues.bins below)
legal_form
sector
currency

What can be passed to `edge.width` and `edge.greyscale`

The pieces of information that is possible to pass to edge.width and edge.greyscale are:

capitalisation
revenue

Additional parameters related to `vertex.size`

The effect of the additional parameters that modify the behaviour of vertex.size are:

vertex.size.max (defaults to 5) :

if vertex.size or one of its aliases is specified, this is the size of the biggest vertex;
if neither vertex.size nor any of its aliases is given, this is the size of ALL vertices.

vertex.size.min (defaults to 1):

if vertex.size or one of its aliases is specified, this is the size of the smallest vertex;
if neither vertex.size nor any of its aliases is given, it is ignored.

Additional parameters related to `vertex.colour`

The only additional parameter related to vertex.colour is vertex.colour.palette. It supports a vector of RGB or named colours (see colours for all named colours in R). It also accepts complete calls to functions that return a such a vector like RColorBrewer::brewer.pal(n, name) or viridisLite::viridis(n, option). If the palette is too short, it will be extended automatically using colorRampPalette. If the palette is not declared, but this arguemnt is TRUE, it will defaulr to the following vector of colours:

#00204D, Oxford Blue
#31446B, Police Blue
#666970, Dim Grey
#958F78, Artichoke
#CBBA69, Dark Khaki
#FFEA46, Gargoyle Gas

If the argument is FALSE, NULL or NA, the vertex will be coloured of #081677 (Gentian blue).

Additional parameters related to `edge.width`

edge.width.max (defaults to 5) :

if edge.width or one of its aliases is specified, this is the thickness of the thickest edge;
if neither edge.width nor any of its aliases is given, this is the thickness of ALL edges

edge.width.min (defaults to 1):

if edge.width or one of its aliases is specified, this is the thickness of the slimmest edge;
if neither edge.width nor any of its aliases is given, it is ignored.

Additional parameters related to `edge.greyscale`

edge.greyscale.darkest (defaults to 5) :

if edge.greyscale or one of its aliases is specified, this is the thickness of the thickest edge;
if neither edge.greyscale nor any of its aliases is given, this is the thickness of ALL edges

edge.greyscale.fairest (defaults to 1):

if edge.greyscale or one of its aliases is specified, this is the thickness of the slimmest edge;
if neither edge.greyscale nor any of its aliases is given, it is ignored.

Several aliases are accepted for all arguments, except M:

for vertex.size: node.size
for vertex.colour: vertex.color, node.colour, and node.color;
for edge.width: tie.width
for edge.greyscale: tie.grayscale, tie.greyscale, and edge.grayscale

Author(s)

Telarico, Fabio Ashtar

Examples

# Create the graph representation of the binary FF of
# Berkshire Hataway's holdings based on common ownership
data("firms_BKB")
x <- FF.naive.ownership(firms_BKB)
FF.graph.custom(x = x, node.size = 3)

# Create the graph representation of the binary FF of
# Berkshire Hataway's holdings based on common ownership
data("firms_BKB")
x <- FF.naive.ownership(firms_BKB)
FF.graph.custom(x = x, node.size = 3)

Create a complete naive-valued firm-firm (FF) matrix

Description

Function to create a naive-valued firm-firm (FF) matrix based on both common ownership and board interlocks

Usage

FF.naive.both(
  ...,
  id_as_firm_name = NULL,
  Matrix = NULL,
  self_ties = FALSE,
  combining = "sum"
)
FF.naive.both(
  ...,
  id_as_firm_name = NULL,
  Matrix = NULL,
  self_ties = FALSE,
  combining = "sum"
)

Arguments

`...`	Either multiple objects of class `firm` or a list of such objects
`id_as_firm_name`	Whether to use the ticker as the firm's name. Defaults to `TRUE` if all firms' id is neither `NULL` nor `NA`.
`Matrix`	Whether to use the `Matrix` package. Defaults to `TRUE` when any matrix in the pipeline contains more than 10,000 cells and the package is installed.
`self_ties`	Whether to allow self-ties (a 'loop' in graph theory). Defaults to `FALSE`.
`combining`	How to combine the FF matrix for managers and that for owners. Possible values: `sum`; `mean` or `average`; `min`; `max`;

Details

The ties' value will reflect the count of common owners and membership depending on combining:

sum: sum of the counts;
mean or average: average of the counts;
min: minimum of the counts;
max: maximum of the counts.

Value

A matrix object of class financial_matrix(possibly using the Matrix package)

Author(s)

Telarico, Fabio Ashtar

Examples


# Create the complete naive firm-firm matrix for the companies held by Berkshire Hathaway
data('firms_BKB')
FF <- FF.naive.both(firms_BKB)

# Create the complete naive firm-firm matrix for the companies held by Berkshire Hathaway
data('firms_BKB')
FF <- FF.naive.both(firms_BKB)

Create a naive-valued firm-firm (FF) matrix for boards interlocks

Description

Function to create a naive-valued firm-firm (FF) matrix based on boards interlocks

Usage

FF.naive.management(
  ...,
  id_as_firm_name = NULL,
  Matrix = NULL,
  self_ties = FALSE
)
FF.naive.management(
  ...,
  id_as_firm_name = NULL,
  Matrix = NULL,
  self_ties = FALSE
)

Arguments

`...`	Either multiple objects of class `firm` or a list of such objects
`id_as_firm_name`	Whether to use the ticker as the firm's name. Defaults to `TRUE` if all firms' id is neither `NULL` nor `NA`.
`Matrix`	Whether to use the `Matrix` package. Defaults to `TRUE` when any matrix in the pipeline contains more than 10,000 cells and the package is installed.
`self_ties`	Whether to allow self-ties (a 'loop' in graph theory). Defaults to `FALSE`.

Details

Naive-valued means simply counting the number of common managers.

Value

A matrix object of class financial_matrix(possibly using the Matrix package)

Author(s)

Telarico, Fabio Ashtar

Examples


# Create the naive FF matrix of Berkshire Hathaway's holdings by boards interlocks
data('firms_BKB')
FF <- FF.naive.management(firms_BKB)

# Create the naive FF matrix of Berkshire Hathaway's holdings by boards interlocks
data('firms_BKB')
FF <- FF.naive.management(firms_BKB)

Create a naive-valued firm-firm (FF) matrix for common ownership

Description

Function to create a naive-valued firm-firm (FF) matrix based on common ownership

Usage

FF.naive.ownership(
  ...,
  id_as_firm_name = NULL,
  Matrix = NULL,
  self_ties = FALSE
)
FF.naive.ownership(
  ...,
  id_as_firm_name = NULL,
  Matrix = NULL,
  self_ties = FALSE
)

Arguments

`...`	Either multiple objects of class `firm` or a list of such objects
`id_as_firm_name`	Whether to use the ticker as the firm's name. Defaults to `TRUE` if all firms' id is neither `NULL` nor `NA`.
`Matrix`	Whether to use the `Matrix` package. Defaults to `TRUE` when any matrix in the pipeline contains more than 10,000 cells and the package is installed.
`self_ties`	Whether to allow self-ties (a 'loop' in graph theory). Defaults to `FALSE`.

Details

Naive-valued means simply counting the number of common owners

Value

A matrix object of class financial_matrix(possibly using the Matrix package)

Author(s)

Telarico, Fabio Ashtar

Examples


# Create the naive FF matrix of Berkshire Hathaway's holdings by common ownership
data('firms_BKB')
FF <- FF.naive.ownership(firms_BKB)

# Create the naive FF matrix of Berkshire Hathaway's holdings by common ownership
data('firms_BKB')
FF <- FF.naive.ownership(firms_BKB)

Easily represent a firm-firm (FF) network using the package `network`

Description

Create an object of class network from the package network using a FF matrix of class financial_matrix using all the default aesthetic options

Usage

FF.net(x, aesthetic = c("simple", "nice"))
FF.net(x, aesthetic = c("simple", "nice"))

Arguments

`x`	A matrix-like object produced by `FF` and related functions.
`aesthetic`	Choose a pre-set for the network's look. Either `'simple'` or `'nice'` (see Details).

Details

This function does not allow for any of the additional arguments that can be passed to FF.net.custom.

Value

A network in the desired format

Loops and values

Loops will be allowed if at least one of the matrix's diagonal entries is not zero. The network will be valued if at least one entry of the matrix is neither zero nor one.

Instead, if aesthetic is set to 'simple':

The width of the ties is 1;
The colour of the ties is #b4b4b4 (Philippine Silver);
The size of the nodes is 5;
The colour of the nodes is #081677 (Gentian blue).

Otherwise, if aesthetic is set to 'nice':

The width of the ties is 1;
The colour of the ties is a grey scale reflecting tie strength if the network is valued, otherwise it is #b4b4b4 (Philippine Silver);
The size of the nodes reflects their capitalisation if all firms have data on it and ranges between 1 and 5, otherwise it is 5 for all nodes;
The colour of the nodes reflects their sector if all firms have data on it is taken from a built-in palette, otherwise it is #081677 (Gentian blue).

Author(s)

Telarico, Fabio Ashtar

Examples

# Create a nice network representation of the binary FF of
# Berkshire Hataway's holdings based on common ownership
data("firms_BKB")
x <- FF.naive.ownership(firms_BKB)
FF.net(x = x, aesthetic = 'nice')

# Create a nice network representation of the binary FF of
# Berkshire Hataway's holdings based on common ownership
data("firms_BKB")
x <- FF.naive.ownership(firms_BKB)
FF.net(x = x, aesthetic = 'nice')

Represent a firm-firm (FF) network using the package `network`

Description

Create an object of class network from the package network using a FF matrix of class financial_matrix

Usage

FF.net.custom(
  x,
  vertex.size = NULL,
  vertex.colour = NULL,
  edge.width = NULL,
  edge.greyscale = NULL,
  directed = TRUE,
  loops = FALSE,
  weighted = any(x@M %in% c(0, 1)),
  ...
)
FF.net.custom(
  x,
  vertex.size = NULL,
  vertex.colour = NULL,
  edge.width = NULL,
  edge.greyscale = NULL,
  directed = TRUE,
  loops = FALSE,
  weighted = any(x@M %in% c(0, 1)),
  ...
)

Arguments

`x`	A matrix-like object produced by `FF` and related functions
`vertex.size`	Which piece of information on the firms should be used to represent the nodes' size (see Details).
`vertex.colour`	Which piece of information on the firms should be used to represent the nodes' colours (see Details).
`edge.width`	Whether to use the edges' width to represent tie strength. Defaults to `FALSE`.
`edge.greyscale`	Whether to use the edges' colour to represent tie strength through a grey scale. Defaults to `TRUE` if the matrix is valued.
`directed`	Whether the network should be directed. Defaults to `TRUE`
`loops`	Whether the network should have loops. Defaults to `FALSE`
`weighted`	Whether the ties/edges should be weighted. Defaults to `TRUE` if any element of the matrix equals neither 0 nor 1
`...`	Aliases to the other parameters and additional settings (see Details).

Details

This function allows for a number of additional arguments.

Value

A network in the desired format

What can be passed to `vertex.colour` and `vertex.size`

The pieces of information that is possible to pass to vertex.size and vertex.colour are:

capitalisation, will be arranged into steps (see capitalisation.bins below)
revenue, will be arranged into steps (see revenues.bins below)
legal_form
sector
currency

What can be passed to `edge.width` and `edge.greyscale`

The pieces of information that is possible to pass to edge.width and edge.greyscale are:

capitalisation
revenue

Additional parameters related to `vertex.size`

The effect of the additional parameters that modify the behaviour of vertex.size are:

vertex.size.max (defaults to 5):

if vertex.size or one of its aliases is specified, this is the size of the biggest vertex;
if neither vertex.size nor any of its aliases is given, this is the size of ALL vertices.

vertex.size.min (defaults to 1):

if vertex.size or one of its aliases is specified, this is the size of the smallest vertex;
if neither vertex.size nor any of its aliases is given, it is ignored.

Additional parameters related to `vertex.colour`

#00204D, Oxford Blue
#31446B, Police Blue
#666970, Dim Gray
#958F78, Artichoke
#CBBA69, Dark Khaki
#FFEA46, Gargoyle Gas

If the argument is FALSE, NULL or NA, the vertex will be coloured of #081677 (Gentian blue).

Additional parameters related to `edge.width`

edge.width.max (defaults to 5):

if edge.width or one of its aliases is specified, this is the thickness of the thickest edge;
if neither edge.width nor any of its aliases is given, this is the thickness of ALL edges

edge.width.min (defaults to 1):

if edge.width or one of its aliases is specified, this is the thickness of the slimmest edge;
if neither edge.width nor any of its aliases is given, it is ignored.

Additional parameters related to `edge.greyscale`

edge.greyscale.darkest (defaults to 5) :

if edge.greyscale or one of its aliases is specified, this is the thickness of the thickest edge;
if neither edge.greyscale nor any of its aliases is given, this is the thickness of ALL edges

edge.greyscale.fairest (defaults to 1):

if edge.greyscale or one of its aliases is specified, this is the thickness of the slimmest edge;
if neither edge.greyscale nor any of its aliases is given, it is ignored.

Several aliases are accepted for all arguments, except M:

for vertex.size: node.size
for vertex.colour: vertex.color, node.colour, and node.color;
for edge.width: tie.width
for edge.greyscale: tie.grayscale, tie.greyscale, and edge.grayscale

Author(s)

Telarico, Fabio Ashtar

Examples

# Create the network representation of the binary FF of
# Berkshire Hataway's holdings based on common ownership
data("firms_BKB")
x <- FF.naive.ownership(firms_BKB)
FF.net.custom(x = x, node.size = 3)

# Create the network representation of the binary FF of
# Berkshire Hataway's holdings based on common ownership
data("firms_BKB")
x <- FF.naive.ownership(firms_BKB)
FF.net.custom(x = x, node.size = 3)

Create a complete normalised-valued firm-firm (FF) matrix

Description

Function to create a normalised-valued firm-firm (FF) matrix based on both common ownership and board interlocks

Usage

FF.norm.both(
  ...,
  id_as_firm_name = NULL,
  Matrix = NULL,
  self_ties = FALSE,
  combining = "sum"
)
FF.norm.both(
  ...,
  id_as_firm_name = NULL,
  Matrix = NULL,
  self_ties = FALSE,
  combining = "sum"
)

Arguments

`...`	Either multiple objects of class `firm` or a list of such objects
`id_as_firm_name`	Whether to use the ticker as the firm's name. Defaults to `TRUE` if all firms' id is neither `NULL` nor `NA`.
`Matrix`	Whether to use the `Matrix` package. Defaults to `TRUE` when any matrix in the pipeline contains more than 10,000 cells and the package is installed.
`self_ties`	Whether to allow self-ties (a 'loop' in graph theory). Defaults to `FALSE`.
`combining`	How to combine the FF matrix for managers and that for owners. Possible values: `sum`; `mean` or `average`; `min`; `max`;

Details

The ties' value will reflect the count of common owners and membership depending on combining: -sum: sum of the shares (normalised on 2); -mean or average: average of the shares (normalised on 1); -min: minimum of the shares (normalised on 1); -max: maximum of the shares (normalised on 1).

Value

A matrix object of class financial_matrix(possibly using the Matrix package)

Author(s)

Telarico, Fabio Ashtar

Examples


# Create the complete normalised firm-firm matrix for the companies held by Berkshire Hathaway
data('firms_BKB')
FF <- FF.norm.both(firms_BKB)


# Create the complete normalised firm-firm matrix for the companies held by Berkshire Hathaway
data('firms_BKB')
FF <- FF.norm.both(firms_BKB)

Create a normalised-valued firm-firm (FF) matrix for boards interlocks

Description

Function to create a normalised-valued firm-firm (FF) matrix based on boards interlocks

Usage

FF.norm.management(
  ...,
  id_as_firm_name = NULL,
  Matrix = NULL,
  self_ties = FALSE
)
FF.norm.management(
  ...,
  id_as_firm_name = NULL,
  Matrix = NULL,
  self_ties = FALSE
)

Arguments

`...`	Either multiple objects of class `firm` or a list of such objects
`id_as_firm_name`	Whether to use the ticker as the firm's name. Defaults to `TRUE` if all firms' id is neither `NULL` nor `NA`.
`Matrix`	Whether to use the `Matrix` package. Defaults to `TRUE` when any matrix in the pipeline contains more than 10,000 cells and the package is installed.
`self_ties`	Whether to allow self-ties (a 'loop' in graph theory). Defaults to `FALSE`.

Details

Normalised-valued means that weights represent the share of common managers.

Value

A matrix object of class financial_matrix(possibly using the Matrix package)

Author(s)

Telarico, Fabio Ashtar

Examples


# Create the normalised FF matrix of Berkshire Hathaway's holdings by boards interlocks
data('firms_BKB')
FF <- FF.norm.management(firms_BKB)

# Create the normalised FF matrix of Berkshire Hathaway's holdings by boards interlocks
data('firms_BKB')
FF <- FF.norm.management(firms_BKB)

Create a normalised-valued firm-firm (FF) matrix for common ownership

Description

Function to create a normalised-valued firm-firm (FF) matrix based on common ownership

Usage

FF.norm.ownership(
  ...,
  id_as_firm_name = NULL,
  Matrix = NULL,
  self_ties = FALSE
)
FF.norm.ownership(
  ...,
  id_as_firm_name = NULL,
  Matrix = NULL,
  self_ties = FALSE
)

Arguments

`...`	Either multiple objects of class `firm` or a list of such objects
`id_as_firm_name`	Whether to use the ticker as the firm's name. Defaults to `TRUE` if all firms' id is neither `NULL` nor `NA`.
`Matrix`	Whether to use the `Matrix` package. Defaults to `TRUE` when any matrix in the pipeline contains more than 10,000 cells and the package is installed.
`self_ties`	Whether to allow self-ties (a 'loop' in graph theory). Defaults to `FALSE`.

Details

Normalised-valued means that weights represent the share of common managers.

Value

A matrix object of class financial_matrix(possibly using the Matrix package)

Author(s)

Telarico, Fabio Ashtar

Examples


# Create the normalised FF matrix of Berkshire Hathaway's holdings by common ownership
data('firms_BKB')
FF <- FF.norm.ownership(firms_BKB)

# Create the normalised FF matrix of Berkshire Hathaway's holdings by common ownership
data('firms_BKB')
FF <- FF.norm.ownership(firms_BKB)

Calculate the Fiedler value (algebraic connectivity)

Description

This function expresses the algebraic connectivity of a Firm-Firm network as its Fiedler value. The Fiedler value, named after Miroslav Fiedler, who explored its significance, summarises the connectivity and robustness of a network. Mathematically, it is the second smallest eigenvalue of the network's Laplacian matrix

Usage

fiedler(..., ignore.weights = FALSE, generalise = NULL)
fiedler(..., ignore.weights = FALSE, generalise = NULL)

Arguments

...

Firm-Firm network in one of the following classes:

financial_matrix produced by FF and family;
network_financial or network if the relevant package is installed;
igraph_financial or igraph if the relevant package is installed.

ignore.weights

Optional parameter, defaults to FALSE. If TRUE, ignore ties weights in the computation.

generalise

See Details for more information. Defaults to NULL.

Details

The Fiedler value is specifically defined for undirected graphs. For directed or asymmetrical networks like the Firm-Firm ones, the Laplacian is not necessarily symmetric, and its eigenvalues can be complex. In practical applications, this is more likely to happen in naively valued networks, due to the presence of large off-diagonal values. But it can happen also under other circumstances.

There are three main workarounds:

1. Symmetrisation - Simply considers the underlying undirected graph. This involves ignoring the direction of edges and calculating the Laplacian matrix and its eigenvalues as if the graph were undirected.

2. The generalised Laplacian calculated as the sum of the diagonal matrices for in-degree and out-degree $\left([D]_{in}+[D]_{out}\right)/2$

3. The Hermitian part of the Laplacian - Uses the Hermitian part of the Laplacian matrix of the directed network $\left([M]+{[M]^\text{C}}^\top)\right)/2$ , where the second addendum is the conjugate transpose of the adjacency matrix.

Practically, the third method is excessive here, as the values of the ties cannot be complex numbers. Indeed, the Hermitian is actually the Laplacian of the underlying symmetric network with the value of the ties being split equally in both directions because the conjugate of a real number is that number. Moreover, symmetrising before calculating the Laplacian or generalising the matrix $[L]$ returns the same result. So, the parameter generalise is logical and takes the following values:

TRUE for the generalised Laplacian;
FALSE for the possibly complex (and uninterpretable) eigenvalue of the as-is Laplacian.
NULL will take the generalised Laplacian only if necessary.

Value

A numeric, the Fiedler value.

Author(s)

Telarico, Fabio Ashtar

References

Fiedler, Miroslav. ‘Laplacian of Graphs and Algebraic Connectivity’. Banach Center Publications 25, no. 1 (1989): 57–70. https://eudml.org/doc/267812.

Guo, Krystal, and Bojan Mohar. ‘Hermitian Adjacency Matrix of Digraphs and Mixed Graphs’. Journal of Graph Theory 85, no. 1 (May 2017): 217–48. doi:10.1002/jgt.22057.

Examples

# Load some data
data('firms_BKB')
# Create a FF matrix
mat <- FF(firms_BKB, who = 'b', ties =  'n')
fiedler(mat)

# Create a FF network
if(!require('network')){
  net <- FF.net(mat, 'simple')
  fiedler(net)==fiedler(mat)
}

# Create a FF graph
if(!require('igraph')){
  g <- FF.graph(mat, 'simple')
  fiedler(g)==fiedler(mat)
}

# Load some data
data('firms_BKB')
# Create a FF matrix
mat <- FF(firms_BKB, who = 'b', ties =  'n')
fiedler(mat)

# Create a FF network
if(!require('network')){
  net <- FF.net(mat, 'simple')
  fiedler(net)==fiedler(mat)
}

# Create a FF graph
if(!require('igraph')){
  g <- FF.graph(mat, 'simple')
  fiedler(g)==fiedler(mat)
}

Function to create a `firm` (legal person) using data from 'Yahoo! Finance'

Description

Tickers can be retrieved from [Yahoo! Finance](https://finance.yahoo.com/lookup/). This function requires the package yahoofinancer to be installed. It is available from the CRAN by running install.packages('yahoofinancer').

Usage

find.firm(
  ticker,
  name = NULL,
  ticker_is_id = TRUE,
  legal_form = NULL,
  sector_granularity = 1,
  managers_remove_salutation_title = TRUE,
  managers_only_surname = FALSE
)
find.firm(
  ticker,
  name = NULL,
  ticker_is_id = TRUE,
  legal_form = NULL,
  sector_granularity = 1,
  managers_remove_salutation_title = TRUE,
  managers_only_surname = FALSE
)

Arguments

`ticker`	Firm's ticker.
`name`	Provide the firm's name. If not provided, `NA`, or `NULL`, will default to the string provided as `ticker`.
`ticker_is_id`	Should the ticker be used as the firm's id?
`legal_form`	The firm's legal form of the firm. Possible values: - a string (e.g., 'LLC', 'Private', 'GmbH', etc.); - `NULL` (default), in which case the function will set `legal_form` to 'JSC'; or - `NA` to specify no legal form.
`sector_granularity`	Sector in which the firm operates. Possible values: - `0`, `NULL`, or `NA` to omit the sector; - `1` or `'generic'` (default) for a generic description (e.g., 'Consumer Technology', 'Consumer Cyclical', 'Consumer Defensive'); - `2` or `'specifc'` for a more granular description (e.g., 'Technology', 'Auto Manufacturers', 'Tobacco').
`managers_remove_salutation_title`	Yahoo! Finance provide salutation titles before the names of the managers. If this is `TRUE` (default), they will be omitted.
`managers_only_surname`	Yahoo! Finance provide first, middle, and last name of the managers. If this is `TRUE` (not recommended for large data sets), only the surname is returned.

Value

An object of the S4 class firm containing several fields, only the first one of which is mandatory:

`name`	Name of the firm (or ticker if no name was provided)
`id`	Firm' ticker (if ticker_is_id was 'TRUE') or nothing (otherwise)
`legal_form`	Legal form of the firm (may be null)
`sector`	Sector in which the firm operates (may be null)
`revenues`	Yearly revenues
`capitalisation`	Capitalisation
`management`	Members of the board
`ownership`	Owner(s)
`shares`	Share owned by (each of) the owner(s)
`currency`	Currency

Author(s)

Telarico, Fabio Ashtar

Examples

# Registering Apple automatically
#| Results are subject to the correct functioning of the package `yahoofinancer`
#| and of the Yahoo! Finance API

# Registering Apple automatically
#| Results are subject to the correct functioning of the package `yahoofinancer`
#| and of the Yahoo! Finance API

Function to create mutiple `firms` (legal persons) using data from 'Yahoo! Finance'

Description

If legal_form is a vector containing: - one or more NULL elements, the corresponding firm's legal form will be JSC; - one or more NAs, the corresponding firm's legal form will be NA.

Usage

find.firms(
  tickers,
  name = NULL,
  ticker_is_id = TRUE,
  legal_form = NULL,
  sector_granularity = 1,
  managers_remove_salutation_title = TRUE,
  managers_only_surname = FALSE
)
find.firms(
  tickers,
  name = NULL,
  ticker_is_id = TRUE,
  legal_form = NULL,
  sector_granularity = 1,
  managers_remove_salutation_title = TRUE,
  managers_only_surname = FALSE
)

Arguments

`tickers`	The firms' ticker.
`name`	Provide the firms' names as a vector of the same length as tickers. If not provided, `NA`, or `NULL`, will default to the firm's `ticker`.
`ticker_is_id`	Should the ticker be used as the firm's id?
`legal_form`	The firm's legal form of the firm. Possible values: - a vector of strings (e.g., 'LLC', 'Private', 'GmbH', etc.) of the same length as `tickers` (see 'Details' for the interpretation of `NA`s and `NULL`s); - `NULL` (default), in which case the function will set `legal_form` to 'JSC' for all firms; or - `NA` to specify no legal form.
`sector_granularity`	Sector in which the firm operates. Possible values: - `0`, `NULL`, or `NA` to omit the sector; - `1` or `'generic'` (default) for a generic description (e.g., 'Consumer Technology', 'Consumer Cyclical', 'Consumer Defensive'); - `2` or `'specifc'` for a more granular description (e.g., 'Technology', 'Auto Manufacturers', 'Tobacco').
`managers_remove_salutation_title`	Yahoo! Finance provide salutation titles before the names of the managers. If this is `TRUE` (default), they will be omitted.
`managers_only_surname`	Yahoo! Finance provide first, middle, and last name of the managers. If this is `TRUE` (not recommended for large data sets), only the surname is returned.

Details

To ensure consistency, ticker_is_id, sector_granularity, managers_remove_salutation_title, and managers_only_surname cannot be vectors.

Value

An object of the S4 class firm containing several fields, only the first one of which is mandatory:

`name`	Name of the firm (or ticker if no name was provided)
`id`	Firm' ticker (if ticker_is_id was 'TRUE') or nothing (otherwise)
`legal_form`	Legal form of the firm (may be null)
`sector`	Sector in which the firm operates (may be null)
`revenues`	Yearly revenues
`capitalisation`	Capitalisation
`management`	Members of the board
`ownership`	Owner(s)
`shares`	Share owned by (each of) the owner(s)
`currency`	Currency

Author(s)

Telarico, Fabio Ashtar

Examples

# Registering Apple, General Motors, and British American Tobacco automatically
#| Results are subject to the correct functioning of the package `yahoofinancer`
#| and of the Yahoo! Finance API

# Registering Apple, General Motors, and British American Tobacco automatically
#| Results are subject to the correct functioning of the package `yahoofinancer`
#| and of the Yahoo! Finance API

Extract all the unique people associated to at least one of the provided `firm` objects

Description

Extract all the unique people associated to at least one of the provided firm objects

Usage

find.people(..., who = c("managers", "owners", "both", "all"), sorting = TRUE)
find.people(..., who = c("managers", "owners", "both", "all"), sorting = TRUE)

Arguments

`...`	Either multiple objects of class `firm` or a list of such objects
`who`	Whether to extract the 'managers' or the 'owners' (minimum unambiguous string)
`sorting`	Whether to sort the people by alphabetical order. Defaults to `TRUE`

Value

A vector containing the names of the individuals looked up. If

Author(s)

Telarico, Fabio Ashtar

Examples

# Find all the shareholders in companies that Berkshire Hathaway holds
data('firms_BKB')
shareholders <- find.people(firms_BKB, who = 'own')

# Find all those managing the companies that Berkshire Hathaway holds
data('firms_BKB')
managers <- find.people(firms_BKB, who = 'man')

# Find all the shareholders in companies that Berkshire Hathaway holds
data('firms_BKB')
shareholders <- find.people(firms_BKB, who = 'own')

# Find all those managing the companies that Berkshire Hathaway holds
data('firms_BKB')
managers <- find.people(firms_BKB, who = 'man')

Complete Berkshire Hathaway Portfolio

Description

Data on Apple (AAPL), General Motors (GM), and British American Tobacco (BTI) extracted from Yahoo! Finance (on May 20, 2023) and formatted a firm objects.

Usage

data('firms_BKB')
data('firms_BKB')

Format

Three objects of class firm.

Source

- Divine, John. “The Complete Berkshire Hathaway Portfolio.” FInancial data. U.S. News & World Report, May 17, 2023. <https://money.usnews.com/investing/stock-market-news/articles/the-complete-berkshire-hathaway-portfolio>. - ICE Data Services. “Nasdaq Stock Exchange & Dow Jones Indexes.” Financial data, May 21, 2023, <https://finance.yahoo.com/lookup/>.

Three US firms

Description

Data on Apple (AAPL), General Motors (GM), and British American Tobacco (BTI) extracted from Yahoo! Finance (on May 20, 2023) and formatted a firm objects.

Usage

data('firms_US')
data('firms_US')

Format

Three objects of class firm.

Source

ICE Data Services. “Nasdaq Stock Exchange & Dow Jones Indexes.” Financial data, May 21, 2023, <https://finance.yahoo.com/lookup/>

Function to create a (necessarily binary) firm-manager (FM) matrix

Description

Function to create a (necessarily binary) firm-manager (FM) matrix

Usage

FM(..., id_as_firm_name = NULL, Matrix = NULL)
FM(..., id_as_firm_name = NULL, Matrix = NULL)

Arguments

`...`	Either multiple objects of class `firm` or a list of such objects
`id_as_firm_name`	Whether to use the ticker as the firm's name. Defaults to `TRUE` if all firms' id is neither `NULL` nor `NA`.
`Matrix`	Whether to use the `Matrix` package. Defaults to `TRUE` when there are more than 10,000 combinations and the package is installed.

Value

A matrix object of class financial_matrix (possibly using the Matrix package) in which:

the rows: Represent firms;
the columns: Represent managers (usually physical persons).

Author(s)

Telarico, Fabio Ashtar

Examples


# Create the FM matrix of Berkshire Hathaway's holdings

data('firms_BKB')
  FM <- FM(firms_BKB)


# Create the FM matrix of Berkshire Hathaway's holdings

data('firms_BKB')
  FM <- FM(firms_BKB)

Function to create a binary firm-owner (FO) matrix

Description

Function to create a binary firm-owner (FO) matrix

Usage

FO.binary(..., id_as_firm_name = NULL, Matrix = NULL)
FO.binary(..., id_as_firm_name = NULL, Matrix = NULL)

Arguments

`...`	Either multiple objects of class `firm` or a list of such objects
`id_as_firm_name`	Whether to use the ticker as the firm's name. Defaults to `TRUE` if all firms' id is neither `NULL` nor `NA`.
`Matrix`	Whether to use the `Matrix` package. Defaults to `TRUE` when there are more than 10,000 combinations and the package is installed.

Value

A matrix object of class financial_matrix (possibly using the Matrix package) in which:

the rows: Represent firms;
the columns: Represent owners (physical and legal persons).

Author(s)

Telarico, Fabio Ashtar

Examples


# Create the binary FO matrix of Berkshire Hathaway's holdings

data('firms_BKB')
FO <- FO.binary(firms_BKB)


# Create the binary FO matrix of Berkshire Hathaway's holdings

data('firms_BKB')
FO <- FO.binary(firms_BKB)

Function to create a naive-valued firm-owner (FO) matrix

Description

The values are simply the value of the owner $j$ 's stake in firm $i$ .

Usage

FO.naive(..., id_as_firm_name = NULL, Matrix = NULL)
FO.naive(..., id_as_firm_name = NULL, Matrix = NULL)

Arguments

`...`	Either multiple objects of class `firm` or a list of such objects
`id_as_firm_name`	Whether to use the ticker as the firm's name. Defaults to `TRUE` if all firms' id is neither `NULL` nor `NA`.
`Matrix`	Whether to use the `Matrix` package. Defaults to `TRUE` when there are more than 10,000 combinations and the package is installed.

Value

A matrix object of class financial_matrix (possibly using the Matrix package) in which:

the rows: Represent firms;
the columns: Represent owners (physical and legal persons).

Author(s)

Telarico, Fabio Ashtar

Examples


# Create the naive FO matrix of Berkshire Hathaway's holdings

data('firms_BKB')
FO <- FO.naive(firms_BKB)


# Create the naive FO matrix of Berkshire Hathaway's holdings

data('firms_BKB')
FO <- FO.naive(firms_BKB)

Function to create a naive-valued firm-owner (FO) matrix

Description

The values represent the share of firm $i$ 's capital owned by $j$ .

Usage

FO.norm(..., id_as_firm_name = NULL, Matrix = NULL)
FO.norm(..., id_as_firm_name = NULL, Matrix = NULL)

Arguments

`...`	Either multiple objects of class `firm` or a list of such objects
`id_as_firm_name`	Whether to use the ticker as the firm's name. Defaults to `TRUE` if all firms' id is neither `NULL` nor `NA`.
`Matrix`	Whether to use the `Matrix` package. Defaults to `TRUE` when there are more than 10,000 combinations and the package is installed.

Value

A matrix object of class financial_matrix (possibly using the Matrix package) in which:

the rows: Represent firms;
the columns: Represent owners (physical and legal persons).

Author(s)

Telarico, Fabio Ashtar

Examples


# Create the normalised FO matrix of Berkshire Hathaway's holdings

data('firms_BKB')
FO <- FO.norm(firms_BKB)


# Create the normalised FO matrix of Berkshire Hathaway's holdings

data('firms_BKB')
FO <- FO.norm(firms_BKB)

Extending `igraph` functions to `igraph_financial` objects

Description

The following functions are implemented:

V to retrieve the vertexes (igraph::V);
vcount to count the vertexes (igraph::vcount);
gorder as an alias to vcount_fin (igraph::gorder);
E to retrieve the edges (igraph::E);
gsize to count the edges (igraph::gsize);
ecount as an alias to gsize_fin (igraph::ecount)
plot_igraph to plot graphs (igraph::plot.igraph))

Usage

V(x)

vcount(x)

gorder(x)

E(x, ...)

ecount(x, ...)

gsize(x, ...)

plot_igraph(x, ...)
V(x)

vcount(x)

gorder(x)

E(x, ...)

ecount(x, ...)

gsize(x, ...)

plot_igraph(x, ...)

Arguments

`x`	The `igraph_financial` object
`...`	Other parameters passed to the corresponding `igraph` functions (see Details).

Details

Implementing most basic iterators from the package igraph for objects of class igraph_financial

Value

The same result for both igraph and igraph_financial objects

V: A vertex sequence containing all vertices, in the order of their numeric vertex ids.
vcount and gorder: Number of vertices, numeric scalar.
E: An edge sequence of the graph
ecount and gsize: Number of edges, numeric scalar.
plot_igraph: Returns NULL, invisibly. Called to print the graph to any R device. (see method and igraph::plot.igraph)

Author(s)

Telarico, Fabio Ashtar

igraph edge iterators for `igraph_financial` objects

Description

Methods to extend igraph edge iterators and functions to igraph_financial objects

Usage

## S4 method for signature 'igraph_financial'
E(x, ...)

## S4 method for signature 'igraph'
E(x, ...)

## S4 method for signature 'igraph_financial'
ecount(x, ...)

## S4 method for signature 'igraph'
ecount(x, ...)

## S4 method for signature 'igraph_financial'
gsize(x, ...)

## S4 method for signature 'igraph'
gsize(x, ...)
## S4 method for signature 'igraph_financial'
E(x, ...)

## S4 method for signature 'igraph'
E(x, ...)

## S4 method for signature 'igraph_financial'
ecount(x, ...)

## S4 method for signature 'igraph'
ecount(x, ...)

## S4 method for signature 'igraph_financial'
gsize(x, ...)

## S4 method for signature 'igraph'
gsize(x, ...)

Arguments

`x`	The `igraph_financial` object
`...`	Other parameters passed to the corresponding method and/or `igraph` functions (see Details).

Value

The same result for both igraph and igraph_financial objects

E: An edge sequence of the graph
ecount and gsize: Number of edges, numeric scalar

Author(s)

Telarico, Fabio Ashtar

An S4 class for relational data extending the package igraph

Description

An S4 class for the network objects produced by the FF.graph and FF.graph.custom to represent the relations between firms (legal person)

Slots

data: The representation of the network as a igraph object

igraph vertex iterators for `igraph_financial` objects

Description

Methods to extend igraph vertex iterators and functions to igraph_financial objects

Usage

## S4 method for signature 'igraph_financial'
V(x)

## S4 method for signature 'igraph'
V(x)

## S4 method for signature 'igraph_financial'
vcount(x)

## S4 method for signature 'igraph'
vcount(x)

## S4 method for signature 'igraph_financial'
gorder(x)

## S4 method for signature 'igraph'
gorder(x)
## S4 method for signature 'igraph_financial'
V(x)

## S4 method for signature 'igraph'
V(x)

## S4 method for signature 'igraph_financial'
vcount(x)

## S4 method for signature 'igraph'
vcount(x)

## S4 method for signature 'igraph_financial'
gorder(x)

## S4 method for signature 'igraph'
gorder(x)

Arguments

`x`	The `igraph_financial` object

Value

The same result for both igraph and igraph_financial objects

V: A vertex sequence containing all vertices, in the order of their numeric vertex ids
vcount and gorder: Number of vertices, numeric scalar

Author(s)

Telarico, Fabio Ashtar

An S4 class for relational data extending the package network

Description

An S4 class for the network objects produced by the FF.net and FF.net.custom functions to represent the relations between firms (legal person)

Slots

data: The representation of the network as a network object

Extending `newtwork` functions to `newtwork_financial` objects

Description

The following functions are implemented:

edgecount to count the number of eges (network::network.edgecount);
vertex.names to retrieve the vertices' names (network::network.vertex.names);
network.size to count the edges (network::network::network.size);
plot_network to plot networks (network::plot.network))

Usage

edgecount(x, ...)

network.size(x, ...)

vertex.names(x, ...)

plot_network(x, ...)
edgecount(x, ...)

network.size(x, ...)

vertex.names(x, ...)

plot_network(x, ...)

Arguments

`x`	The `newtwork_financial` object
`...`	Other parameters passed to the corresponding `newtwork` functions (see Details).

Details

Implementing most basic iterators from the package newtwork for objects of class newtwork_financial

Value

The same result for both newtwork and newtwork_financial objects

edgecount: Number of edges, numeric scalar
vertex.names: Names/Labels of the vertices, character vector
network.size: Number of vertices, numeric scalar
plot_network: Returns a two-column matrix containing the vertex positions as (x,y) coordinates, invisibly. Called to print the graph to any R device.)

Author(s)

Telarico, Fabio Ashtar

Operators for `network_financial` objects

Description

Methods to extend operators from the package network to network_financial objects

Usage

## S4 method for signature 'network_financial'
edgecount(x, ...)

## S4 method for signature 'network'
edgecount(x, ...)

## S4 method for signature 'network_financial'
vertex.names(x, ...)

## S4 method for signature 'network'
vertex.names(x, ...)

## S4 method for signature 'network_financial'
network.size(x, ...)

## S4 method for signature 'network'
network.size(x, ...)
## S4 method for signature 'network_financial'
edgecount(x, ...)

## S4 method for signature 'network'
edgecount(x, ...)

## S4 method for signature 'network_financial'
vertex.names(x, ...)

## S4 method for signature 'network'
vertex.names(x, ...)

## S4 method for signature 'network_financial'
network.size(x, ...)

## S4 method for signature 'network'
network.size(x, ...)

Arguments

`x`	The `network_financial` object
`...`	Other parameters passed to the corresponding method and/or `network` functions (see Details).

Value

The same result for both network and network_financial objects

network.edgecount: Number of edges, numeric scalar
network.vertex.names: Names/Labels of the vertices, character vector
network::network.size: Number of vertices, numeric scalar

Author(s)

Telarico, Fabio Ashtar

Calculate network efficiency

Description

Network efficiency quantifies how efficiently information (management relations) and/or money capital (ownership relations) flow through a network. It is essential in systemic-risk identification, resilience assessment, and crisis-propagation analysis.

Usage

network.efficiency(
  ...,
  ignore.weights = FALSE,
  use.igraph = isTRUE(requireNamespace("igraph", quietly = TRUE))
)
network.efficiency(
  ...,
  ignore.weights = FALSE,
  use.igraph = isTRUE(requireNamespace("igraph", quietly = TRUE))
)

Arguments

...

Firm-Firm network in one of the following classes:

financial_matrix produced by FF and family;
network_financial or network if the relevant package is installed;
igraph_financial or igraph if the relevant package is installed.

ignore.weights

Optional parameter, defaults to FALSE. If TRUE, ignore ties weights in the computation.

use.igraph

Whether to use igraph to speed-up the computation. See 'Details'.

Details

The function is implemented both for igraph users and in base R using the Floyd-Warshall algorithm. However, the latter runs in $O(n^3)$ , which may not be efficient for very large networks.

The distances enter into play in the formal definition of efficiency:

$E = \frac{1}{N(N-1)}\sum_{i\ne j \in \mathcal{N}}\frac{1}{d_{i,\ j}}$

where:

$\mathcal{N}$ is the set of all nodes;
$N$ is the number of nodes (i.e., the number of elements in $\mathcal{N}$ ;
$d_{i,\ j}$ is the shortest (weighted and directed) path distance between the nodes $i$ and $j$ .

Value

A numeric, the global efficiency value.

Author(s)

Telarico, Fabio Ashtar

References

Latora, Vito, and Masimo Marchiori. 'Economic Small-World Behavior in Weighted Networks'. The European Physical Journal B - Condensed Matter and Complex Systems 32, no. 2 (1 March 2003): 249–63. doi:10.1140/epjb/e2003-00095-5.

Floyd, Robert W. 'Algorithm 97: Shortest path'. Communications of the ACM, 5, no. 6 (1962): 345.

Examples

# Load some data
data('firms_BKB')

# Create a FF matrix
mat <- FF(firms_BKB, who = 'b', ties =  'n')
# Use the built-in Floyd-Warshall algorithm
network.efficiency(mat, use.igraph = FALSE)

#' # Create a FF graph
if(!require('igraph')){
  g <- FF.graph(mat, 'simple')
  # Use igraph's implementation, which gives the same result
  # as the built-in Floyd-Warshall algorithm, but is faster
  network.efficiency(g, use.igraph = TRUE)==network.efficiency(mat, use.igraph = FALSE)
}

# Load some data
data('firms_BKB')

# Create a FF matrix
mat <- FF(firms_BKB, who = 'b', ties =  'n')
# Use the built-in Floyd-Warshall algorithm
network.efficiency(mat, use.igraph = FALSE)

#' # Create a FF graph
if(!require('igraph')){
  g <- FF.graph(mat, 'simple')
  # Use igraph's implementation, which gives the same result
  # as the built-in Floyd-Warshall algorithm, but is faster
  network.efficiency(g, use.igraph = TRUE)==network.efficiency(mat, use.igraph = FALSE)
}

igraph plotting for `igraph_financial` objects

Description

Methods to extend igraph's plotting functions to igraph_financial objects

Usage

## S4 method for signature 'igraph_financial'
plot_igraph(x, ...)

## S4 method for signature 'igraph'
plot_igraph(x, ...)
## S4 method for signature 'igraph_financial'
plot_igraph(x, ...)

## S4 method for signature 'igraph'
plot_igraph(x, ...)

Arguments

`x`	The `igraph_financial` object
`...`	Other parameters passed to the corresponding method and/or `igraph` functions (see Details).

Value

For both igraph and igraph_financial objects, returns NULL invisibly. It is called to print the graph to any R device. (see method and igraph::plot.igraph)

Author(s)

Telarico, Fabio Ashtar

network plotting for `igraph_financial` objects

Description

Methods to extend network's plotting functions to network_financial objects

Usage

## S4 method for signature 'network_financial'
plot_network(x, ...)

## S4 method for signature 'network'
plot_network(x, ...)
## S4 method for signature 'network_financial'
plot_network(x, ...)

## S4 method for signature 'network'
plot_network(x, ...)

Arguments

`x`	The `network_financial` object
`...`	Other parameters passed to the corresponding method and/or `network` functions (see Details).

Value

For both igraph and igraph_financial objects, returns NULL invisibly. It is called to print the graph to any R device. (see method and igraph::plot.igraph)

Author(s)

Telarico, Fabio Ashtar

Print information on a class `firm` object

Description

Print method for the S4 class representing a firm (legal person)

Usage

## S4 method for signature 'firm'
print(x)
## S4 method for signature 'firm'
print(x)

Arguments

`x`	The `firm` object to show

Value

No return value, called to print to the console detail information about the firm object including:

in the first paragraph:
- legal form (if any),
- revenues (if known),
- capitalisation (if known).
in the second paragraph, the names of the board members/managers;
in the third paragraph, a data frame with two columns:
- First, the names of the owners
- The, their respective share of the firm's capital (normalised to 1)

Author(s)

Telarico, Fabio Ashtar

Function to extract information from a `firm` object (legal person)

Description

Function to extract information from a firm object (legal person)

Usage

query.firm(firm, which, naming = TRUE)
query.firm(firm, which, naming = TRUE)

Arguments

`firm`	Firm which to extract information from
`which`	Information to extract, minimum unambiguous substring. Possible values (one or more): - `name` Name of the firm - `id` ID of the firm, usually the ticker (if provided or otherwise known) - `legal_form` Legal form of the firm - `sector` Sector in which the firm operates - `revenues` Yearly revenues - `capitalisation` Capitalisation - `management` Members of the board - `ownership` Owner(s) - `shares` Share owned by (each of) the owner(s) - `currency` Currency in which revenues and capitalisation are denominated
`naming`	Whether to name the result after the querie information (defaults to `TRUE`)

Value

Depends on the information queried. One (or, if length(which)>=2, a list of two or more) of the following:

`name`	A string representing the name of the firm
`id`	A string representing the ID of the firm (usually its ticker)
`legal_form`	A string representing the firm's legal form
`sector`	A string indicating the sector in which the firm operates (possibly a NACE rev. 2 code)
`revenues`	A numeric (double) quantifying yearly revenues
`capitalisation`	A numeric (double) quantifying capitalisation
`management`	A vector of strings representing the members of the board
`ownership`	A vector of strings representing the owner(s)
`shares`	A numeric (double) vector indicating the shares controlled by (each of) the owner(s)
`currency`	A string indicating the currency in which revenues and capitalisation are denominated

Author(s)

Telarico, Fabio Ashtar

Examples


# Query Apple's capitalisation
data('firms_US')
list2env(firms_US, parent.frame())
query.firm(AAPL, which = 'capitalisation')

# Query British-American Tobacco's capitalisation using the common abbreviation 'cap'
data('firms_US')
list2env(firms_US, parent.frame())
query.firm(BTI, 'cap')

# Query General Motors's owners and their shares, but return an unnamed \code{\link{list}}
data('firms_US')
list2env(firms_US, parent.frame())
query.firm(GM, c('own', 'sha'), naming = FALSE)


# Query Apple's capitalisation
data('firms_US')
list2env(firms_US, parent.frame())
query.firm(AAPL, which = 'capitalisation')

# Query British-American Tobacco's capitalisation using the common abbreviation 'cap'
data('firms_US')
list2env(firms_US, parent.frame())
query.firm(BTI, 'cap')

# Query General Motors's owners and their shares, but return an unnamed \code{\link{list}}
data('firms_US')
list2env(firms_US, parent.frame())
query.firm(GM, c('own', 'sha'), naming = FALSE)

Function to extract information from multiple `firm` object (legal person)

Description

This function can be fed either: - a (possibly named) list of objects of class firm (see examples 1 and 2); or - multiple objects of class firm(see example 3)

Usage

query.firms(..., which, naming = TRUE)
query.firms(..., which, naming = TRUE)

Arguments

`...`	Object/s which to extract information from (see 'Details')
`which`	Information to extract, minimum unambiguous sub-string. Possible values (one or more): - `name` Name of the firm - `id` ID of the firm, usually the ticker (if provided or otherwise known) - `legal_form` Legal form of the firm - `sector` Sector in which the firm operates - `revenues` Yearly revenues - `capitalisation` Capitalisation - `management` Members of the board - `ownership` Owner(s) - `shares` Share owned by (each of) the owner(s) - `currency` Currency in which revenues and capitalisation are denominated
`naming`	Whether to name the result after the querie information (defaults to `TRUE`)

Value

Depends on the information queried. An object of class list (that, if length(which)>=2, contain multiple sub-lists) of the following:

`name`	A string representing the name of the firm
`id`	A string representing the ID of the firm (usually its ticker)
`legal_form`	A string representing the firm's legal form
`sector`	A string indicating the sector in which the firm operates (possibly a NACE rev. 2 code)
`revenues`	A numeric (double) quantifying yearly revenues
`capitalisation`	A numeric (double) quantifying capitalisation
`management`	A vector of strings representing the members of the board
`ownership`	A vector of strings representing the owner(s)
`shares`	A numeric (double) vector indicating the shares controlled by (each of) the owner(s)
`currency`	A string indicating the currency in which revenues and capitalisation are denominated

Author(s)

Telarico, Fabio Ashtar

Examples


# Query Apple's, GM's, and BTI's market cap and revenues
data('firms_US')
query.firms(firms_US, which = c('cap', 'rev'))

# Query GM's and BTI's management
data('firms_US')
query.firms(firms_US, which = 'man')

# Query Appple's and GM's revenues and currency
data('firms_US')
list2env(firms_US, envir = parent.frame())
query.firms(AAPL, GM, which = c('rev', 'curr'))


# Query Apple's, GM's, and BTI's market cap and revenues
data('firms_US')
query.firms(firms_US, which = c('cap', 'rev'))

# Query GM's and BTI's management
data('firms_US')
query.firms(firms_US, which = 'man')

# Query Appple's and GM's revenues and currency
data('firms_US')
list2env(firms_US, envir = parent.frame())
query.firms(AAPL, GM, which = c('rev', 'curr'))

Function to extract information from multiple `firm` object (legal person) as a data frame

Description

This function can be fed either: - a (possibly named) list of objects of class firm (see example 1); or

Usage

query.firms.dataframe(..., which, naming = TRUE, transposing = TRUE)
query.firms.dataframe(..., which, naming = TRUE, transposing = TRUE)

Arguments

`...`	Object/s which to extract information from (see 'Details')
`which`	Information to extract, minimum unambiguous sub-string. Possible values (one or more): - `name` Name of the firm - `id` ID of the firm, usually the ticker (if provided or otherwise known) - `legal_form` Legal form of the firm - `sector` Sector in which the firm operates - `revenues` Yearly revenues - `capitalisation` Capitalisation - `management` Members of the board - `ownership` Owner(s) - `shares` Share owned by (each of) the owner(s) - `currency` Currency in which revenues and capitalisation are denominated
`naming`	Whether to name the result after the queried information (defaults to `TRUE`)
`transposing`	If `TRUE` (default) each row will correspond to a firm and each column to a variable.

Details

It is not recommended to use this function with management, ownership, or shares unless transposing == FALSE.

Value

A data frame in structured as follows (or vice versa if transposing == TRUE):

a row: for each queried information; and
a column: for each number of firm

Author(s)

Telarico, Fabio Ashtar

Examples


# Query Apple's, GM's, and BTI's market cap and revenues
data('firms_US')
query.firms.dataframe(firms_US, which = c('cap', 'rev'))

# Query GM's and BTI's market cap and revenues
data('firms_US')
list2env(firms_US, envir = parent.frame())
query.firms.dataframe(GM, BTI, which = c('cap', 'rev'))


# Query Apple's, GM's, and BTI's market cap and revenues
data('firms_US')
query.firms.dataframe(firms_US, which = c('cap', 'rev'))

# Query GM's and BTI's market cap and revenues
data('firms_US')
list2env(firms_US, envir = parent.frame())
query.firms.dataframe(GM, BTI, which = c('cap', 'rev'))

Function to create a `firm` (legal person)

Description

Function to create a firm (legal person)

Usage

register.firm(
  name,
  id = NA,
  legal_form = NA,
  sector = NA,
  sector_classif = NULL,
  revenues = NA,
  capitalisation = NA,
  management = NA,
  ownership = NA,
  shares = NA,
  currency = NA
)
register.firm(
  name,
  id = NA,
  legal_form = NA,
  sector = NA,
  sector_classif = NULL,
  revenues = NA,
  capitalisation = NA,
  management = NA,
  ownership = NA,
  shares = NA,
  currency = NA
)

Arguments

`name`	Name of the firm
`id`	Provide an ID code for the firm. Defaults to `NA`
`legal_form`	Legal form of the firm (e.g., LLP, Inc, GmbH, Private, etc.)
`sector`	Sector in which the firm operates (its values depend on the value of `sector_classif`)
`sector_classif`	Which standard sector classification (if any) to be used. Possible values are - `NACE` for the Statistical Classification of Economic Activities in the European Community or 'Nomenclature statistique des Activités économiques dans la Communauté Européenne', revision 2; - `NA` for a custom classification (default if anything is provided); - `NULL` for no classification (default if nothing is provided).
`revenues`	Yearly revenues
`capitalisation`	Firm's capitalisation
`management`	Names of the members of the board
`ownership`	Names of the owner(s)
`shares`	Share owned by (each of) the owner(s)
`currency`	Currency in which the capitalisation and revenues are expressed (defaults to 'USD')

Value

An object of the S4 class firm containing several fields, only the first one of which is mandatory:

`name`	Name of the firm
`id`	ID of the firm, usually the ticker
`legal_form`	Legal form of the firm
`sector`	Sector in which the firm operates
`revenues`	Yearly revenues
`capitalisation`	Capitalisation
`management`	Members of the board
`ownership`	Owner(s)
`shares`	Share owned by (each of) the owner(s)
`currency`	Currency

Author(s)

Telarico, Fabio Ashtar

Examples


# Registering Apple manually
AAPL <- register.firm(name = 'Apple', id = 'AAPL', legal_form = 'GmbH',
                      revenues = 81665400000, capitalisation = 2755039000000,
                      management = my_vector <- c("Timothy D. Cook",
                                                  "Luca Maestri",
                                                  "Jeffrey E. Williams",
                                                  "Katherine L. Adams",
                                                  "Deirdre O'Brien",
                                                  "Chris Kondo",
                                                  "James Wilson",
                                                  "Mary Demby",
                                                  "Nancy Paxton",
                                                  "Greg Joswiak"),
                      ownership = c('Vanguard Total Stock Market Index Fund',
                      'Vanguard 500 Index Fund',
                      'Fidelity 500 Index Fund',
                      'SPDR S&P 500 ETF Trust',
                      'iShares Core S&P 500 ETF',
                      'Invesco ETF Tr-Invesco QQQ Tr, Series 1 ETF',
                      'Vanguard Growth Index Fund',
                      'Vanguard Institutional Index Fund-Institutional Index Fund',
                      'Vanguard Information Technology Index Fund',
                      'Select Sector SPDR Fund-Technology'),
                      shares = c(0.0290, 0.0218, 0.0104, 0.0102, 0.0084,
                                 0.0082, 0.0081, 0.0066, 0.0043, 0.0039),
                      currency = 'USD')

# Registering a coal-mining company indicating the sector using `NACE` codes, without ID
set.seed(123456789)
firm_coalmining <- register.firm(
  name = 'A coal-mining firm',
  legal_form = 'Private',
  sector = 'B.05',
  sector_classif = 'NACE'
)

# Getting creative: Register a firm with coded owners and managers
set.seed(123456789)
firm_coded <- register.firm(
  name = 'Coded firm',
  revenues = sample(seq(1:100)/10, 1)*10^sample(1:5, 1),
  capitalisation = sample(seq(1:100)/10, 1)*10^sample(2:7, 1),
  management = c('Board Member', 'CEO', 'CTO', 'Activist investor'),
  ownership = c('State', 'Foreign investors'),
  shares = c(51, 49),
  currency = 'EUR'
)

# Registering Apple manually
AAPL <- register.firm(name = 'Apple', id = 'AAPL', legal_form = 'GmbH',
                      revenues = 81665400000, capitalisation = 2755039000000,
                      management = my_vector <- c("Timothy D. Cook",
                                                  "Luca Maestri",
                                                  "Jeffrey E. Williams",
                                                  "Katherine L. Adams",
                                                  "Deirdre O'Brien",
                                                  "Chris Kondo",
                                                  "James Wilson",
                                                  "Mary Demby",
                                                  "Nancy Paxton",
                                                  "Greg Joswiak"),
                      ownership = c('Vanguard Total Stock Market Index Fund',
                      'Vanguard 500 Index Fund',
                      'Fidelity 500 Index Fund',
                      'SPDR S&P 500 ETF Trust',
                      'iShares Core S&P 500 ETF',
                      'Invesco ETF Tr-Invesco QQQ Tr, Series 1 ETF',
                      'Vanguard Growth Index Fund',
                      'Vanguard Institutional Index Fund-Institutional Index Fund',
                      'Vanguard Information Technology Index Fund',
                      'Select Sector SPDR Fund-Technology'),
                      shares = c(0.0290, 0.0218, 0.0104, 0.0102, 0.0084,
                                 0.0082, 0.0081, 0.0066, 0.0043, 0.0039),
                      currency = 'USD')

# Registering a coal-mining company indicating the sector using `NACE` codes, without ID
set.seed(123456789)
firm_coalmining <- register.firm(
  name = 'A coal-mining firm',
  legal_form = 'Private',
  sector = 'B.05',
  sector_classif = 'NACE'
)

# Getting creative: Register a firm with coded owners and managers
set.seed(123456789)
firm_coded <- register.firm(
  name = 'Coded firm',
  revenues = sample(seq(1:100)/10, 1)*10^sample(1:5, 1),
  capitalisation = sample(seq(1:100)/10, 1)*10^sample(2:7, 1),
  management = c('Board Member', 'CEO', 'CTO', 'Activist investor'),
  ownership = c('State', 'Foreign investors'),
  shares = c(51, 49),
  currency = 'EUR'
)

Package 'FinNet'

Help Index

Coerce into (a list of) firm object(s)

Description

Usage

Arguments

Value

Author(s)

Coerce a financial_matrix object into a list of firm objects

Description

Usage

Arguments

Value

Author(s)

Compute Bonacich centrality on a Firm-Firm network

Description

Usage

Arguments

Value

Author(s)

References

Examples

Perform cascade failure analysis

Description

Usage

Arguments

Value

Author(s)

References

Examples

Create any firm-firm (FF) matrix

Description

Usage

Arguments

Details

Value

Author(s)

See Also

Examples

Basic methods for objects of class financial_matrix

Description

Usage

Arguments

Details

Value

Author(s)

Basic method to check to compare values in a financial_matrix object

Description

Usage

Arguments

Value

Author(s)

Mathematical methods for financial_matrix objects

Description

Usage

Arguments

Details

Value

Author(s)

Number of rows/columns in a financial_matrix object

Description

Usage

Arguments

Details

Value

Author(s)

Method to subset a financial_matrix

Description

Usage

Arguments

Value

Author(s)

Create a complete binary firm-firm (FF) matrix

Description

Usage

Arguments

Details

Value

Author(s)

See Also

Coerce into (a list of) `firm` object(s)

Coerce a `financial_matrix` object into a list of `firm` objects

Basic methods for objects of class `financial_matrix`

Basic method to check to compare values in a `financial_matrix` object

Mathematical methods for `financial_matrix` objects

Number of rows/columns in a `financial_matrix` object

Method to subset a `financial_matrix`

Easily represent a firm-firm (FF) network using the package `igraph`

Represent a firm-firm (FF) network using the package `igraph`

What can be passed to `vertex.colour` and `vertex.size`

What can be passed to `edge.width` and `edge.greyscale`

Additional parameters related to `vertex.size`

Additional parameters related to `vertex.colour`

Additional parameters related to `edge.width`

Additional parameters related to `edge.greyscale`

Easily represent a firm-firm (FF) network using the package `network`