Help for package massProps

Title:

Calculate Mass Properties and Uncertainties of Tree Structures

Version:

0.3.3

Description:

Recursively calculates mass properties (mass, center of mass, moments and products of inertia, and optionally, their uncertainties) for arbitrary decomposition trees. R. L. Zimmerman, J. H. Nakai. (2005) https://www.sawe.org/product/paper-3360/).

License:

MIT + file LICENSE

Encoding:

UTF-8

RoxygenNote:

7.3.2

Imports:

rollupTree (≥ 0.1.0)

Depends:

R (≥ 3.5)

LazyData:

true

Suggests:

igraph, knitr, rmarkdown, testthat (≥ 3.0.0)

Config/testthat/edition:

VignetteBuilder:

knitr

URL:

https://jsjuni.github.io/massProps/, https://github.com/jsjuni/massProps

BugReports:

https://github.com/jsjuni/massProps/issues

NeedsCompilation:

Packaged:

2025-06-20 20:56:20 UTC; sjenkins

Author:

James Steven Jenkins

[aut, cre, cph]

Maintainer:

James Steven Jenkins <sjenkins@studioj.us>

Repository:

CRAN

Date/Publication:

2025-06-20 21:10:02 UTC

massProps: Calculate Mass Properties and Uncertainties of Tree Structures

Description

Author(s)

Maintainer: James Steven Jenkins sjenkins@studioj.us (ORCID) [copyright holder]

Add radii of gyration

Description

add_radii_of_gyration() adds calculated radii of gyration to a data frame of rolled-up mass properties.

Radii of gyration are calculated directly from moments of inertia and mass; they are not recursively-defined, and do not require a rollup method.

Usage

add_radii_of_gyration(df)

Arguments

df

A data frame with (at least) these columns: id, mass, Cx, Cy, Cz, Ixx, Iyy, Izz, Ixy, Ixz, Iyz, POIconv, Ipoint.

Value

A data frame with the same columns as df, plus radii of gyration in columns kx, ky, and kz.'

Examples

test_table_rollup <- rollup_mass_props(test_tree, test_table)
add_radii_of_gyration(test_table_rollup)

Combine mass properties

Description

combine_mass_props() calculates the mass properties of an aggregate from a list of constituent mass properties.

Usage

combine_mass_props(mpl)

Arguments

mpl

A list of mass properties lists, each of which contains the following named elements:

mass Numeric mass.
center_mass Numeric 3-vector center of mass.
point Logical indicating point mass. The inertia of point masses is excluded from calculations.
inertia Numeric 3x3 matrix inertia tensor.

Details

See vignette("massProps", package = "massProps") for details on the algorithms employed.

Value

Combined mass properties list with the same named elements.

Examples

leaves <- names(igraph::neighbors(test_tree, "A.3", mode = "in"))
mpl <- Map(f = function(id) get_mass_props(test_table, id), leaves)
combine_mass_props(mpl)

Combine mass properties and uncertainties

Description

combine_mass_props_and_unc() is a convenience wrapper that concatenates the results of combine_mass_props() and combine_mass_props_unc().

Usage

combine_mass_props_and_unc(mpl)

Arguments

mpl

A list of mass properties and uncertainties lists, each of which contains the following named elements:

mass Numeric mass.
center_mass Numeric 3-vector center of mass.
point Logical indicating point mass. The inertia of point masses is excluded from calculations.
inertia Numeric 3x3 matrix inertia tensor.
sigma_mass mass uncertainty
sigma_center_mass center of mass uncertainty (3-dimensional numeric)
sigma_inertia Inertia tensor uncertainty (3x3 numeric matrix)

Value

Combined mass properties list with the same named elements.

Examples

leaves <- names(igraph::neighbors(sawe_tree, "Combined", mode = "in"))
mpl <- Map(f = function(id) get_mass_props_and_unc(sawe_table, id), leaves)
combine_mass_props_and_unc(mpl)

Combine mass properties uncertainties

Description

combine_mass_prop_unc() calculates the mass properties uncertainties of an aggregate from the mass properties and uncertainties of its constituents and the mass properties of the aggregate.

Usage

combine_mass_props_unc(mpl, amp)

Arguments

mpl

A list of mass properties and uncertainties lists, each of which contains the following named elements:

mass Numeric mass.
center_mass Numeric 3-vector center of mass.
point Logical indicating point mass. The inertia of point masses is excluded from calculations.
inertia Numeric 3x3 matrix inertia tensor.
sigma_mass mass uncertainty
sigma_center_mass center of mass uncertainty (3-dimensional numeric)
sigma_inertia Inertia tensor uncertainty (3x3 numeric matrix)

amp

A named list of mass properties for the aggregate containing the following named elements:

mass Numeric mass.
center_mass Numeric 3-vector center of mass.
point Logical indicating point mass. The inertia of point masses is excluded from calculations.
inertia Numeric 3x3 matrix inertia tensor.

Details

See vignette("massProps", package = "massProps") for details on the algorithms employed.

Value

The mass properties and uncertainties of the aggregate. A list with the same elements as members of mpl.

Examples

leaves <- names(igraph::neighbors(sawe_tree, "Combined", mode = "in"))
mpl <- Map(f = function(id) get_mass_props_and_unc(sawe_table, id), leaves)
combine_mass_props_unc(mpl, amp = get_mass_props(sawe_table, "Combined"))

Get mass properties for a row in a data frame

Description

get_mass_props() creates a mass properties list from a selected row in a data frame.

Usage

get_mass_props(df, id)

Arguments

df

A data frame with (at least) these columns: id, mass, Cx, Cy, Cz, Ixx, Iyy, Izz, Ixy, Ixz, Iyz, POIconv, Ipoint.

id

The id value of the desired row.

Value

A list with the following named elements:

mass Numeric mass.
center_mass Numeric 3-vector center of mass.
point Logical indicating point mass. The inertia of point masses is excluded from calculations.
inertia Numeric 3x3 matrix inertia tensor. The signs of the off-diagonal elements of the inertia tensor are determined by POIconv. For example, the xy element of the inertia tensor is Ixy if POIconv is "-"; it is -Ixy if POIconv is "+".

Examples

get_mass_props(mp_table, "C.1.2.2.3.1.2.3")

Get mass properties and uncertainties for a row in a data frame

Description

get_mass_props_and_unc() is a convenience wrapper that combines the results of get_mass_props() and get_mass_props_unc().

Usage

get_mass_props_and_unc(df, id)

Arguments

df

A data frame with (at least) these columns: id, mass, Cx, Cy, Cz, Ixx, Iyy, Izz, Ixy, Ixz, Iyz, POIconv, Ipoint, sigma_mass, sigma_Cx, sigma_Cy, sigma_Cz,sigma_Ixy, sigma_Ixz, sigma_Iyz.

id

The id value of the desired row.

Value

A list with the following named elements:

mass Numeric mass.
center_mass Numeric 3-vector center of mass.
point Logical indicating point mass. The inertia of point masses is excluded from calculations.
inertia Numeric 3x3 matrix inertia tensor. The signs of the off-diagonal elements of the inertia tensor are determined by POIconv. For example, the xy element of the inertia tensor is Ixy if POIconv is "-"; it is -Ixy if POIconv is "+".
sigma_mass Numeric mass uncertainty.
sigma_center_mass Numeric 3-vector center of mass uncertainties.
sigma_inertia Numeric 3x3 matrix inertia tensor uncertainties.

Examples

get_mass_props_and_unc(mp_table, "C.1.2.2.3.1.2.3")

Get mass properties and uncertainties and radii of gyration

Description

get_mass_props_and_unc_and_radii() creates a mass properties and uncertainties and radii of gyration list from a selected row in a data frame.

Usage

get_mass_props_and_unc_and_radii(df, id)

Arguments

df

id

The id value of the desired row.

Value

A list with the following named elements:

mass Numeric mass.
center_mass Numeric 3-vector center of mass.
point Logical indicating point mass. The inertia of point masses is excluded from calculations.
inertia Numeric 3x3 matrix inertia tensor. The signs of the off-diagonal elements of the inertia tensor are determined by POIconv. For example, the xy element of the inertia tensor is Ixy if POIconv is "-"; it is -Ixy if POIconv is "+".
sigma_mass Numeric mass uncertainty.
sigma_center_mass Numeric 3-vector center of mass uncertainties.
sigma_inertia Numeric 3x3 matrix inertia tensor uncertainties.
radii_gyration Numeric 3-vector radii of gyration.

Examples

mp_table_small_rollup <- rollup_mass_props_and_unc(mp_tree_small, mp_table_small)
radii_table_small <- add_radii_of_gyration(mp_table_small_rollup)
get_mass_props_and_unc_and_radii(radii_table_small, "C.1")

Get mass properties and uncertainties and radii of gyration and uncertainties

Description

get_mass_props_and_unc_and_radii_and_unc() creates a mass properties and uncertainties and radii of gyration and uncertainties list from a selected row in a data frame.

Usage

get_mass_props_and_unc_and_radii_and_unc(df, id)

Arguments

df

id

The id value of the desired row.

Value

A list with the following named elements:

mass Numeric mass.
center_mass Numeric 3-vector center of mass.
point Logical indicating point mass. The inertia of point masses is excluded from calculations.
inertia Numeric 3x3 matrix inertia tensor. The signs of the off-diagonal elements of the inertia tensor are determined by POIconv. For example, the xy element of the inertia tensor is Ixy if POIconv is "-"; it is -Ixy if POIconv is "+".
sigma_mass Numeric mass uncertainty.
sigma_center_mass Numeric 3-vector center of mass uncertainties.
sigma_inertia Numeric 3x3 matrix inertia tensor uncertainties.
radii_gyration Numeric 3-vector radii of gyration.
sigma_radii_gyration Numeric 3-vector radii of gyration uncertainties.

Examples

mp_table_small_rollup <- rollup_mass_props_and_unc(mp_tree_small, mp_table_small)
radii_and_unc_table <- rollup_radii_of_gyration_unc(
                          mp_tree_small, add_radii_of_gyration(mp_table_small_rollup))
get_mass_props_and_unc_and_radii_and_unc(radii_and_unc_table, "C.1")

Get mass properties uncertainties for a row in a data frame

Description

get_mass_props_unc() creates a mass properties uncertainties list from a selected row in a data frame.

Usage

get_mass_props_unc(df, id)

Arguments

df

A data frame with (at least) these columns: id, sigma_mass, sigma_Cx, sigma_Cy, sigma_Cz, sigma_Ixx, sigma_Iyy, sigma_Izz, sigma_Ixy, sigma_Ixz, sigma_Iyz.

id

The id value of the desired row.

Value

A list with the following named elements:

sigma_mass Numeric mass uncertainty.
sigma_center_mass Numeric 3-vector center of mass uncertainties.
sigma_inertia Numeric 3x3 matrix inertia tensor uncertainties.

Examples

get_mass_props_unc(mp_table, "C.1.2.2.3.1.2.3")

Example Mass Properties Table

Description

Example Mass Properties Table

Usage

mp_table

Format

A data frame with columns:

id: unique key
name: character name
POIconv: sign convention for products of inertia (one of c("+", "-"))
mass: mass
Cx: x-component of center of mass
Cy: y-component of center of mass
Cz: z-component of center of mass
Ixx: I_{xx} moment of inertia
Iyy: I_{yy} moment of inertia
Izz: I_{zz} moment of inertia
Ixy: I_{xy} product of inertia
Ixz: I_{xz} product of inertia
Iyz: I_{yz} product of inertia
Ipoint: logical indicator to consider item a point mass, i.e., with negligible inertia
sigma_mass: mass uncertainty
sigma_Cx: x-component of center of mass uncertainty
sigma_Cy: y-component of center of mass uncertainty
sigma_Cz: z-component of center of mass uncertainty
sigma_Ixx: I_{xx} moment of inertia uncertainty
sigma_Iyy: I_{yy} moment of inertia uncertainty
sigma_Izz: I_{zz} moment of inertia uncertainty
sigma_Ixy: I_{xy} product of inertia uncertainty
sigma_Ixz: I_{xz} product of inertia uncertainty
sigma_Iyz: I_{yz} product of inertia uncertainty

Example Small Mass Properties Table

Description

Example Small Mass Properties Table

Usage

mp_table_small

Format

A data frame with columns:

id: unique key
name: character name
POIconv: sign convention for products of inertia (one of c("+", "-"))
mass: mass
Cx: x-component of center of mass
Cy: y-component of center of mass
Cz: z-component of center of mass
Ixx: I_{xx} moment of inertia
Iyy: I_{yy} moment of inertia
Izz: I_{zz} moment of inertia
Ixy: I_{xy} product of inertia
Ixz: I_{xz} product of inertia
Iyz: I_{yz} product of inertia
Ipoint: logical indicator to consider item a point mass, i.e., with negligible inertia
sigma_mass: mass uncertainty
sigma_Cx: x-component of center of mass uncertainty
sigma_Cy: y-component of center of mass uncertainty
sigma_Cz: z-component of center of mass uncertainty
sigma_Ixx: I_{xx} moment of inertia uncertainty
sigma_Iyy: I_{yy} moment of inertia uncertainty
sigma_Izz: I_{zz} moment of inertia uncertainty
sigma_Ixy: I_{xy} product of inertia uncertainty
sigma_Ixz: I_{xz} product of inertia uncertainty
sigma_Iyz: I_{yz} product of inertia uncertainty

Example Mass Properties Tree

Description

Example Mass Properties Tree

Usage

mp_tree

Format

An 'igraph' tree whose vertices are named as the values of the id column of a mass properties table and whose directed edges point from child id to parent id.

Example Small Mass Properties Tree

Description

Example Small Mass Properties Tree

Usage

mp_tree_small

Format

An 'igraph' tree whose vertices are named as the values of the id column of a mass properties table and whose directed edges point from child id to parent id.

Roll up mass properties

Description

'rollup_mass_props()' rolls up mass properties in a data frame such that the mass properties of each non-leaf vertex element is the aggregation of those of its child elements.

Usage

rollup_mass_props(tree, df, validate_df = validate_mass_props_table, ...)

Arguments

tree

An 'igraph' tree whose vertices are named as the values of the id column of df and whose directed edges point from child id to parent id.

df

A data frame with (at least) these columns: id, mass, Cx, Cy, Cz, Ixx, Iyy, Izz, Ixy, Ixz, Iyz, POIconv, Ipoint.

validate_df

A validator for the tree and table, default validate_mass_props_table()

...

Other parameters passed to rollupTree::rollup()

Value

The updated data frame

Examples

rollup_mass_props(mp_tree_small, mp_table_small)

Roll up mass properties and uncertainties

Description

'rollup_mass_props_and_unc()' rolls up mass properties in a data frame with (at least) these columns: id, mass, Cx, Cy, Cz, Ixx, Iyy, Izz, Ixy, Ixz, Iyz, POIconv, Ipoint, sigma_mass, sigma_Cx, sigma_Cy, sigma_Cz, sigma_Ixx, sigma_Iyy, sigma_Izz, sigma_Ixy, sigma_Ixz, sigma_Iyz.

The difference between rollup_mass_props_unc() and rollup_mass_props_and_unc() is that rollup_mass_props_unc() expects the mass properties in its input to have been rolled up, whereas rollup_mass_props_and_unc() performs the mass properties rollup itself.

Usage

rollup_mass_props_and_unc(
  tree,
  df,
  validate_df = validate_mass_props_and_unc_table,
  ...
)

Arguments

tree

An 'igraph' tree whose vertices are named as the values of the id column of df and whose directed edges point from child id to parent id.

df

A data frame with (at least) these columns: id, mass, Cx, Cy, Cz, Ixx, Iyy, Izz, Ixy, Ixz, Iyz, POIconv, Ipoint.

validate_df

A validator for the tree and table, default validate_mass_props_and_unc_table()

...

Other parameters passed to rollupTree::rollup()

Value

The updated data frame

Examples

rollup_mass_props_and_unc(mp_tree_small, mp_table_small)

Roll up mass properties and uncertainties without input validation

Description

rollup_mass_props_and_unc_fast() performs the same operation as rollup_mass_props_and_unc() but omits input validation. It is somewhat faster than rollup_mass_props_and_unc() but should be used with caution and only under circumstances in which the caller assumes responsibility for validity of input. Its behavior when passed ill-formed input is unspecified.

Usage

rollup_mass_props_and_unc_fast(tree, df)

Arguments

tree

An 'igraph' tree whose vertices are named as the values of the id column of df and whose directed edges point from child id to parent id.

df

A data frame with (at least) these columns: id, mass, Cx, Cy, Cz, Ixx, Iyy, Izz, Ixy, Ixz, Iyz, POIconv, Ipoint.

Value

The updated data frame

Examples

rollup_mass_props_and_unc_fast(sawe_tree, sawe_table)

Roll up mass properties without input validation

Description

rollup_mass_props_fast() performs the same operation as rollup_mass_props() but omits input validation. It is somewhat faster than rollup_mass_props() but should be used with caution and only under circumstances in which the caller assumes responsibility for validity of input. Its behavior when passed ill-formed input is unspecified.

Usage

rollup_mass_props_fast(tree, df)

Arguments

tree

An 'igraph' tree whose vertices are named as the values of the id column of df and whose directed edges point from child id to parent id.

df

A data frame with (at least) these columns: id, mass, Cx, Cy, Cz, Ixx, Iyy, Izz, Ixy, Ixz, Iyz, POIconv, Ipoint.

Value

The updated data frame

Examples

rollup_mass_props_fast(test_tree, test_table)

Roll up mass properties uncertainties

Description

rollup_mass_props_unc() rolls up mass properties uncertainties in a data frame such that the uncertainties of each non-leaf vertex element is the aggregation of the mass properties and uncertainties of its child elements.

Usage

rollup_mass_props_unc(
  tree,
  df,
  validate_df = validate_mass_props_and_unc_table,
  ...
)

Arguments

tree

An 'igraph' tree whose vertices are named as the values of the id column of df and whose directed edges point from child id to parent id.

df

A data frame with (at least) these columns: id, mass, Cx, Cy, Cz, Ixx, Iyy, Izz, Ixy, Ixz, Iyz, POIconv, Ipoint.

validate_df

A validator for the tree and table, default validate_mass_props_and_unc_table()

...

Other parameters passed to rollupTree::rollup()

Value

The updated data frame

Examples

mp_ru <- rollup_mass_props(mp_tree_small, mp_table_small)
rollup_mass_props_unc(mp_tree_small, mp_ru)

Roll up mass properties uncertainties without input validation

Description

rollup_mass_props_unc_fast() performs the same operation as rollup_mass_props_unc() but omits input validation. It is somewhat faster than rollup_mass_props_unc() but should be used with caution and only under circumstances in which the caller assumes responsibility for validity of input. Its behavior when passed ill-formed input is unspecified.

Usage

rollup_mass_props_unc_fast(tree, df)

Arguments

tree

An 'igraph' tree whose vertices are named as the values of the id column of df and whose directed edges point from child id to parent id.

df

A data frame with (at least) these columns: id, mass, Cx, Cy, Cz, Ixx, Iyy, Izz, Ixy, Ixz, Iyz, POIconv, Ipoint.

Value

The updated data frame

Examples

rollup_mass_props_unc_fast(sawe_tree, sawe_table)

Roll up radii of gyration uncertainties

Description

rollup_radii_of_gyration_unc() adds calculated radii of gyration uncertainties to a data frame of rolled-up mass properties and uncertainties.

Radii of gyration uncertainties are calculated directly from moments of inertia and mass and their uncertainties; they are not recursively-defined. Radii of gyration uncertainties for composite elements depend on uncertainties of their component elements.

Usage

rollup_radii_of_gyration_unc(tree, df)

Arguments

tree

An 'igraph' tree whose vertices are named as the values of the id column of df and whose directed edges point from child id to parent id.

df

A data frame with (at least) these columns: id, mass, Cx, Cy, Cz, Ixx, Iyy, Izz, Ixy, Ixz, Iyz, POIconv, Ipoint.

Value

A data frame with the same columns as df, plus radii of gyration in columns sigma_kx, sigma_ky, and sigma_kz.'

Examples

sawe_table_rollup <- rollup_mass_props(sawe_tree, sawe_table)
rollup_radii_of_gyration_unc(sawe_tree, add_radii_of_gyration(sawe_table_rollup))

Mass Properties and Uncertainties Table from SAWE Paper No. 3360

Description

Mass Properties and Uncertainties Table from SAWE Paper No. 3360

Usage

sawe_table

Format

A data frame with columns:

id: unique key
mass: mass
Cx: x component of center of mass
Cy: y component of center of mass
Cz: z component of center of mass
Ixx: Ixx moment of inertia
Iyy: Iyy moment of inertia
Izz: Izz moment of inertia
Ixy: Ixy product of inertia
Ixz: Ixz product of inertia
Iyz: Iyz product of inertia
sigma_mass: mass uncertainty
sigma_Cx: x component of center of mass uncertainty
sigma_Cy: y component of center of mass uncertainty
sigma_Cz: z component of center of mass uncertainty
sigma_Ixx: Ixx moment of inertia uncertainty
sigma_Iyy: Iyy moment of inertia uncertainty
sigma_Izz: Izz moment of inertia uncertainty
sigma_Ixy: Ixy product of inertia uncertainty
sigma_Ixz: Ixz product of inertia uncertainty
sigma_Iyz: Iyz product of inertia uncertainty
Ipoint: logical indicator to consider item a point mass
POIconv: sign convention for products of inertia (one of c("+", "-"))

Source

Zimmerman, Robert L., and John H. Nakai. 2005. “Are You Sure? Uncertainty in Mass Properties Engineering.” In 64th Annual International Conference on Mass Properties Engineering, 123–60. Society of Allied Weight Engineers.

Note: the results for combined mass properties and uncertainties in the published example are accurate only within approximately 0.2%.

Mass Properties and Uncertainties Tree from SAWE Paper No. 3360

Description

Mass Properties and Uncertainties Tree from SAWE Paper No. 3360

Usage

sawe_tree

Format

An igraph tree with edges from child id to parent id.

Source

Set mass properties for a row in a data frame

Description

set_mass_props() sets mass properties for a specified row in a data frame.

Usage

set_mass_props(df, id, mp)

Arguments

df

A data frame with an id column.

id

The id value of the desired row.

mp

A list with the following named elements:

mass Numeric mass.
center_mass Numeric 3-vector center of mass.
point Logical indicating point mass. The inertia of point masses is excluded from calculations.
poi_conv Enumeration c("+", "-") indicating sign convention for products of inertia.
inertia Numeric 3x3 matrix inertia tensor. The signs of the products of inertia are determined by POIconv. For example, Ixy is the xy element of the inertia tensor if POIconv is "-"; it is the additive inverse of that value if POIconv is "+".

Value

The updated data frame with columns id, mass, Cx, Cy, Cz, Ixx, Iyy, Izz, Ixy, Ixz, Iyz, POIconv, Ipoint.

Examples

df <- data.frame(id = c("C.1.2.2.3.1.2.3", "C.1.2.2.3.2.1.1"))
mp <- get_mass_props(mp_table, "C.1.2.2.3.2.1.1")
mp$poi_conv = "+"
set_mass_props(df, "C.1.2.2.3.2.1.1", mp)

Set mass properties and uncertainties for a row in a data frame

Description

set_mass_props_and_unc() is a convenience wrapper that combines the results of set_mass_props() and set_mass_props_unc().

Usage

set_mass_props_and_unc(df, id, mpu)

Arguments

df

A data frame with an id column.

id

The id value of the desired row.

mpu

A list containing the following named elements:

mass Numeric mass.
center_mass Numeric 3-vector center of mass.
point Logical indicating point mass. The inertia of point masses is excluded from calculations.
poi_conv Enumeration c("+", "-") indicating sign convention for products of inertia.
inertia Numeric 3x3 matrix inertia tensor. The signs of the products of inertia are determined by POIconv. For example, Ixy is the xy element of the inertia tensor if POIconv is "-"; it is the additive inverse of that value if POIconv is "+".
sigma_mass Numeric mass uncertainty.
sigma_center_mass Numeric 3-vector center of mass uncertainties.
sigma_inertia Numeric 3x3 matrix inertia tensor uncertainties.

Value

The updated data frame.

Examples

mpu <- c(get_mass_props_and_unc(sawe_table, "Widget"), poi_conv = "+")
set_mass_props_and_unc(sawe_table, "Combined", mpu)

Set mass properties uncertainties for a row in a data frame

Description

set_mass_props_unc() sets mass properties uncertainties for a selected row in a data frame with an id column.

Usage

set_mass_props_unc(df, id, mpu)

Arguments

df

A data frame with an id column.

id

The id value of the desired row.

mpu

A list with the following named elements:

sigma_mass Numeric mass uncertainty.
sigma_center_mass Numeric 3-vector center of mass uncertainties.
sigma_inertia Numeric 3x3 matrix inertia tensor uncertainties.

Value

The updated data frame.

Examples

set_mass_props_unc(sawe_table, "Combined", get_mass_props_unc(sawe_table, "Widget"))

Set POI convention for mass properties list to match a target item

Description

set_poi_conv_from_target() sets the products of inertia sign convention for a mass properties list to that of a target item in a mass properties table. This convention determines how products of inertia are saved to the data frame.

The signature ⁠of set_poi_conv_from_target()⁠ is such that it can be passed as an override argument to update_mass_props() and update_mass_props_and_unc(), thus ensuring that all calculated POI values follow the negative integral convention of the target item to which they are written.

Usage

set_poi_conv_from_target(df, target, mp)

Arguments

df

A data frame with columns id and POIconv.

target

The id value of the target row.

mp

A mass properties list.

Value

The mass properties list with the named element poi_conv set to the POIconv column of the target row in the data frame.

Examples

set_poi_conv_from_target(mp_table, "C.1.2.2.3.2.1", get_mass_props(mp_table, "C.1.2.2.3.2.1.1"))

Set POI sign convention for mass properties list to "-"

Description

set_poi_conv_minus() sets the products of inertia sign convention for a mass properties list to "-". This convention determines how products of inertia are saved to a data set.

The signature of set_poi_conv_minus() is such that it can be passed as an override argument to update_mass_props() and update_mass_props_and_unc(), thus ensuring that calculated POI values are saved using the negative integral convention.

Usage

set_poi_conv_minus(ds, target, mp)

Arguments

ds

Ignored.

target

Ignored.

mp

A mass properties list.

Value

The mass properties list with the named element poi_conv set to "-"

Examples

set_poi_conv_minus(NULL, NULL, get_mass_props(mp_table, "C.1.2.2.3.2.1.1"))

Set POI sign convention for mass properties list to "+"

Description

set_poi_conv_plus() sets the products of inertia sign convention for a mass properties list to "+". This convention determines how products of inertia are saved to a data set.

The signature of set_poi_conv_plus() is such that it can be passed as an override argument to update_mass_props() and update_mass_props_and_unc(), thus ensuring that calculated POI values are saved using the positive integral convention.

Usage

set_poi_conv_plus(ds, target, mp)

Arguments

ds

Ignored.

target

Ignored.

mp

A mass properties list.

Value

The input mass properties list with the named element poi_conv set to "+"

Examples

set_poi_conv_plus(NULL, NULL, get_mass_props(mp_table, "C.1.2.2.3.2.1.1"))

Set radii of gyration for a row in a data frame

Description

set_radii_of_gyration() sets radii of gyration for a selected row in a data frame with an id column.

Usage

set_radii_of_gyration(df, id, rg)

Arguments

df

A data frame with an id column.

id

The id value of the desired row.

rg

A list with the following named elements:

radii_gyration Numeric 3x3 matrix radii of gyration.

Value

The updated data frame.

Examples

rgl <- list(radii_gyration = c(x = 1, y = 2, z = 3))
set_radii_of_gyration(mp_table, "C.1", rgl)[1:5, ]

Set radii of gyration uncertainties for a row in a data frame

Description

set_radii_of_gyration_unc() sets radii of gyration uncertainties for a selected row in a data frame with an id column.

Usage

set_radii_of_gyration_unc(df, id, rgu)

Arguments

df

A data frame with an id column.

id

The id value of the desired row.

rgu

A list with the following named elements:

sigma_radii_gyration Numeric 3x3 matrix radii of gyration uncertainties.

Value

The updated data frame.

Examples

rgul <- list(sigma_radii_gyration = c(x = 1, y = 2, z = 3))
set_radii_of_gyration_unc(mp_table, "C.1", rgul)[1:5, ]

Example Mass Properties Table

Description

Example Mass Properties Table

Usage

test_table

Format

A data frame with columns:

id: unique key
parent: parent key
mass: mass
Cx: x component of center of mass
Cy: y component of center of mass
Cz: z component of center of mass
Ixx: Ixx moment of inertia
Iyy: Iyy moment of inertia
Izz: Izz moment of inertia
Ixy: Ixy product of inertia
Ixz: Ixz product of inertia
Iyz: Iyz product of inertia
POIconv: sign convention for products of inertia (one of c("+", "-"))
Ipoint: logical indicator to consider item a point mass

Example Mass Properties Tree

Description

Example Mass Properties Tree

Usage

test_tree

Format

An igraph tree with edges from child id to parent id.

Example Mass Properties and Uncertainties Table

Description

Example Mass Properties and Uncertainties Table

Usage

test_unc_table

Format

A data frame with columns:

id: unique key
parent: parent key
mass: mass
Cx: x component of center of mass
Cy: y component of center of mass
Cz: z component of center of mass
Ixx: Ixx moment of inertia
Iyy: Iyy moment of inertia
Izz: Izz moment of inertia
Ixy: Ixy product of inertia
Ixz: Ixz product of inertia
Iyz: Iyz product of inertia
POIconv: sign convention for products of inertia (one of c("+", "-"))
Ipoint: logical indicator to consider item a point mass
sigma_mass: mass uncertainty
sigma_Cx: x component of center of mass uncertainty
sigma_Cy: y component of center of mass uncertainty
sigma_Cz: z component of center of mass uncertainty
sigma_Ixx: Ixx moment of inertia uncertainty
sigma_Iyy: Iyy moment of inertia uncertainty
sigma_Izz: Izz moment of inertia uncertainty
sigma_Ixy: Ixy product of inertia uncertainty
sigma_Ixz: Ixz product of inertia uncertainty
sigma_Iyz: Iyz product of inertia uncertainty

Update mass properties

Description

update_mass_props() updates mass properties for a specified target row from specified source rows in a data frame.

Usage

update_mass_props(df, target, sources, override = set_poi_conv_from_target)

Arguments

df

A data frame with (at least) these columns: id, mass, Cx, Cy, Cz, Ixx, Iyy, Izz, Ixy, Ixz, Iyz, POIconv, Ipoint.

target

The id value of the target row.

sources

List of id values of the of the source rows.

override

An override function, called as override(df, target, value). The default override sets the POI sign convention of a computed aggregate to the POIconv column of the target row in the data frame.

Value

The updated data frame.

Examples

leaves <- names(igraph::neighbors(test_tree, "A.3", mode = "in"))
update_mass_props(test_table, "A.3", leaves)

Update mass properties and uncertainties

Description

update_mass_props_and_unc() updates mass properties and uncertainties for a specified target row from specified source rows in a data frame.

Usage

update_mass_props_and_unc(
  df,
  target,
  sources,
  override = set_poi_conv_from_target
)

Arguments

df

target

The id value of the target row.

sources

List of id values of the of the source rows.

override

An override function, called as override(df, target, value). The default override sets the POI sign convention of a computed aggregate to the POIconv column of the target row in the data frame.

Value

The updated data frame.

Examples

leaves <- list("Widget", "2nd Part")
update_mass_props_and_unc(sawe_table, "Combined", leaves)

Update mass properties uncertainties

Description

update_mass_props_unc() updates mass properties uncertainties for a specified target row from specified source rows in a data frame with (at least) these columns: id, sigma_mass, sigma_Cx, sigma_Cy, sigma_Cz, sigma_Ixx, sigma_Iyy, sigma_Izz, sigma_Ixy, sigma_Ixz, sigma_Iyz.

Usage

update_mass_props_unc(df, target, sources, override = set_poi_conv_from_target)

Arguments

df

target

The id value of the target row.

sources

List of id values of the of the source rows.

override

An override function, called as override(df, target, value). The default override sets the POI sign convention of a computed aggregate to the POIconv column of the target row in the data frame.

Value

The updated data frame.

Examples

leaves <- names(igraph::neighbors(sawe_tree, "Combined", mode = "in"))
update_mass_props_unc(sawe_table, "Combined", leaves)

Validate mass properties

Description

validate_mass_props() ensures that a mass properties list satisfies the following constraints:

mass is non-missing and positive
center_mass is a 3-vector of non-missing numeric values
point is TRUE or FALSE
if point is FALSE:
- inertia is positive definite
- eigenvalues \{\lambda_1, \lambda_2, \lambda_3\} of inertia satisfy the triangle inequalities:
  - \lambda_1 < \lambda_2 + \lambda_3
  - \lambda_2 < \lambda_1 + \lambda_3
  - \lambda_3 < \lambda_1 + \lambda_2

Usage

validate_mass_props(mp)

Arguments

mp

Mass properties list containing the following named elements

mass Numeric mass.
center_mass Numeric 3-vector center of mass.
point Logical indicating point mass. The inertia of point masses is excluded from calculations.
inertia Numeric 3x3 matrix inertia tensor.

Value

TRUE if valid, stops otherwise

Examples

mp <- get_mass_props(test_table, "C.1")
validate_mass_props(mp)

Validate mass properties and uncertainties

Description

validate_mass_props_and_unc() is a convenience wrapper that calculates the logical conjunction of validate_mass_props() and validate_mass_props_unc().

Usage

validate_mass_props_and_unc(mpu)

Arguments

mpu

Mass properties and uncertainties list containing the following named elements

mass mass (numeric)
center_mass center of mass (3-dimensional numeric)
inertia Inertia tensor (3x3 numeric matrix)
point Logical indicating point mass, i.e., negligible inertia
sigma_mass mass uncertainty
sigma_center_mass center of mass uncertainty (3-dimensional numeric)
sigma_inertia Inertia tensor uncertainty (3x3 numeric matrix)

Value

TRUE if valid, stops otherwise

Examples

mpu <- get_mass_props_and_unc(sawe_table, "Widget")
validate_mass_props_and_unc(mpu)

Validate a mass properties and uncertainties table

Description

validate_mass_props_and_unc() calls validate_mass_props_table() and further applies the checks of validate_mass_props_and_unc() to every row of the data frame corresponding to a leaf vertex of the tree.

Usage

validate_mass_props_and_unc_table(tree, df)

Arguments

tree

An 'igraph' tree whose vertices are named as the values of the id column of df and whose directed edges point from child id to parent id.

df

Value

TRUE if valid, stops with an error otherwise

Examples

validate_mass_props_and_unc_table(mp_tree_small, mp_table_small)

Validate a mass properties table

Description

validate_mass_props_table() checks that the names of vertices in a tree and the id values of a data frame are identical. It further applies the checks of validate_mass_props() to every row of the data frame corresponding to a leaf vertex of the tree.

validate_mass_props_table() ensures that the id column of the table and the vertices of the tree contain the same identifiers, and that the mass properties of every leaf element of the table are valid.

Usage

validate_mass_props_table(tree, df)

Arguments

tree

An 'igraph' tree whose vertices are named as the values of the id column of df and whose directed edges point from child id to parent id.

df

A data frame with (at least) these columns: id, mass, Cx, Cy, Cz, Ixx, Iyy, Izz, Ixy, Ixz, Iyz, POIconv, Ipoint.

Value

TRUE if valid, stops with an error otherwise

Examples

validate_mass_props_table(mp_tree_small, mp_table_small)

Validate mass properties uncertainties

Description

validate_mass_props_unc() ensures that a mass properties and uncertainties list satisfies the following constraints:

sigma_mass is non-missing and non-negative
sigma_center_mass is a 3-vector of non-missing non-negative values
if point is FALSE, the sigma_inertia contains no missing or negative values

Usage

validate_mass_props_unc(mp)

Arguments

mp

Mass properties and uncertainties list containing the following named elements

point Logical indicating point mass, i.e., negligible inertia
sigma_mass mass uncertainty
sigma_center_mass center of mass uncertainty (3-dimensional numeric)
sigma_inertia Inertia tensor uncertainty (3x3 numeric matrix)

Value

TRUE if valid, stops otherwise

Examples

mp <- get_mass_props_and_unc(sawe_table, "Widget")
validate_mass_props_unc(mp)

massProps: Calculate Mass Properties and Uncertainties of Tree Structures

Description

Author(s)

See Also

Add radii of gyration

Description

Usage

Arguments

Value

Examples

Combine mass properties

Description

Usage

Arguments

Details

Value

Examples

Combine mass properties and uncertainties

Description

Usage

Arguments

Value

Examples

Combine mass properties uncertainties

Description

Usage

Arguments

Details

Value

Examples

Get mass properties for a row in a data frame

Description

Usage

Arguments

Value

Examples

Get mass properties and uncertainties for a row in a data frame

Description

Usage

Arguments

Value

Examples

Get mass properties and uncertainties and radii of gyration

Description

Usage

Arguments

Value

Examples

Get mass properties and uncertainties and radii of gyration and uncertainties

Description

Usage

Arguments

Value

Examples

Get mass properties uncertainties for a row in a data frame

Description

Usage

Arguments

Value

Examples

Example Mass Properties Table

Description

Usage

Format

Example Small Mass Properties Table

Description

Usage

Format

Example Mass Properties Tree

Description

Usage

Format

Example Small Mass Properties Tree

Description

Usage

Format

Roll up mass properties

Description

Usage

Arguments