DataSet

The structure used for containing math results. A DataSet contains axes that indicate where quantities are defined, as well as the values for those quantities at each point.

Example

app = pf.GetApplication()
app:NewProject()
app:OpenFile(FEKO_HOME..[[/shared/Resources/Automation/startup.fek]])

-- Create a new DataSet
    
myDataSet = pf.DataSet.New()

    -- Build the axes and quantities:
    --    Frequency axis spanning from 1GHz to 2GHz with 11 values
    --    Add a X axis spanning from -1m to 1m with 11 values
    --    Add a Y axis spanning from -1m to 1m with 11 values
    --    Add a Z axis spanning from -1m to 1m with 11 values
    
myDataSet.Axes:Add( pf.Enums.DataSetAxisEnum.Frequency, "GHz", 1 ,2 ,11)
myDataSet.Axes:Add( pf.Enums.DataSetAxisEnum.X,"m", -1, 1, 11)
myDataSet.Axes:Add( pf.Enums.DataSetAxisEnum.Y,"m", -1, 1, 11)
myDataSet.Axes:Add( pf.Enums.DataSetAxisEnum.Z,"m", -1, 1, 11)

    -- Add some quantities to the quantity collection
    
myDataSet.Quantities:Add( "Threshold", pf.Enums.DataSetQuantityTypeEnum.Scalar, "")
myDataSet.Quantities:Add( "TotalEField", pf.Enums.DataSetQuantityTypeEnum.Complex, "V/m")

    -- Iterate over all the axes and populate the data set values
    
for freqIndex = 1, #myDataSet.Axes["Frequency"] do
    for xIndex = 1, #myDataSet.Axes["X"] do
        for yIndex = 1, #myDataSet.Axes["Y"] do
            for zIndex = 1, #myDataSet.Axes["Z"] do 
                indexedValue = myDataSet[freqIndex][xIndex][yIndex][zIndex]
                xValue = indexedValue:AxisValue(pf.Enums.DataSetAxisEnum.X)
                yValue = indexedValue:AxisValue(pf.Enums.DataSetAxisEnum.Y)
                zValue = indexedValue:AxisValue(pf.Enums.DataSetAxisEnum.Z)
                r = math.sqrt((xValue*xValue)+(yValue*yValue)+(zValue*zValue))
                indexedValue.TotalEField = 1/r + j*(1/r)
                indexedValue.Threshold = 1
            end
        end
    end
end

    -- An iterator function that is used by ForAllValues to populate the data set values
    -- This is equivalent to the above method.
    
function initialise( index, myDataSet )
    indexedValue = myDataSet[index]
    xValue = indexedValue:AxisValue(pf.Enums.DataSetAxisEnum.X)
    yValue = indexedValue:AxisValue(pf.Enums.DataSetAxisEnum.Y)
    zValue = indexedValue:AxisValue(pf.Enums.DataSetAxisEnum.Z)
    r = math.sqrt((xValue*xValue)+(yValue*yValue)+(zValue*zValue))
    indexedValue.TotalEField = 1/r + j*(1/r)
    indexedValue.Threshold = 1
end
pf.DataSet.ForAllValues( initialise, myDataSet )

    -- Store the custom data set and plot it on a 3D view

storedCustomData = myDataSet:StoreData(pf.Enums.StoredDataTypeEnum.Custom)
customDataPlot = app.Views[1].Plots:Add(storedCustomData)
customDataPlot.Quantity.Type = "TotalEField"
app.Views[1]:ZoomToExtents()

Usage locations

The DataSet object can be accessed from the following locations:

Property List

MetaData
Metadata that is associated with the data set. (Read only DataSetMetaData)
Type
The object type string. (Read only string)

Collection List

Axes
The collection of axes defining the positions in the data set where quantities are defined. (DataSetAxisCollection of DataSetAxis.)
Quantities
The collection of quantities that are defined at each point in the data set. (DataSetQuantityCollection of DataSetQuantity.)

Method List

Clone ()
Makes a copy of this dataset and returns it. (Returns a DataSet object.)
CloneStructure ()
Creates a copy of the structure of the dataset but none of its values. (Returns a DataSet object.)
ExportMatFile (filename string, varname string)
Writes the given DataSet object to a *.mat file. (Returns a boolean object.)
FromComplexMatrix (matrix ComplexMatrix, quantityNames List of string)
Fills the data set from a matrix.
FromComplexMatrix (matrix ComplexMatrix, quantityNames List of string, dataAxisName string)
Fills the data set from a matrix.
FromMatrix (matrix Matrix, quantityNames List of string)
Fills the data set from a matrix.
FromMatrix (matrix Matrix, quantityNames List of string, dataAxisName string)
Fills the data set from a matrix.
StoreData (type StoredDataTypeEnum)
Creates a stored copy of the dataset. (Returns a ResultData object.)
ToComplexMatrix (quantityNames List of string)
Extracts data from the data set. (Returns a ComplexMatrix object.)
ToComplexMatrix (quantityNames List of string, dataAxisName string)
Extracts data from the data set. (Returns a ComplexMatrix object.)
ToMatrix (quantityNames List of string)
Extracts data from the data set. (Returns a Matrix object.)
ToMatrix (quantityNames List of string, dataAxisName string)
Extracts data from the data set. (Returns a Matrix object.)
UpdateStoredData (type StoredDataTypeEnum, entity ResultData)
Updates the contents of a stored data entity from the dataset.

Constructor Function List

New ()
Creates a new data set. (Returns a DataSet object.)

Static Function List

CombineDataSets (name string, unit Unit, values List of Variant, sets List of DataSet)
Combines the data sets creating a new outer axis. (Returns a DataSet object.)
ForAllValues (valueFunction function, data DataSet, ...)
Iterates over every point on every axis of the data set.

Index List

[list<number>]
Index into the values of the data set using a table of indices. (Read DataSetIndexer)
[number]
Index into the values of the data set. (Read DataSetIndexer)

Property Details

MetaData
Metadata that is associated with the data set.
Type
DataSetMetaData
Access
Read only
Type
The object type string.
Type
string
Access
Read only

Collection Details

Axes
The collection of axes defining the positions in the data set where quantities are defined.
Type
DataSetAxisCollection
Quantities
The collection of quantities that are defined at each point in the data set.
Type
DataSetQuantityCollection

Method Details

Clone ()
Makes a copy of this dataset and returns it.
Return
DataSet
A copy of the current DataSet.
CloneStructure ()
Creates a copy of the structure of the dataset but none of its values.
Return
DataSet
A structural copy of the current DataSet.
ExportMatFile (filename string, varname string)
Writes the given DataSet object to a *.mat file.
Input Parameters
filename(string)
The name of the file.
varname(string)
The name of the variable to export.
Return
boolean
Boolean indicating success.
FromComplexMatrix (matrix ComplexMatrix, quantityNames List of string)
Fills the data set from a matrix.
Input Parameters
matrix(ComplexMatrix)
Matrix to fill the dataset with.
quantityNames(List of string)
List of quantities the matrix represents.
FromComplexMatrix (matrix ComplexMatrix, quantityNames List of string, dataAxisName string)
Fills the data set from a matrix.
Input Parameters
matrix(ComplexMatrix)
Matrix to fill the dataset with.
quantityNames(List of string)
List of quantities the matrix represents.
dataAxisName(string)
Data axis the matrix represents.
FromMatrix (matrix Matrix, quantityNames List of string)
Fills the data set from a matrix.
Input Parameters
matrix(Matrix)
Matrix to fill the dataset with.
quantityNames(List of string)
List of quantities the matrix represents.
FromMatrix (matrix Matrix, quantityNames List of string, dataAxisName string)
Fills the data set from a matrix.
Input Parameters
matrix(Matrix)
Matrix to fill the dataset with.
quantityNames(List of string)
List of quantities the matrix represents.
dataAxisName(string)
Data axis the matrix represents.
StoreData (type StoredDataTypeEnum)
Creates a stored copy of the dataset.
Input Parameters
type(StoredDataTypeEnum)
The type of stored data entity specified by StoredDataTypeEnum, e.g. FarField, NearField, Custom, etc.
Return
ResultData
The new stored data.
ToComplexMatrix (quantityNames List of string)
Extracts data from the data set.
Input Parameters
quantityNames(List of string)
List of quantities to extract.
Return
ComplexMatrix
A matrix with a quantity in each column.
ToComplexMatrix (quantityNames List of string, dataAxisName string)
Extracts data from the data set.
Input Parameters
quantityNames(List of string)
List of quantities to extract.
dataAxisName(string)
Data of the quantity to extract.
Return
ComplexMatrix
A matrix with the quantities as rows and the axis as columns.
ToMatrix (quantityNames List of string)
Extracts data from the data set.
Input Parameters
quantityNames(List of string)
List of quantities to extract.
Return
Matrix
A matrix with a quantity in each column.
ToMatrix (quantityNames List of string, dataAxisName string)
Extracts data from the data set.
Input Parameters
quantityNames(List of string)
List of quantities to extract.
dataAxisName(string)
Data of the quantity to extract.
Return
Matrix
A matrix with the quantities as rows and the axis as columns.
UpdateStoredData (type StoredDataTypeEnum, entity ResultData)
Updates the contents of a stored data entity from the dataset.
Input Parameters
type(StoredDataTypeEnum)
The type of stored data entity specified by StoredDataTypeEnum, e.g. FarField, NearField, Custom, etc.
entity(ResultData)
The stored data entity that must be updated.

Static Function Details

CombineDataSets (name string, unit Unit, values List of Variant, sets List of DataSet)
Combines the data sets creating a new outer axis.
Input Parameters
name(string)
The name of the axis.
unit(Unit)
The unit of the axis.
values(List of Variant)
The values of the axis in a table.
sets(List of DataSet)
A list of data sets to combine.
Return
DataSet
The new data set with the combined values.
ForAllValues (valueFunction function, data DataSet, ...)
Iterates over every point on every axis of the data set.
Input Parameters
valueFunction(function)
A function that that processes each of the values. Must take at least two arguments (index, dataset, ...).
data(DataSet)
The data set that is iterated over.
...
Any extra arguments that will be passed directly to the value function.
Example
app = pf.GetApplication()
app:NewProject()
app:OpenFile(FEKO_HOME..[[/shared/Resources/Automation/startup.fek]])

-- Create a new DataSet
    
myDataSet = pf.DataSet.New()

    -- Build the axes and quantities:
    --    Frequency axis spanning from 1GHz to 2GHz with 11 values
    --    Add a X axis spanning from -1m to 1m with 11 values
    --    Add a Y axis spanning from -1m to 1m with 11 values
    --    Add a Z axis spanning from -1m to 1m with 11 values
    
myDataSet.Axes:Add(pf.Enums.DataSetAxisEnum.Frequency, "GHz", 1 ,2 ,11)
myDataSet.Axes:Add(pf.Enums.DataSetAxisEnum.X,"m", -1, 1, 11)
myDataSet.Axes:Add(pf.Enums.DataSetAxisEnum.Y,"m", -1, 1, 11)
myDataSet.Axes:Add(pf.Enums.DataSetAxisEnum.Z,"m", -1, 1, 11)

    --    Add a "Threshold" scalar quantity with no unit
    
myDataSet.Quantities:Add( "Threshold", pf.Enums.DataSetQuantityTypeEnum.Scalar, "")

    -- An iterator function that initialises all of the defined values
    -- to to the value provided as an extra argument to the 'forAllValues'
    -- function.
    
function initialise( index, myDataSet, initialValue )
    myDataSet[index].Threshold = initialValue
end
pf.DataSet.ForAllValues(initialise, myDataSet, 2)

    -- Store the custom data set and plot it on a 3D view

storedCustomData = myDataSet:StoreData(pf.Enums.StoredDataTypeEnum.Custom)
app.Views[1].Plots:Add(storedCustomData)
app.Views[1]:ZoomToExtents()
New ()
Creates a new data set.
Return
DataSet
The new data set.