High-Precision Multi-Trait Cause-and-Effect Path Coefficient Analysis Engine

The `compute_path_analysis` function executes phenotypic and genotypic path coefficient analysis based on the classic standard methodology of Dewey and Lu (1959). It partitions correlation coefficients between causal developmental traits and a target response variable into direct influence coefficients and indirect pathways acting through interconnected traits.

Usage

compute_path_analysis(
  correlation_payload,
  response_trait,
  predictor_traits = NULL,
  reporting_level = 2
)

Arguments

correlation_payload: A structured list generated by compute_correlation containing genotypic_correlation and/or phenotypic_correlation matrices, or a single matrix.
response_trait: A single character string specifying the target dependent trait column name.
predictor_traits: A character vector identifying the causal predictor traits. If NULL, all remaining numeric traits except non-agronomic design factors and response_trait are automatically selected.
reporting_level: An integer flag defining console output verbosity: 0 for silent execution, 1 for path decomposition summary, and 2 for detailed separate component tables. Defaults to 2.

Value

A structured named list containing path partition analyses for available correlation levels (Genotypic and/or Phenotypic):

direct_effects: Numeric vector storing standardized direct path coefficients ($\beta$).
indirect_effects_matrix: Data frame capturing inter-trait indirect path components alongside total correlation.
total_correlation_vector: Original correlation alignment vector with the target response trait.
residual_effect: Unexplained model residual variation ($R_X$).
r_squared: Total variance explained by causal predictors ($R^2$).
predictors: Character vector of causal predictor traits included in the pathway model.

Details

Path coefficient analysis provides a matrix-based decomposition of direct and indirect components. For a target response variable, let $R$ denote the correlation matrix among causal predictor traits, and $r$ denote the vector of correlations between predictors and the response variable. Standardized direct path coefficients ($\beta$) are calculated via matrix inversion: $$\beta = R^{-1} r$$ Indirect effects are cross-products between inter-trait correlations and direct path coefficients. The unexplained residual effect ($R_X$) is derived as: $$R_X = \sqrt{1 - \sum (\beta_i \times r_i)}$$

Examples

# \donttest{
   # Compute multi-level correlation matrices
   corr_payload <- compute_correlation(data = gv_data, reporting_level = 0)
   
   # Define all 6 causal predictor traits driving Grain Yield per Meter
   all_predictors <- c("PH", "SL", "PL", "NOT", "NOSS", "TGW")
   
   # Run path coefficient analysis across all causal traits with full report
   path_out <- compute_path_analysis(
     correlation_payload = corr_payload, 
     response_trait = "GYPM",
     predictor_traits = all_predictors,
     reporting_level = 2
   )
#> 
#> ==========================================================================================
#>            AGRIDATATOOLS: GENOTYPIC & PHENOTYPIC PATH ANALYSIS REPORT
#>            Target Response Trait (Effect): GYPM
#> ==========================================================================================
#> 
#> ------------------------------------------------------------------------------------------
#>  TABLE: GENOTYPIC PATH COEFFICIENTS MATRIX
#> ------------------------------------------------------------------------------------------
#>            PH       SL       PL      NOT     NOSS      TGW Total_Correlation
#> PH    0.54818  0.00161 -0.03603 -0.00909  0.01345  0.02169           0.53981
#> SL   -0.02820 -0.03133  0.00360  0.01896  0.13060  0.03383           0.12746
#> PL    0.23840  0.00136 -0.08285 -0.00504  0.01644  0.03086           0.19916
#> NOT  -0.05726 -0.00682  0.00480  0.08705  0.05918 -0.04388           0.04307
#> NOSS  0.01614 -0.00896 -0.00298  0.01128  0.45665 -0.00747           0.46466
#> TGW   0.08998 -0.00802 -0.01935 -0.02891 -0.02580  0.13215           0.14005
#> 
#>  [ DIRECT EFFECTS (Diagonal Values) ]:
#>       PH       SL       PL      NOT     NOSS      TGW 
#>  0.54818 -0.03133 -0.08285  0.08705  0.45665  0.13215 
#> 
#>  Model Statistics:
#>   * R-Squared Explained (R^2) : 0.50986
#>   * Residual Effect (Rx)       : 0.7001
#> ------------------------------------------------------------------------------------------
#> 
#> ------------------------------------------------------------------------------------------
#>  TABLE: PHENOTYPIC PATH COEFFICIENTS MATRIX
#> ------------------------------------------------------------------------------------------
#>            PH       SL       PL      NOT     NOSS      TGW Total_Correlation
#> PH    0.51150 -0.00031 -0.02612 -0.00646  0.01655  0.01695           0.51210
#> SL   -0.03359  0.00479  0.00328  0.01305  0.09895  0.02339           0.10986
#> PL    0.21836 -0.00026 -0.06118 -0.00408  0.01595  0.02317           0.19196
#> NOT  -0.04970  0.00094  0.00376  0.06645  0.04968 -0.03262           0.03851
#> NOSS  0.01937  0.00108 -0.00223  0.00756  0.43684 -0.00659           0.45604
#> TGW   0.07836  0.00101 -0.01281 -0.01959 -0.02602  0.11062           0.13157
#> 
#>  [ DIRECT EFFECTS (Diagonal Values) ]:
#>       PH       SL       PL      NOT     NOSS      TGW 
#>  0.51150  0.00479 -0.06118  0.06645  0.43684  0.11062 
#> 
#>  Model Statistics:
#>   * R-Squared Explained (R^2) : 0.46705
#>   * Residual Effect (Rx)       : 0.73003
#> ------------------------------------------------------------------------------------------
# }