/// <summary>
/// Analyzes the principal components of data
/// in which individuals and variables have been assigned
/// the specified weights and coefficients, respectively.
/// </summary>
/// <remarks>
/// Rows of the data matrix correspond to individuals, columns to variables.
/// Each row is interpreted as the coordinates of a multidimensional point
/// with respect to a <see cref="Basis">basis</see> whose vectors are defined as follows:
/// the square root of the weight of the <i>j</i>-th variable is multiplied
/// by the <i>j</i>-th
/// unit vector of the same dimension, and the result is included as
/// a basis vector.
/// </remarks>
/// <param name="data">The data to analyze.</param>
/// <param name="individualWeights">The individual weights.</param>
/// <param name="variableCoefficients">The variable coefficients.</param>
/// <returns>
/// The Principal Components of the specified data.
/// </returns>
/// <exception cref="ArgumentNullException">
/// <paramref name="data"/> is <b>null</b>.<br/>
/// -or-<br/>
/// <paramref name="individualWeights"/> is <b>null</b>.<br/>
/// -or-<br/>
/// <paramref name="variableCoefficients"/> is <b>null</b>.
/// </exception>
/// <exception cref="ArgumentOutOfRangeException">
/// <paramref name="individualWeights"/> is not a column vector.<br/>
/// -or-<br/>
/// <paramref name="variableCoefficients"/> is not a row vector.<br/>
/// -or-<br/>
/// The <see cref="DoubleMatrix.
/// Count"/> of <paramref name="individualWeights"/> is not equal
/// to the number of rows
/// of <paramref name="data"/>.<br/>
/// -or-<br/>
/// The <see cref="DoubleMatrix.Count"/> of
/// <paramref name="variableCoefficients"/> is not equal
/// to the number of columns
/// of <paramref name="data"/>.<br/>
/// -or-<br/>
/// <paramref name="individualWeights"/> entries do not sum up to 1.<br/>
/// -or-<br/>
/// Any entry of <paramref name="individualWeights"/> is negative.<br/>
/// -or-<br/>
/// Any entry of <paramref name="variableCoefficients"/> is not positive.
/// </exception>
/// <exception cref="InvalidOperationException">
/// The Singular Value Decomposition needed to acquire
/// the principal components cannot be executed or does not converge.<br/>
/// -or-<br/>
/// No principal component has positive variance.
/// The principal information cannot be acquired.
/// </exception>
public static PrincipalComponents Analyze(DoubleMatrix data,
DoubleMatrix individualWeights, DoubleMatrix variableCoefficients)
{
if (data is null)
{
throw new ArgumentNullException(nameof(data));
}
PrincipalComponents.ValidateIndividualWeights(data, individualWeights);
PrincipalComponents.ValidateVariableCoefficients(data, variableCoefficients);
return(InternalAnalyze(data, individualWeights, variableCoefficients));
}
private static PrincipalComponents InternalAnalyze(
DoubleMatrix data,
DoubleMatrix individualWeights,
DoubleMatrix variableCoefficients)
{
var basisMatrix = DoubleMatrix.Diagonal(
variableCoefficients.Apply((x) => Math.Sqrt(x)));
var cloud = new Cloud(data, individualWeights, new Basis(basisMatrix));
var principalComponents = new PrincipalComponents(cloud);
return(principalComponents);
}
/// <summary>
/// Analyzes the principal components of data
/// in which individuals have received the specified weights.
/// </summary>
/// <remarks>
/// Rows of the data matrix correspond to individuals, columns to variables.
/// Each row is interpreted as the coordinates of a multidimensional point
/// with respect to the <see cref="Basis.Standard">standard</see> basis.
/// </remarks>
/// <param name="data">The data to analyze.</param>
/// <param name="individualWeights">The individual weights.</param>
/// <returns>The Principal Components of the specified data.</returns>
/// <exception cref="ArgumentNullException">
/// <paramref name="data"/> is <b>null</b>.<br/>
/// -or-<br/>
/// <paramref name="individualWeights"/> is <b>null</b>.
/// </exception>
/// <exception cref="ArgumentOutOfRangeException">
/// <paramref name="individualWeights"/> is not a column vector.<br/>
/// -or-<br/>
/// The <see cref="DoubleMatrix.
/// Count"/> of <paramref name="individualWeights"/> is not equal
/// to the number of rows
/// of <paramref name="data"/>.<br/>
/// -or-<br/>
/// <paramref name="individualWeights"/> entries do not sum up to 1.<br/>
/// -or-<br/>
/// Any entry of <paramref name="individualWeights"/> is negative.
/// </exception>
/// <exception cref="InvalidOperationException">
/// The Singular Value Decomposition needed to acquire
/// the principal components cannot be executed or does not converge.<br/>
/// -or-<br/>
/// No principal component has positive variance.
/// The principal information cannot be acquired.
/// </exception>
public static PrincipalComponents Analyze(
DoubleMatrix data,
DoubleMatrix individualWeights)
{
#region Input validation
if (data is null)
{
throw new ArgumentNullException(nameof(data));
}
PrincipalComponents.ValidateIndividualWeights(data, individualWeights);
#endregion
DoubleMatrix variableCoefficients =
DoubleMatrix.Dense(1, data.NumberOfColumns, 1.0);
return(InternalAnalyze(data, individualWeights, variableCoefficients));
}
