This help section provides a brief listing of various terminology used in Kornucopia.
adv - A commonly used variable name in
Kornucopia examples, typically used as adv
= k_adv();
. After this
expression is evaluated, the variable adv
holds a structure of all Kornucopia function names and their ADV options,
making it easy for the user to quickly access these ADV options using
MATLAB dot and tab syntax.
You can learn more by visiting the help page of the function k_adv or the ADV Parameter
help page.
ADV - The general term for the Kornucopia Advanced argument. This optional argument allows you to specify pairs of ParamNames and ParamVals to override certain behaviors of Kornucopia functions. Learn more on the ADV Parameter help page.
Affine unit - A unit
whose transform to another unit is based on the form y
= m*x + b
. This type of transform is different from
nearly all other Units transforms which are strictly multiplicative,
meaning y = m*x
(there is no
offset). In particular, the units of Celsius and Fahrenheit may or
may not be affine depending on if the unit is referencing an absolute
temperature (it is affine) or a change in temperature (it is
not affine). Kornucopia has advanced logic to handle both cases; see
the help page on Temperature
and Frequency for more details.
cell-string (or cellstr or cellString) - A cell array where each element contains a string.
cell-wrap (or cellwrap) - A variable is placed within a single element cell array. Thus, A = {A}; would be cell-wrapping the variable A. A common use of cell-wrapping is to avoid MATLAB from trying to interpret the variable in a way that is not intended by the user. For example, the function k_tableCreateRecord automatically (by default) cell-wraps arrays of k_units data and structs before it places them into a MATLAB table variable type. If this is not done, the MATLAB table internal processing will attempt to concatenate multiple records placed into a table in such as way as to either create an error or a non-intended behavior. Cell-wrapping the entities before they are placed into the MATLAB table variable ensures that MATLAB views each entry and an entity.
Class - A term used in Object Oriented Programming. A class, in simple terms, is a set of code the defines how a particular data type works, including any Properties and Methods it may have. A class is also where the code for overloaded functions related to that data type reside.
DatenumID - A string that can be used as a unique ID to represent a file. The DatenumID is derived from a time stamp, such as the time stamp of when a file was written or last modified. The DatenumID is the full datenum of the file, stored as a string. A simple example is as follows: For the time stamp 06-Jul-2017 18:33, the Kornucopia DatenumID is the string '736882.772916666697710752487183'. While it is not perfectly guaranteed to be unique, it is highly likely to serve as a good unique stamp for items. Kornucopia returns as part of the output a DatenumID for k_readText, k_readToCellStr, any of the k_sd_Impax* or k_abq* importing functions.
dot-tab syntax - This refers to a commonly set of key-strokes that you can use with MATLAB structures and tables, as well as Kornucopia's k_units data type. The typical typing approach is to type a variable's name, such a myStuff, then type a "dot" (also known as period), then hit the tab key. If the variable has fields, Properties, or Methods, they will show up in a selectable list. This approach makes it very easy for the user to work with variables that have structure to them, making it easy for you to find what you are looking for. The syntax works in both the MATLAB command window and the MATLAB editor.
Do note that a variable must be in memory for this to work. A common scenario for a Kornucopia user is that if they use the adv technique of defining adv = k_adv() to obtain a handy list of ADV options for all functions, the dot-tab syntax will not work until you have computed the command line above so that the variable adv is in memory. This type of require is true for any type of variable you intend to use dot-tab syntax with.
Entity
- A generic term used in Kornucopia to denote either a variable,
a data type, or part of a data type (such as a field in a structure
or an element in a cell array). For example, consider the
expression C = myfunc(A, B, 5, 'first', '3*mm')
.
In the expression, myfunc
is a function name, A
and B
are input variables, 5
is a
scalar data type, 'first'
and '3*mm'
are two strings,
and C
is an output argument
(as called an output variable). The expression has six
entities, namely the five
input arguments and the one output variable.
Installed default settings - Kornucopia has a variety of modifiable settings, most of which are ADV settings. Installed default settings implies the ParamVals for these settings as defined when the software was originally installed. The user can change these defaults for a given MATLAB session or function call as described in the help section on the ADV Parameter.
Kornucopia-compatible
data types - Any data type (or entity),
A
, that can be successfully
converted to a
k_units data type of the class k_units
via
A
= k_units(A)
The Kornucopia function k_units, in the expression above, is also called the constructor function for the class k_units. Data types (or entities) that yield an error for this function evaluation are not Kornucopia-compatible data types. Click here for more detailed discussion on Kornucopia-compatible data types.
k_units data type (or data type k_units) - A data type that is designed to hold scalar or tabular-oriented data, including units and meta-info. The k_units data type is a data type that the Kornucopia software provides.
k_units function (or
function k_units) - The Kornucopia
function, k_units, converts its input argument
into a k_units data type of the class k_units.
The k_units
function is also called the constructor
function for the class k_units.
Kornucopia Results Workbook via a Tabbed Figure - By using easy to create tabbed figures, you can significantly improve the management, documentation, storage, and retrieval of your Kornucopia results. See a brief overview here and the Tutorial - Kornucopia Results Workbook via a Tabbed Figure to learn more.
Kornucopia Tab Management - See here for a brief explanation.
Kornucopia table - The output format style of a k_units data type. A Kornucopia table will display a tabular-like output format to the MATLAB Command Window that has the Props.ColNames, Props.RowNames, Units and Data, and Props.Description Properties all displayed as a nicely formatted table. If any of the Properties listed are empty, then that particular portion of the table is omitted. In addition, if there are any non-empty entries in Props.ColComments, Props.RowComments, or Props.UserData, then a notice is shown at the bottom of the Kornucopia table stating that other Props exist but are not shown. The Kornucopia table also, by default, limits the number of rows shown and does not wrap the table for wide tables. These setting can be changed via the k_set function.
Also consider using k_varViewer to view output of a k_units data type.
Meta-info - Information (text and or numeric) that is associated with an entity. The most common forms of meta-info used in Kornucopia are the Properties Descriptions, ColNames (column names), ColComments, RowNames, RowComments, and UserData (general user data).
Method or Methods - A term used in Object Oriented Programming. A method is a special function that implements operations (calculations) that are usually performed only on instances of the parent class. The k_units class (data type) has four public methods of .convert, .dataSize, .toStruct, and .toTable.
Mtable - An abbreviation sometimes used in Kornucopia to refer to the MATLAB table data type.
OOP - Object Oriented Programming. The k_units data type is created using MATLAB's OOP capabilities. If you do not know about OOP, do not worry. You do not have to do any OOP coding to use Kornucopia and it's k_units data type.
ParamName
and ParamVal - Kornucopia
functions' ADV (advanced) options come in pairs of ParamName,
ParamVal
. The ParamName
is a keyword (specific to a given function's ADV option) and the ParamVal
is its setting. Learn more on
the help page ADV Parameter.
Property or Properties - A term used in Object Oriented Programming. A property is a "data" storage "container" within a data type. The data type's class predefines what properties can exist for that data type and the types of entities ("data") that can go in them. Kornucopia's k_units data type has a variety of properties. See The k_units Data Type to learn more.
Props Inheritance - This refers to the rules and resulting behavior of how Kornucopia handles inheritance issues related to the Props Properties of entities of type k_units. In short, inheritance refers to what, if any, meta-info Properties stored in the Props of an input argument are inherited by (or copied to) an output argument of a function or operation. See Props Inheritance help page for more details.
record - A 1-row MATLAB table. Records are stacked together to make a pseudo database. See the example Pseudo Databases via Tables to learn more.
string - In general within Kornucopia documentation, the word string refers to a MATLAB char data type (a character array). For a long time in MATLAB, the char was the only data type for characters. It was typically referred to as a string and MATLAB functions related to it had str in their names, such as strtrim, cellstr, str2num, and strcmp to name a few. Then around 2016 MATLAB introduced a new data type for character strings called string. It handles character strings differently, especially multi-row character strings than the original char data type does. The char uses single quotes to denote a char data type, such as 'mm' whereas the MATLAB string uses double quotes to denote its data type, such as "Have a nice day". Needless to say, this now creates terminology and syntax confusion! In Kornucopia the following terminology and syntax holds true: unless the combined words MATLAB String are used, Kornucopia generally means a char when the word string is used. Additionally, nearly all Kornucopia functions support the char data type and very few support the MATLAB string data type.
String-list - A string in which entities within the string are delimited by either a comma or semicolon. Click here to learn more. This is an alternate syntax option to the use of a cell-string for several Kornucopia features including:
The Properties of Units
,
Props.ColNames
, and Props.RowNames
of the k_units data type.
Some ParamVals of ADV options for various Kornucopia functions.
Tagged File - Kornucopia's functions k_writeText and k_toCellstrColvec have the option of adding tags around regions in a text file when creating files that hold heterogenous information. Learn more about Kornucopia tagged files here.
Text file - A text file is any non-binary file, meaning it can be opened and sensibly viewed in a text file reader such as Notepad++, Notepad, Textpad, or similar. It is noted that CSV files are text files. Some typical binary files are ones with file extensions such as MAT, XLS, ODB, and DOCX files.
Units Compatibility - This is like the term Units Consistency, but it has a broader application. A calculation done with consistent units implies that all units involved in the calculation are for a single consistent units system. Kornucopia allows you to define and utilize calculations with mixed units, meaning units from different units systems. Kornucopia does all the needed units conversions for you, behind the scenes. Units Compatibly refers to ensuring that such a mixed-units calculation is valid. For example, doing A = 5*N/in + 3*lbf/mm is Units Compatible but attempting A = 5*in + 3*N would NOT be Units Compatible.
Units Consistency - A Units System satisfies Units Consistency when all of its derived units (such as force, pressure, velocity, etc.) have a conversion multiplication factor of 1.0 when the derived unit is defined in terms of the system's base units. See here to learn more.
Units Signature - This
is the fundamental way that Kornucopia tracks units with your numerical
data. The concept is fully described in the help
page on Units Signatures.
A brief simple description is given here. Consider a values 5*N
and 20*lbf
. Both values are representing some value of
force, but in different units. In both cases, force is a derived unit,
meaning it is defined (or derived) from base units. In the case of
Newton, N = kg*m/s^2
.
For pound force, lbf = slug*ft/s^2
. In
both cases, their units signatures
are mass*length/time^2
.
Units System - In Kornucopia, a Units System is a Units Preference that also satisfies Units Consistency. Units Consistency means that derived units (such as force) have a conversion multiplication factor of 1.0 when the derived unit is defined in terms of the system's base units. See here to learn more.
Unit
Variables (or Units Variable)
- These are variables made using the function k_unitsVariables.
Each Unit Variable represents a single unit from the Kornucopia
Units Library, unless the Unit Variable was defined from the function
k_unitsVariables
using the
technique that results in a single structured
Units Variable representing ALL the Kornucopia Units. Unit
Variables allow the user to easily define MATLAB statements or code
such as
k_unitsVariables('kHz, mm, s'); fs = 50*kHz; A = 775.4*mm/s^2;
.
With a structured Units Variable, the same code would be written as
u = k_unitsVariables(); fs = 50*u.kHz; A = 775.4*u.mm/u.s^2;
.