Merge branch 'dev'

R/ace-estimate.R

@@ -9,7 +9,7 @@
 #' @note The contents of the `Details` list depends on the underlying
 #' estimation routine.  For example, when the ACE model is estimated with a DF
 #' analysis, the output is an [stats::lm()] object, because the [stats::lm()] function
-#' was used (ie, the basic general linear model).  Alternatively, if the
+#' was used (i.e., the basic general linear model).  Alternatively, if the
 #' user specified the [lavaan::lavaan()] package should estimate that ACE model,
 #' the output is a [lavaan::lavaan()] object.
 #'

R/ace-lavaan-group.R

@@ -111,7 +111,9 @@ AceLavaanGroup <-
     c2 := c * c                           #Declare c^2 for easy point and variance estimation.
   ")
 
-    # If the A/C component's excluded: (1) overwrite the code and (2) declare a2/c2, so the parameter value can be retrieved later without if statements.
+    # If the A/C component's excluded: 
+    # (1) overwrite the code and (2) declare a2/c2, 
+    # so the parameter value can be retrieved later without if statements.
     if (!estimateA) modelA <- "\n a2 := 0 \n"
     if (!estimateC) modelC <- "\n c2 := 0 \n"
 
@@ -146,8 +148,9 @@ AceLavaanGroup <-
     #   layer(geom="line") + layer(geom="text") + scale_x_reverse(limits=c(1,0))
 
     components <- base::as.numeric(base::cbind(a2, c2, e2)[1, ] / (a2 + c2 + e2)) # The 'as.numeric' gets rid of the vector labels.
-    if (printOutput) base::print(components) # Print the unity-SCALED ace components.
-    caseCount <- base::nrow(dsClean)
+    # Print the unity-SCALED ace components.
+    if (printOutput) base::print(components)
+        caseCount <- base::nrow(dsClean)
     details <- base::list(lavaan = fit)
     # print(paste("R Levels excluded:",  stringr::str_c(rLevelsToExclude, collapse=", "), "; R Levels retained:", rString)) #Print the dropped & retained groups.
     ace <- NlsyLinks::CreateAceEstimate(

R/validate-pair-links-are-symmetric.R

@@ -1,25 +1,22 @@
 #' @name ValidatePairLinksAreSymmetric
 #'
 #' @export
-#'
 #' @title Verifies that the pair relationships are symmetric.
+#' @description Validates that the `linksPair` data frame is symmetric.
+#' In a symmetric `linksPair`, each row has a corresponding row with reversed SubjectTag_S1 and SubjectTag_S2,
+#' but the same `R` value.
+#' For certain analyses (like types of DF methods and some
+#' spatially-inspired methods), the pairs links (which can be considered a type of
+#' sparse matrix) need to be symmetric. For example, if Subject 201 is related to
+#' Subject 202 with a value of `R=0.5`, then there must be
+#' a reciprocal row where Subject 202 is related to Subject 201 with `R=0.5`.
 #'
-#' @description For certain analyses, the pairs links (which can be considered a type of
-#' sparse matrix) need to be symmetric. For instance, if there is a row for
-#' Subjects 201 and 202 with `R`=0.5, there should be a second row for
-#' Subjects 202 and 201 with `R`=0.5.
-#'
-#' This validation function is useful to some types of DF methods and some
-#' spatially-inspired methods.
-#'
-#' @param linksPair The [base::data.frame] object that should be symmetric
 #'
+#' @param linksPair A [base::data.frame] containing the pair relationships that should be symmetric
 #' @return Returns `TRUE` if symmetric.  Throw an error with [base::stop()] if asymmetric.
 #'
-#' @author Will Beasley
-#'
 #' @seealso [CreatePairLinksDoubleEntered()]
-#'
+#' @author Will Beasley
 #' @keywords validation
 #'
 #' @examples
@@ -45,22 +42,28 @@
 #' summary(dsDouble) # Summarize the variables
 #'
 #' ValidatePairLinksAreSymmetric(dsDouble) # Should return TRUE.
+#'
 ValidatePairLinksAreSymmetric <- function(linksPair) {
+  # Preliminary validation of the linksPair data frame
   ValidatePairLinks(linksPair)
+
+  # Loop through each row to validate symmetry
   for (rowIndex in base::seq_len(base::nrow(linksPair))) {
+    # Extract the 'R' value for the current row
     r <- linksPair$R[rowIndex]
-    # tag1          <- linksPair$SubjectTag_S1[rowIndex]
-    # tag2          <- linksPair$SubjectTag_S2[rowIndex]
-    # r             <- linksPair$R[rowIndex]
-    # path          <- linksPair$RelationshipPath[rowIndex]
 
+    # Proceed only if 'R' is not NA
     if (!is.na(r)) {
+      # Extract other fields for the current row
       tag1 <- linksPair$SubjectTag_S1[rowIndex]
       tag2 <- linksPair$SubjectTag_S2[rowIndex]
       path <- linksPair$RelationshipPath[rowIndex]
 
-      # oppositeCount <- base::nrow(subset(linksPair, SubjectTag_S1==tag2 & SubjectTag_S2==tag1 & R==r & RelationshipPath==path))
+      # Check if an opposite pair exists with the same 'R' value
       oppositeCount <- base::nrow(linksPair[linksPair$SubjectTag_S1 == tag2 & linksPair$SubjectTag_S2 == tag1 & linksPair$R == r & linksPair$RelationshipPath == path, ])
+      # oppositeCount <- base::nrow(subset(linksPair, SubjectTag_S1==tag2 & SubjectTag_S2==tag1 & R==r & RelationshipPath==path))
+
+      # If opposite pair doesn't exist or exists more than once, throw an error
       if (oppositeCount != 1) {
         base::stop(paste0(
           "The 'linksPair' dataset doesn't appear to be double-entered & symmetric.  The reciprocal of (SubjectTag_S1, SubjectTag_S2, R)=(",
@@ -69,5 +72,6 @@ ValidatePairLinksAreSymmetric <- function(linksPair) {
       }
     }
   }
+  # Return TRUE if all pairs are symmetric
   return(TRUE)
 }

vignettes/articles/compile_joss.R

@@ -0,0 +1,11 @@
+compile_joss <- function(...) {
+  message("Rendering rmarkdown document...")
+
+  rmarkdown::render('E:/Dropbox/Lab/Research/Projects/2023/NlsyLinks/vignettes/articles/paper.Rmd',
+                    encoding = 'UTF-8',
+                    knit_root_dir = '~/R')
+
+  message("Done rendering!")
+}
+
+compile_joss()

vignettes/articles/paper.Rmd

@@ -70,13 +70,14 @@ Acknowledgment of any financial support.
 # Summary
 
 <!--  A summary describing the high-level functionality and purpose of the software for a diverse, non-specialist audience. -->
-
+NlsyLinks is an R package designed to facilitate behavior genetics research by providing comprehensive tools for managing and analyzing kinship information derived from the National Longitudinal Survey of Youth (NLSY). This package simplifies the complex processes of linking family members within the NLSY datasets and preparing the data for genetic and environmental influence analysis. By offering both structural and topical dataset management, NlsyLinks enables researchers to focus on hypotheses testing across various domains, including genetic contributions to behaviors and traits.
 
 
 
 # Statement of need
 <!-- A Statement of need section that clearly illustrates the research purpose of the software and places it in the context of related work. -->
 
+Behavior genetics research often grapples with the challenge of accurately identifying and analyzing kinship relationships within large, longitudinal datasets. The NLSY, with its extensive data on families across multiple generations, is a valuable resource for such research but requires sophisticated tools to manage and analyze effectively. NlsyLinks addresses this need by providing tailored functionalities for the NLSY data, including the handling of ambiguous kinship categories and the facilitation of complex genetic model estimations, such as ACE models. These capabilities are crucial for advancing research in behavior genetics, where understanding the genetic and environmental factors influencing traits is paramount.
 
 ## Features