nwpredmodel class

Predictor model class, which specifies the mapping from nodes and excitations of a network structure to inputs and outputs of a predictor model. An instance of this class is required for single module/subnetwork identification, where a subset of the excitation and node signals from the full network are required for the estimation of the target module/subnetwork. Single module identification is currently only supported for directed networks, and subnetwork identification is only supported for diffusively coupled networks. For identification in a directed network, specify the mappings G, T and H. For identification in a diffusively coupled network, specify the mappings X, Y, B and F.

Construction

pred = nwpredmodel(networkStructure) creates a full network identification predictor model based on the topology in the provided LabelledAdjStruct argument.
pred = nwpredmodel(networkStructure,target,Rset,Dset,Yset) creates a single module identification (for directed networks) or subnetwork identification (for diffusively coupled networks) predictor model based on the topology in the provided LabelledAdjStruct argument, and the provided target, input excitations (Rset), input nodes (Dset) and output nodes (Yset).
pred = nwpredmodel(path) creates a predictor model object from file, previously stored using the save method.
pred = nwpredmodel(__,Name=Value) creates a predictor model with additional properties set according to the provided values. The Name, nE, Variable, Ts and properties can be set in this way.

Properties

Name
character array string
Name of the predictor model. Empty by default.
Variable
character array string
Global variable of transfer functions in predictor mappings. See documentation on the equivalent property in the transfer function object tf. 'z^-1' by default.
Ts
scalar
Global sample time of transfer functions in predictor mappings. See documentation on the equivalent property in the transfer function object tf. -1 by default
NetworkStructure
Structure array
Details of the network structure from which the predictor model is generated. When set either during construction or after, this structure must be provided as a LabelledAdjStruct object. The object is then converted to a structure array. Modifying fields of this structure array directly is currently not supported.
type
string
Type of the predictor model. Currently only 'tf' is supported.
hasTarget
logical scalar
Indicates if the predictor model has a target.
fullNetwork
logical scalar
Indicates if the predictor model specifies full network identification.
target
[:,2] array
Target module(s) for identification, specified by the indices of the input and output nodes in the network structure. Similar to targetLabelNr, but here the set of integers refers to the position of the nodes in the network structure, rather than the node numbers. For example, when NetworkStructure.NodeNumbers = [1 3 2 4] and targetLabelNr = [1 2], then target = [1 3].
Rset
$[1,n_{R}]$ array
Indices of input excitations in the predictor model. Similar to RsetLabelNr, but here the set of integers refers to the position of the excitations in the network structure, rather than the excitation numbers. For example, when NetworkStructure.ExcitationNumbers = [1 3 2 4] and RsetLabelNr = [1 2], then Rset = [1 3].
Dset
$[1,n_{D}]$ array
Indices of input nodes in the predictor model. Similar to DsetLabelNr, but here the set of integers refers to the position of the nodes in the network structure, rather than the node numbers. For example, when NetworkStructure.NodeNumbers = [1 3 2 4] and DsetLabelNr = [1 2], then Dset = [1 3].
Yset
$[1,n_{Y}]$ array
Indices of output nodes in the predictor model. Similar to YsetLabelNr, but here the set of integers refers to the position of the nodes in the network structure, rather than the node numbers. For example, when NetworkStructure.NodeNumbers = [1 3 2 4] and YsetLabelNr = [1 2], then Yset = [1 3].
targetLabelNr
[:,2] integer array
Target module(s) for identification, specified by the label numbers of the input and output nodes in the network structure (corresponding to NetworkStructure.NodeNumbers). An empty ([0,2]) array indicates the full network should be identified. Defaults to an empty array.
RsetLabelNr
$[1,n_{R}]$ integer array
Label numbers of input excitations in the predictor model, corresponding to NetworkStructure.ExcitationNumbers. For a full network predictor model, all excitations in the NetworkStructure property appear in the input. For a single module predictor model, this property defaults to an empty array.
DsetLabelNr
$[1,n_{D}]$ integer array
Numbers of input nodes in the predictor model, corresponding to NetworkStructure.NodeNumbers. For a full network predictor model, all nodes in the NetworkStructure property appear in the output. For a single module predictor model, this property defaults to an empty array.
YsetLabelNr
$[1,n_{Y}]$ integer array
Numbers of output nodes in the predictor model, corresponding to NetworkStructure.NodeNumbers. For a full network predictor model, all nodes in the NetworkStructure property appear in the output. For a single module predictor model, this property defaults to an empty array.
G
PredictorMap object
Structural and estimation properties of the mapping from input nodes to output nodes. By default, for a full network identification model, the parametrized elements (.p) are based on the fixed field of the network structure (NetworkStructure) property. For a single module identification model, all elements are parametrized. All (present) elements have a delay of 1 (strictly proper), and there are no monic terms. The number of free parameters of the numerator (npnum) and denominator npden of each element is equal to the global order.
T
PredictorMap object
Structural and estimation properties of the mapping from excitations to output nodes. By default, for a full network identification model, the parametrized elements (.p) are based on the fixed field of the network structure (NetworkStructure) property. For a single module identification model, all elements are parametrized. All fixed terms of T are set to unit gain by default.
H
PredictorMap object
Structural and estimation properties of the mapping from noise signals to output nodes. By default, for a full network identification model, the parametrized elements (.p) are based on the fixed field of the network structure (NetworkStructure) property. For a single module identification model, all elements are parametrized. All (present) off-diagonal elements have a delay of 1, and all (present) diagonal elements are monic. The number of free parameters of the numerator (npnum) and denominator npden of each element is equal to the global order.
X
PredictorMap object
Structural and estimation properties of the mapping from nodes to the ground in a diffusively coupled (sub)network. By default, for a full network identification model, the parametrized elements (.p) are based on the fixed field of the network structure (NetworkStructure) property. For a subnetwork identification model, all elements are parametrized. The number of free parameters of the numerator (npnum) of each element is equal to the global order. Since X is a polynomial, npden must be 0 for all elements.
Y
PredictorMap object
Structural and estimation properties of the mapping from nodes to other nodes in a diffusively coupled (sub)network. By default, for a full network identification model, the parametrized elements (.p) are based on the fixed field of the network structure (NetworkStructure) property. For a subnetwork identification model, all elements are parametrized. The number of free parameters of the numerator (npnum) of each element is equal to the global order. Since Y is a polynomial, npden must be 0 for all elements. Due to the indirected interconnections in diffusively coupled networks, isSymmetric must also be true.
B
PredictorMap object
Structural and estimation properties of the mapping from excitation signals to nodes in a diffusively coupled (sub)network. By default, for a full network identification model, the parametrized elements (.p) are based on the fixed field of the network structure (NetworkStructure) property. For a subnetwork identification model, all elements are parametrized. All fixed terms of B are set to unit gain by default. The number of free parameters of the numerator (npnum) of each element is equal to the global order. Since B is a polynomial, npden must be 0 for all elements.
F
PredictorMap object
Structural and estimation properties of the mapping from noise signals to nodes in a diffusively coupled (sub)network. By default, for a full network identification model, the parametrized elements (.p) are based on the fixed field of the network structure (NetworkStructure) property. For a subnetwork identification model, all elements are parametrized. All (present) off-diagonal elements have a delay of 1, and all (present) diagonal elements are monic. The number of free parameters of the numerator (npnum) and denominator npden of each element is equal to the global order.
order
positive scalar
Initial orders of the predictor mappings. Note that this order can be superseded by modifying the predictor mapping properties (e.g. G).
Report
nwreport object
Estimation report, containing e.g. information on data used, fit and estimation method used.
aux
AuxPred object
Object that contains additional information which can be either input or output to a specific identification algorithm.
nodesW
struct
Structure specifying the indices of the input and output nodes in the predictor model, with the fields:
- Y (nodes appearing in output)
- D (nodes appearing in input)
- Q (nodes appearing in both input and output)
- O (nodes appearing only in output)
- U (nodes appearing only in input)
nodesR
$[n_{R},1]$ array
Indices of excitations appearing in the predictor model.
idmodule
tf object
Transfer function representation of the (to be) identified module. Retrieved by indexing the G property with the indices specified in the target property.
nD
positive scalar
Number of input nodes.
nY
positive scalar
Number of output nodes.
nR
positive scalar
Number of excitation signals.
nE
positive scalar
Number of noise signals.
nU
positive scalar
Total number of inputs.
full
logical scalar
Indicates if the predictor model specifies full network identification.
struc
LabelledAdjStruct object
Shorthand for NetworkStructure


character array	string


character array	string


scalar


Structure array


string


logical scalar


logical scalar


`[:,2]` array


$[1,n_{R}]$ array


$[1,n_{D}]$ array


$[1,n_{Y}]$ array


`[:,2]` integer array


$[1,n_{R}]$ integer array


$[1,n_{D}]$ integer array


$[1,n_{Y}]$ integer array


`PredictorMap` object


`PredictorMap` object


`PredictorMap` object


`PredictorMap` object


`PredictorMap` object


`PredictorMap` object


`PredictorMap` object


positive scalar


`nwreport` object


`AuxPred` object


`struct`


$[n_{R},1]$ array


`tf` object


positive scalar


positive scalar


positive scalar


positive scalar


positive scalar


logical scalar


`LabelledAdjStruct` object

Methods

save
Save properties of the object.
Syntax
- save(pred,path) stores a struct containing the properties of the predictor model object at the location specified by path.
Input arguments
- pred
  nwpredmodel object
- path
  character array string
  Path to folder in which the predictor model details should be stored.
get
Displays the properties of the object.
Syntax
- get(pred) displays a struct containing the properties of the nwpredmodel object.
Input arguments
- pred
  nwpredmodel object
residuals
Compute residuals after identification based on a data set.
Syntax
- eps = residuals(pred,data) returns residuals based on the identified model object and a data set.
Input arguments
- pred
  nwpredmodel object
- data
  nwdata object
  Data set compatible with predictor model. Can be the same data as was used for identification, or an external (validation) set.
Output arguments
- eps
  $[N,n_{Y}]$ array
  Computed residuals.
plotCorrelation
Plot auto-/cross-correlation. Plot autocorrelation between a residual with itself, or plot the cross-correlation with an excitation/node. The plot includes 95% confidence bounds.
Syntax
- plotCorrelation(pred,data,outputLabel,inputLabel,ax) plots correlation using residuals based on provided data set.
Input arguments
- pred
  nwpredmodel object
- data
  nwdata object
  Data set compatible with predictor model. Can be the same data as was used for identification, or an external (validation) set.
- outputLabel
  character array string
  Node label (e.g. 'w3') corresponding to the residual to be correlated with.
- inputLabel
  character array string
  Node/excitation label (e.g. 'r2') corresponding to the node/excitation signal used in cross-correlation. Specify an empty string for autocorrelation of the outputLabel.
- ax
  Axes object
  Axis to plot the autocorrelation/cross-correlation on. If this argument is not specified, a new figure is created.
Output arguments
- eps
  $[N,n_{Y}]$ array
  Computed residuals.

nwpredmodel class

Construction​

Properties​

Name​

Variable​

Ts​

NetworkStructure​

type​

hasTarget​

fullNetwork​

target​

Rset​

Dset​

Yset​

targetLabelNr​

RsetLabelNr​

DsetLabelNr​

YsetLabelNr​

G​

T​

H​

X​

Y​

B​

F​

order​

Report​

aux​

nodesW​

nodesR​

idmodule​

nD​

nY​

nR​

nE​

nU​

full​

struc​

Methods​

save​

Syntax​

Input arguments​

get​

Syntax​

Input arguments​

residuals​

Syntax​

Input arguments​

Output arguments​

plotCorrelation​

Syntax​

Input arguments​

Output arguments​

Construction

Properties

Name

Variable

Ts

NetworkStructure

type

hasTarget

fullNetwork

target

Rset

Dset

Yset

targetLabelNr

RsetLabelNr

DsetLabelNr

YsetLabelNr

G

T

H

X

Y

B

F

order

Report

aux

nodesW

nodesR

idmodule

nD

nY

nR

nE

nU

full

struc

Methods

save

Syntax

Input arguments

get

Syntax

Input arguments

residuals

Syntax

Input arguments

Output arguments

plotCorrelation

Syntax

Input arguments

Output arguments