Type:	Package
Title:	Quickly Build and Manipulate Financial Networks
Version:	0.2.1
Maintainer:	Fabio Ashtar Telarico <Fabio-Ashtar.Telarico@fdv.uni-lj.si>
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.
License:	GPL (≥ 3)
URL:	https://fatelarico.github.io/FinNet.html
BugReports:	https://github.com/FATelarico/FinNet/issues
Encoding:	UTF-8
RoxygenNote:	7.3.2
Depends:	R (≥ 2.10)
Author:	Fabio Ashtar Telarico [aut, cre]
Imports:	Matrix, grDevices, methods, Rcpp
Suggests:	knitr, igraph, network, markdown, SPB, yahoofinancer
LazyData:	no
VignetteBuilder:	knitr
LinkingTo:	Rcpp
NeedsCompilation:	yes
Packaged:	2024-10-31 10:36:37 UTC; fabio
Repository:	CRAN
Date/Publication:	2024-10-31 15:30:02 UTC

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').

Author(s)

Telarico, Fabio Ashtar

See Also

Useful links:

• https://fatelarico.github.io/FinNet.html

• Report bugs at https://github.com/FATelarico/FinNet/issues

Function to return an object after assigning new names

Description

Combines magrittr::set_colnames, magrittr::set_rownames, magrittr::set_names

Usage

.set_names(x, names, where = c("col", "row", "attr"))

Arguments

Value

The original object, with new names

Author(s)

Telarico, Fabio Ashtar

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)

Arguments

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

See Also

Other Financial_matrix builders: FF.binary.both(), FF.binary.management(), FF.binary.ownership(), FF.naive.both(), FF.naive.management(), FF.naive.ownership(), FF.norm.both(), FF.norm.management(), FF.norm.ownership()

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')

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")

Arguments

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, ...)

Arguments

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, ...)

Arguments

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)

Arguments

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, ...)

Arguments

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"
)

Arguments

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

See Also

Other Financial_matrix builders: FF(), FF.binary.management(), FF.binary.ownership(), FF.naive.both(), FF.naive.management(), FF.naive.ownership(), FF.norm.both(), FF.norm.management(), FF.norm.ownership()

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 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
)

Arguments

Value

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

Author(s)

Telarico, Fabio Ashtar

See Also

Other Financial_matrix builders: FF(), FF.binary.both(), FF.binary.ownership(), FF.naive.both(), FF.naive.management(), FF.naive.ownership(), FF.norm.both(), FF.norm.management(), FF.norm.ownership()

Examples

# 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
)

Arguments

Value

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

Author(s)

Telarico, Fabio Ashtar

See Also

Other Financial_matrix builders: FF(), FF.binary.both(), FF.binary.management(), FF.naive.both(), FF.naive.management(), FF.naive.ownership(), FF.norm.both(), FF.norm.management(), FF.norm.ownership()

Examples

# 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"))

Arguments

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

See Also

FF.net FF.net.custom FF.graph.custom

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')

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)),
  ...
)

Arguments

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

See Also

FF.net FF.net.custom FF.graph

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 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"
)

Arguments

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

See Also

Other Financial_matrix builders: FF(), FF.binary.both(), FF.binary.management(), FF.binary.ownership(), FF.naive.management(), FF.naive.ownership(), FF.norm.both(), FF.norm.management(), FF.norm.ownership()

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 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
)

Arguments

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

See Also

Other Financial_matrix builders: FF(), FF.binary.both(), FF.binary.management(), FF.binary.ownership(), FF.naive.both(), FF.naive.ownership(), FF.norm.both(), FF.norm.management(), FF.norm.ownership()

Examples

# 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
)

Arguments

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

See Also

Other Financial_matrix builders: FF(), FF.binary.both(), FF.binary.management(), FF.binary.ownership(), FF.naive.both(), FF.naive.management(), FF.norm.both(), FF.norm.management(), FF.norm.ownership()

Examples

# 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"))

Arguments

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

See Also

FF.net.custom FF.graph FF.graph.custom

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')

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)),
  ...
)

Arguments

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 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

See Also

FF.net FF.graph FF.graph.custom

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 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"
)

Arguments

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

See Also

Other Financial_matrix builders: FF(), FF.binary.both(), FF.binary.management(), FF.binary.ownership(), FF.naive.both(), FF.naive.management(), FF.naive.ownership(), FF.norm.management(), FF.norm.ownership()

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 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
)

Arguments

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

See Also

Other Financial_matrix builders: FF(), FF.binary.both(), FF.binary.management(), FF.binary.ownership(), FF.naive.both(), FF.naive.management(), FF.naive.ownership(), FF.norm.both(), FF.norm.ownership()

Examples

# 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
)

Arguments

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

See Also

Other Financial_matrix builders: FF(), FF.binary.both(), FF.binary.management(), FF.binary.ownership(), FF.naive.both(), FF.naive.management(), FF.naive.ownership(), FF.norm.both(), FF.norm.management()

Examples

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

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)

Arguments

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

See Also

FO.binary FO.naive FO.norm

Examples

# 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)

Arguments

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

See Also

FM FO.naive FO.norm

Examples

# 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)

Arguments

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

See Also

FM FO.binary FO.norm

Examples

# 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)

Arguments

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

See Also

FM FO.binary FO.naive

Examples

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

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

A (virtual) class union for matrix-like objects to be included in financial_matrix

Description

This is the un-exported basis for the S4 classes financial_matrix

Tarjan's algorithm for finding strongly connected components

Description

This function performs a depth-first search (DFS) on a directed graph to identify strongly connected components (SCCs) and their size

Usage

SCC(test_m)

Arguments

Details

This function is a modified version of the R implementation of Tarjan's algorithm for finding strongly connected components in directed graphs by Ettore Settanni at the University of Cambridge (see References).

The function consists of several internal steps:

1. Node Labeling - All nodes are labeled with two-digit names for clarity in referencing.

2. Successor List Creation - For each node, lists of direct successors are compiled.

3. Utilization Table Setup - A table is set up for tracking exploration details such as depth and backtracking information.

4. Main DFS Loop - The core loop where DFS occurs, including node visitation and backtracking logic to determine SCCs.

5. Stack Management - Nodes are managed in a stack to keep track of the current path of exploration and to facilitate backtracking.

6. SCC Identification - Upon finishing exploration of an SCC, it is identified and nodes are popped from the stack.

Value

A list containing two elements:

• n - number of strongly connected components

• sizes - size of each strongly connected component, in order of discovery

Author(s)

Settanni,Ettore

Telarico, Fabio Ashtar

References

Settanni, Ettore. ‘RtarD - Find Strongly Connected Components in a Digraph Using R’. R, 15 November 2021. https://github.com/Dr-Eti/RtarD-Tarjans_DFS_in_R.

See Also

Other SCC finders: SCC2()

Tarjan's algorithm for finding strongly connected components in C++

Description

This function performs a depth-first search (DFS) on a directed graph to identify strongly connected components (SCCs) and their size

Usage

SCC2(x)

Arguments

Details

This function is a modified version of the C++ implementation of Tarjan's algorithm for finding strongly connected components in directed graphs made available by the webiste Geeks for Geeks (see References).

The function consists of several internal steps:

1. Node Labeling - All nodes are labeled with two-digit names for clarity in referencing.

2. Successor List Creation - For each node, lists of direct successors are compiled.

3. Utilization Table Setup - A table is set up for tracking exploration details such as depth and backtracking information.

4. Main DFS Loop - The core loop where DFS occurs, including node visitation and backtracking logic to determine SCCs.

5. Stack Management - Nodes are managed in a stack to keep track of the current path of exploration and to facilitate backtracking.

6. SCC Identification - Upon finishing exploration of an SCC, it is identified and nodes are popped from the stack.

Value

A list containing two elements:

• n - number of strongly connected components

• sizes - size of each strongly connected component, in order of discovery

Author(s)

Geeks for Geeks

Telarico, Fabio Ashtar

References

Geeks for Geeks. ‘Strongly Connected Components’. C++, 17 January 2024. https://www.geeksforgeeks.org/strongly-connected-components/.

See Also

Other SCC finders: SCC()

Create list of edges for SCC2

Description

Create list of edges for SCC2

Usage

SCC2.prep(x)

Arguments

Value

If there are at least two non-zero rows:

• A list whose elements are vectors representing the ties between units as c(starting_node, end_node) for the function #' SCC2(). Otherwise,

• A list like those produced by SCC2() and SCC().

Note: Isolated nodes are not returned, but the object x2 is modified in place to store information on their number if the matrix has at least two non-null rows.

Author(s)

Telarico, Fabio Ashtar

See Also

[SCC2()]

Function to set a vertex or edge attribute of a network or graph object

Description

Function to set a vertex or edge attribute of a network or graph object

Usage

add.attribute(x, where = c("edge", "vertex"), attr_name, value, which = NULL)

Arguments

Value

A network or graph object with the desired attribute

Author(s)

Telarico, Fabio Ashtar

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, ...)

Arguments

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, ...)

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

Coerce a financial_matrix object into a list of firm objects

Description

Un-exported function behind the as.firm method for objects of class financial_matrix

Usage

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

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

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)
)

Arguments

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)

Determine if all the non-NA slots of a financial_matrix object are of a given length

Description

Un-exported function called by the ncol and nrow methods for objects of class financial_matrix

Usage

check.against.other.slots(x, number)

Arguments

Author(s)

Telarico, Fabio Ashtar

Function to check whether the provided colour is actually a shade of grey and correct it if necessary

Description

Function to check whether the provided colour is actually a shade of grey and correct it if necessary

Usage

check.correct.grey(hex)

Arguments

Value

A valid grey colour in RGB format

Author(s)

Telarico, Fabio Ashtar

Function to extract the bare matrix from several complex objects

Description

Function to extract the bare matrix from several complex objects

Usage

extract.matrix(x, .except.igraph = FALSE)

Arguments

Value

A matrix or an object from the package Matrix

Author(s)

Telarico, Fabio Ashtar

See Also

Other Internal matrix (de)constructrs: get.matrix.adjacency(), get.matrix.adjacency.both(), load.Matrix()

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)

Arguments

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:

1. TRUE for the generalised Laplacian;

2. FALSE for the possibly complex (and uninterpretable) eigenvalue of the as-is Laplacian.

3. 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)
}

An S4 class for the adjacency matrix produced by FF and related functions to represent the relations between firms (legal person)

Description

An S4 class for the adjacency matrix produced by FF and related functions to represent the relations between firms (legal person)

Slots

M

Adjacency matrix

relation

Relations represented by the matrix

legal_form

Legal form of the firms

sector

Sector in which the firms operate

revenues

Yearly revenues

capitalisation

Firms' capitalisation

currency

Currency in which the capitalisation and revenues are expressed

A virtual class for relational data extending the packages networkand igraph

Description

This is the un-exported virtual base for the S4 classes igraph_financial and network_financial to represent the relations between firms (legal person)

Slots

relation

Relations represented by the matrix

vertex.size

Attribute used to determine the vertexes' size

vertex.color

Attribute used to determine the vertexes' colour

edge.width

Whether the edges' width reflect tie weight

edge.greyscale

Whether the edges' color reflects tie weight

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
)

Arguments

Value

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

Author(s)

Telarico, Fabio Ashtar

See Also

register.firm find.firms

Examples

# 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
)

Arguments

Details

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

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').

Value

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

Author(s)

Telarico, Fabio Ashtar

See Also

find.firm

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

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)

Arguments

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')

A firm

Description

An S4 class to representing a firm (legal person) as a financial entity

Details

This S4 class stores all information on a firm created using register.firm or find.firm. The firm's property can be accessed using the relative function (see query.firm)

Slots

name

Name of the firm

id

Provide an ID code for the firm.

legal_form

Legal form of the firm

sector

Sector in which the firm operates

sector_classif

Activity sector classification (if any)

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

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')

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')

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 compute the binary values of the FM or FO matrix for multiple firm objects

Description

Function to compute the binary values of the FM or FO matrix for multiple firm objects

Usage

get.binarary.values(firms, which, cols = NULL)

Arguments

Value

The values to be filled in the binary FO or FM matrix

Author(s)

Telarico, Fabio Ashtar

Create any firm-firm (FF) matrix for common ownership or board interlocks

Description

Function to create a firm-firm (FF) matrix based on ownership or board interlocks:

Usage

get.matrix.adjacency(
  ...,
  who = c("managers", "owners"),
  ties = 3,
  id_as_firm_name = NULL,
  Matrix = NULL,
  self_ties = FALSE
)

Arguments

Details

The possible values of ties and their effect relative to the value of who are:

binary or 0 for binary ties. Namely:

• for owners: 1 if there is at least one common owner, 0 otherwise;

• for managers: 1 if there is at least one common manager, 0 otherwise.

naive, or 1 for 'naively' valued ties. Namely:

• for owners, the number of common owners;

• for managers, the number of common managers.

share or 2 (the default) for 'normalised' tie values. Namely:

• for owners, the share of i's owners who are also amongst j's owners;

• for managers, the share of i's managers who are also amongst j's managers.

Value

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

Author(s)

Telarico, Fabio Ashtar

See Also

FF

Other Internal matrix (de)constructrs: extract.matrix(), get.matrix.adjacency.both(), load.Matrix()

Create a firm-firm (FF) matrix

Description

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

Usage

get.matrix.adjacency.both(
  ...,
  ties = 3,
  id_as_firm_name = NULL,
  Matrix = NULL,
  self_ties = FALSE,
  combining = "sum"
)

Arguments

Details

The possible values of ties and their effect relative to the value of who are:

binary or 1 for binary ties: 1 if there is at least one common manager or owner, 0 otherwise.

naive, or 2 for 'naively' valued ties indicating the number of common managers and owners.

share or 3 (the default) for 'normalised' tie values. The actual value depends on combining:

• for sum (the default), the sum of the share of i's owners who are also amongst j's owners and the share of i's managers who are also amongst j's managers (normalised to 2);

• for mean or avg, the mean of the share of i's owners who are also amongst j's owners and the share of i's managers who are also amongst j's managers (normalised to 1);

• for max, the maximum between the share of i's owners who are also amongst j's owners and the share of i's managers who are also amongst j's managers (normalised to 1);

• for min, the minimum between the share of i's owners who are also amongst j's owners and the share of i's managers who are also amongst j's managers (normalised to 1);

Value

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

Author(s)

Telarico, Fabio Ashtar

See Also

FF.

Other Internal matrix (de)constructrs: extract.matrix(), get.matrix.adjacency(), load.Matrix()

Function to create a firm-owner (FO) or firm-manager (FM) matrix

Description

The possible values of ties are:

• binary or 1 for binary ties;

• weighted, valued, or 2 to weight the tie between company i and the person j as the value of j's share of i's capital;

• share or 3 (the default) to weight the tie between company i and the person j as the share of i's capital owned by j.

Usage

get.matrix.twomode(..., who, ties = 3, id_as_firm_name = NULL, Matrix = NULL)

Arguments

Value

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

the rows

Represent firms;

the columns

Represent managers/owners (physical and legal persons).

Author(s)

Telarico, Fabio Ashtar

See Also

FM FO.binary FO.naive FO.norm

Create any firm-firm (FF) network

Description

Create a network (either an object of class network from the package network or a graph object from the package igraph) from a FF, FO, or FM matrix

Usage

get.net(
  x,
  vertex.size = NULL,
  vertex.colour = NULL,
  edge.width = NULL,
  edge.greyscale = NULL,
  format = c("igraph", "network"),
  directed = TRUE,
  loops = FALSE,
  weighted = any(!x@M %in% c(0, 1)),
  ...
)

Arguments

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 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

See Also

FF.net FF.net.custom FF.graph FF.graph.custom

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, ...)

Arguments

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, ...)

Arguments

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)

Arguments

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

Function to check whether an object is neither NA nor NULL

Description

Combines base::is.na(x)|> magrittr::not() and base::is.null(x)|> magrittr::not().

Usage

is.neither.null.nor.na(x)

Arguments

Value

Logical: TRUE if x is neither NA or NULL, FALSE otherwise.

Author(s)

Telarico, Fabio Ashtar

Function to check whether an object is NA or NULL

Description

Combines base::is.na(x), base::is.null(x). When negating is TRUE, it integrates also f(x)|> magrittr::not().

Usage

is.null.na(x, negating = FALSE)

Arguments

Value

Logical, depending on negating:

• if negating is FALSE, it returns TRUE if x is NA or NULL;

• if negating is TRUE, it returns TRUE if x is neither NA nor NULL.

Author(s)

Telarico, Fabio Ashtar

Function to list multiple objects passed as ...

Description

Function to list multiple objects passed as ...

Usage

listing(..., naming = TRUE)

Arguments

Value

A (possibly named) list of the provided objects.

Author(s)

Telarico, Fabio Ashtar

Function to load the package Matrix

Description

Checks if the package is required and check whether it is available

Usage

load.Matrix(x, pos = 1L)

Arguments

Value

A logical whether to load the package Matrix

Author(s)

Telarico, Fabio Ashtar

See Also

Other Internal matrix (de)constructrs: extract.matrix(), get.matrix.adjacency(), get.matrix.adjacency.both()

Function to extract the symbols of the objects passed as ...

Description

This function will not work when called inside the function to which the objects were explicitly passsed as ....

Usage

naming(...)

Arguments

Value

A vector of strings matching the provided objects' symbols.

Author(s)

Telarico, Fabio Ashtar

References

https://stackoverflow.com/a/11892680

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))
)

Arguments

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)
}

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, ...)

Arguments

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, ...)

Arguments

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

Function to create the default palette and ramp it up as needed

Description

Function to create the default palette and ramp it up as needed

Usage

palette(length = 6)

Arguments

Value

A vector of RGB codes containing length colours

Author(s)

Telarico, Fabio Ashtar

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, ...)

Arguments

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, ...)

Arguments

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 financial_matrix

Description

Print method for the objects of class financial_matrix

Usage

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

Arguments

Value

No return value, called to print to the console information about the financial_matrix object:

• type of relation detail (common ownership, board interlocks, or both),

• Total capitalisation of the firms present (if known), broke down by currency (if more than one);

• Average total revenues (if known), broke down by currency (if more than one)

• A print-out of the matrix, up to the number of character given by options('max.print').

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)

Arguments

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

Print information on a igraph_financial object

Description

Method to print objects of class igraph_financial

Usage

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

Arguments

Details

For more information see the relevant igraph function: print.igraph

Value

Nothing, called for printing to the console the following information:

• The first line contains the basic properties of the graph;

• The rest of the of the print-out contains the graph's attributes. After the attribute names, the kind of the attribute – graph (‘g’), vertex (‘v’) or edge (‘e’) – is denoted, and the type of the attribute as well, character (‘c’), numeric (‘n’), logical (‘l’), or other (‘x’).

Author(s)

Telarico, Fabio Ashtar

Print information on a network_financial object

Description

Method to print objects of class network_financial

Usage

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

Arguments

Value

Prints the list of global attributes of the network as if network::print.network() had been called. See print.network for more details.

Author(s)

Telarico, Fabio Ashtar

Print information on a financial_matrix

Description

Un-exported function behind the print methods for objects of class financial_matrix

Usage

print_financial_matrix(x)

Arguments

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)

Arguments

Value

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

Author(s)

Telarico, Fabio Ashtar

See Also

query.firms query.firms.dataframe

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)

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)

Arguments

Value

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

Author(s)

Telarico, Fabio Ashtar

See Also

query.firm query.firms.dataframe

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'))

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)

Arguments

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

See Also

query.firm query.firms

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'))

Function to chose the right algorithm when querying one or more information over multiple firm objects

Description

Function to chose the right algorithm when querying one or more information over multiple firm objects

Usage

query.firms_switch(firm, which, naming = TRUE, unlisting = FALSE)

Arguments

Value

The queried information.

Author(s)

Telarico, Fabio Ashtar

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
)

Arguments

Value

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

Author(s)

Telarico, Fabio Ashtar

See Also

find.firm

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'
)

Function to rescale numeric vectors

Description

Rescale continuous vector to have specified minimum and maximum

Usage

rescale.numeric(
  x,
  to = c(0, 1),
  from = range(x, na.rm = TRUE, finite = TRUE),
  ...
)

Arguments

Details

From: The package scales

Value

Re-scaled vector

Author(s)

Hadley Wickham

Show information on a financial_matrix

Description

Show method for the objects of class financial_matrix

Usage

## S4 method for signature 'financial_matrix'
show(object)

Arguments

Value

No return value, called to print to the console information about the financial_matrix object:

• type of relation detail (common ownership, board interlocks, or both),

• Total capitalisation of the firms present (if known), broke down by currency (if more than one);

• Average total revenues (if known), broke down by currency (if more than one)

• A print-out of the matrix, up to six columns by six rows (i.e., 36 cells). An additional row of text is printed out to inform on the truncation of the matrix displayed

Author(s)

Telarico, Fabio Ashtar

Show information on a firm

Description

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

Usage

## S4 method for signature 'firm'
show(object)

Arguments

Value

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

• legal form (if any),

• revenues (if known),

• capitalisation (if known),

• number of members of the board/managers; and

• number of owners/shareholders.

Author(s)

Telarico, Fabio Ashtar

Show information on a igraph_financial

Description

Show method for the objects of class igraph_financial

Usage

## S4 method for signature 'igraph_financial'
show(object)

Arguments

Value

Nothing, called for printing to the console the following information:

• The first line contains the basic properties of the graph;

• The rest of the of the first paragrah contains the graph's attributes. After the attribute names, the kind of the attribute – graph (‘g’), vertex (‘v’) or edge (‘e’) – is denoted, and the type of the attribute as well, character (‘c’), numeric (‘n’), logical (‘l’), or other (‘x’);

• The second paragraph decribes the type of relation represented in the network (common ownership, board interlocks, both);

• The third paragraph informs on whether the size of the vertexes represents an attribute (and, if yes, which one);

• The fourth paragraph informs on whether the colour of the vertexes represents an attribute (and, if yes, which one);

• The fifth paragraph informs on whether the width of the edges represents their strength;

• The sixth paragraph informs on whether the colour of the edges represents their strength.

Author(s)

Telarico, Fabio Ashtar

Show information on a network_financial

Description

Show method for the objects of class network_financial

Usage

## S4 method for signature 'network_financial'
show(object)

Arguments

Author(s)

Telarico, Fabio Ashtar

Show information on a class firm object

Description

Unexported function behind the show methods for objects of class firm

Usage

show_firm(object)

Arguments

Value

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

• legal form (if any),

• revenues (if known),

• capitalisation (if known),

• number of members of the board/managers; and

• number of owners/shareholders.

Author(s)

Telarico, Fabio Ashtar

Show information on a igraph_financial

Description

Un-exported function behind the show method for objects of class igraph_financial

Usage

show_igraph_financial(x)

Arguments

Author(s)

Telarico, Fabio Ashtar

Show information on a network_financial

Description

Un-exported function behind the show method for objects of class network_financial

Usage

show_network_financial(x)

Arguments

Author(s)

Telarico, Fabio Ashtar

Subset a financial_matrix object

Description

Un-exported function behind the subset method for objects of class financial_matrix

Usage

subset_financial_matrix(x, ...)

Arguments

Author(s)

Telarico, Fabio Ashtar