quick tidy up

DESCRIPTION

@@ -2,19 +2,20 @@ Package: npiv
 Type: Package
 Title: Kinematics and hydrodynamics analysis on nauplii
 Version: 0.0.1
-Date: 2018-11-08
+Date: 2018-12-06
 Authors@R: c(person("Jin Yung", "Wong", 
           email = "wongjinyung@gmail.com", role = c("aut", "cre")),
   person("Benny K. K.", "Chan", email = "chankk@gate.sinica.edu.tw", 
           role = "ths"), 
   person("K. Y. Karen", "Chan", email = "karenchan@ust.hk", role = "ths"))
 Maintainer: Wong Jin Yung <wongjinyung@gmail.com>
-Description: R package for analyses of high speed video/ 
-  particle image velocimetry data of swimming nauplii
+Description: R package for analyses of high speed video or particle image 
+  velocimetry data of swimming nauplii.
+License: GPL(>= 2)
 Depends:
     R(>= 3.0.0)
 LazyLoad: yes
 URL: https://github.com/jinyung/npiv
-Imports: reticulate, signal
+Imports: reticulate, signal, fields, shape
 Suggests: knitr, rmarkdown
 VignetteBuilder: knitr

NAMESPACE

@@ -1 +1,5 @@
-exportPattern("^[^\\.]")
+exportPattern("^[^\\.]")
+
+import(fields)
+import(shape)
+import(signal)

R/ang_sep.R

@@ -1,57 +1,3 @@
-# assume id of tps file as number and the difference between id represent time difference
-# mid of power and recovery stroke defined as the max speed of power stroke and recovery stroke
-# but here assume the first half consist of power stroke and second half with recovery stroke
-# and take the steepest change in angular speed
-#
-#
-# return
-# max_sep = amplitude
-# ang_sep <- function(body_tps_file, limb_tps_file) {
-#   # read
-#   limb_tps <- kt$readtps(limb_tps_file)
-#   body_tps <- kt$readtps(body_tps_file)
-#   limb_land <- limb_tps$coords
-#   body_land <- body_tps$coords
-#
-#   # limb angle
-#   langle <- kt$tlangle(body_land, limb_land)
-#   rownames(langle) <- body_tps$id
-#   colnames(langle) <- c('ant1', 'ant2', 'mand')
-#   # langle_smooth <- apply(langle, 2, kt$smooth, win_size = smooth)
-#   langle_smooth <- apply(langle, 2, signal::sgolayfilt, 3, 19)
-#
-#   # define power and recovery stroke by ant2
-#   # t_len <- length(body_tps$id)
-#   # langle_power <- langle_smooth[1:(t_len/2), ]
-#   # langle_recor <- langle_smooth[(t_len - t_len/2 + 1):t_len, ]
-#
-#   # define mid of power stroke and mid of recovery stroke, by ant2
-#   # tlist <- as.integer(body_tps$id)
-#   # d_t <- diff(tlist, 2)
-#   # langle_diff_ant2 <- diff(langle_smooth[, 'ant2'], 2)
-#   # langle_dt_ant2 <- langle_diff_ant2 / d_t
-#   # power_mid_idx <- which.min(langle_dt_ant2[1:(t_len/2)]) + 1  # idx +1 because diff shorten length
-#   # recor_mid_idx <- c((t_len/2 + 1):t_len)[which.max(langle_dt_ant2[(t_len/2 + 1):t_len]) + 1]
-#
-#   # calculate angular separation
-#   ang_sep = kt$tsangle(body_land, limb_land)
-#   # ang_sep_smooth = apply(ang_sep, 2, kt$smooth)
-#   ang_sep_smooth = apply(ang_sep, 2, signal::sgolayfilt, 3, 19)
-#
-#
-#   # result
-#   # power_sep <- ang_sep_smooth[power_mid_idx, ]
-#   # recor_sep <- ang_sep_smooth[recor_mid_idx, ]
-#   # edge <- (smooth - 1) / 2
-#   # ang_sep_smooth <- ang_sep_smooth[-c(1:edge, (t_len - edge + 1):t_len), ]
-#   langle_smooth <- langle_smooth[-c(1:edge, (t_len - edge + 1):t_len), ]
-#   max_sep <- apply(langle_smooth, 2, max) - apply(langle_smooth, 2, min)
-#   return(list(power_sep = power_sep, recor_sep = recor_sep, ang_sep = ang_sep,
-#               ang_sep_smooth = ang_sep_smooth, max_sep = max_sep,
-#               langle_smooth = langle_smooth, langle = langle,
-#               power_mid_idx = power_mid_idx, recor_mid_idx = recor_mid_idx))
-# }
-
 ang_sep <- function(body_land, limb_land) {
 
   # calculate limb angle
@@ -66,9 +12,6 @@ ang_sep <- function(body_land, limb_land) {
 
   # result
   amplitude <- apply(langle, 2, max) - apply(langle, 2, min)
-  # return(list(ang_sep = ang_sep, ang_sep_smooth = ang_sep_smooth,
-  #             amplitude = amplitude, langle_smooth = langle_smooth,
-  #             langle = langle))
   return(list(ang_sep = ang_sep,
               amplitude = amplitude,
               langle = langle))

R/calc_power.R

@@ -1,6 +1,3 @@
-# --- calculate the power of r ---
-# r: numeric vector
-# u: numeric vector
 calc_power <- function(r, u) {
   fit <- lm(log10(u)~log10(r))  # power = slope of log-log model
   pval <- anova(fit)$P[1]

R/calc_refv.R

@@ -1,4 +1,4 @@
-
+# TODO: combine calc_refv and disp
 calc_refv <- function(body_land_array, type = c('top', 'side'),
                       scal, t_stamp) {
   type <- match.arg(type)
@@ -9,7 +9,7 @@ calc_refv <- function(body_land_array, type = c('top', 'side'),
     centroid_mat <- t(apply(body_land_array[-3, , ], 3, cent))  # 3rd lm only for direction
     tail_land_mat <- t(body_land_array[1, , ])
   }
-  
+
   cent_diff <- apply(centroid_mat, 2, dif)   # with 2 less values
   # NA-ed for 1st and last one
   # refv defined as velocity of centroid in opposite direction to cent-tail-vec

R/disp.R

@@ -1,12 +1,3 @@
-# use dot product to differentiate direction, with dot prooduct >0 in same
-# direction, dot product <0 in different direction and dot product = 0 as
-# perpendicular
-
-# depends on whether need to keep same time sampling points (same length easier
-# for indexing, but will insert NA) or need to smooth the result (Savitzky-Golay
-# filter will give undesirable result with NAs), adjust keep_len parameter.
-# Generally it is easier to remove NA than to add later
-
 disp <- function(body_land, keep_len = TRUE, win_size) {
   # size of moving window
   if (missing(win_size))

R/get_fluxln.R

@@ -1,13 +1,8 @@
-# line width for top view should be body width
-# line width for side view should be body height
-# here we use body height * 1.5
-# define flux line as what used in the manuscript
-
 get_fluxln <- function(body_land, vect_scal = 1, ln_width,
                        ln_width_scal = 1, type = c('top', 'side')) {
   # function things
   type <- match.arg(type)
-  
+
   # centroid, tail, and centroid-to-tail-vector
   # for side, 3rd lm only for direction so not used
   if (type == 'top') {
@@ -19,18 +14,18 @@ get_fluxln <- function(body_land, vect_scal = 1, ln_width,
     tail_land <- body_land[1, ]
   }
   cent_tail_vect <- tail_land - centroid
-  
+
   # scale centroid-to-tail-vector
   cent_tail_vect_scaled <- cent_tail_vect * vect_scal
-  
+
   # center point of flux line (top)
   # starting point of flux line (side)
   tail_extend <- centroid + cent_tail_vect_scaled
-  
+
   # unit normal vector to cent_tail_vect
   unormv1 <- unitv(c(cent_tail_vect[2], -cent_tail_vect[1]))  # clockwise
   unormv2 <- unitv(c(-cent_tail_vect[2], cent_tail_vect[1]))  # anti-clockwise
-  
+
   if (type == 'side') {
     ## determine the unit normal vector in ventral side
     # centroid-to-3rd-landmark vector
@@ -41,7 +36,7 @@ get_fluxln <- function(body_land, vect_scal = 1, ln_width,
     else
       unormv_vent <- unormv2
   }
-  
+
   # scale unormv and put it on the center point / starting point
   if (type == 'top') {
     # resulting flux line is from left to right of nauplius body
@@ -51,7 +46,7 @@ get_fluxln <- function(body_land, vect_scal = 1, ln_width,
     pt1 <- tail_extend
     pt2 <- tail_extend + unormv_vent * ln_width * ln_width_scal
   }
-  
+
   # return
   return(xy.coords(x = c(pt1[1], pt2[1]), y = c(pt1[2], pt2[2])))
 }

man/ang_sep.Rd

@@ -25,6 +25,7 @@ Abbreviations for the appendages:
   \item \code{ant2} = antenna
   \item \code{mand} = mandibles
 }
-Please refer to the details of \code{\inst\python\kinematics.py} for more details of the underlying functions (\code{vangle}, \code{sangle}, \code{langle}, \code{tsangle}, \code{tlangle}).
-}
+Please refer to the details of \code{\\inst\\python\\kinematics.py} for more 
+details of the underlying functions (\code{vangle}, \code{sangle}, 
+\code{langle}, \code{tsangle}, \code{tlangle}).
 }

man/calc_flux.Rd

@@ -18,21 +18,28 @@ proj_v(xycoord, vf_path, nseg = 8, side = c('right', 'left'))
 }
 
 \arguments{
-  \item{FUN}{(function) function to give xy coordinates of line segment for flux calculation, and should in R's \code{\link{xy.coords}} format}
+  \item{FUN}{(function) function to give xy coordinates of line segment for flux 
+    calculation, and should in R's \code{\link{xy.coords}} format}
   \item{vf_path}{(char) path to file containing the vector field}
-  \item{side}{(char) there are two possible normal directions to line segment, side specify which to output, see details}
-  \item{refv}{(num) velocity of frame of reference, see details. Single value for \code{calc_flux} but multiple values for \code{tcalc_flux}}
+  \item{side}{(char) there are two possible normal directions to line segment, 
+    side specify which to output, see details}
+  \item{refv}{(num) velocity of frame of reference, see details. Single value 
+    for \code{calc_flux} but multiple values for \code{tcalc_flux}}
   \item{width}{(num) length of the flux line segment}
   \item{...}{arguments to be passed into \code{FUN}}
   \item{body_land_array}{(3d array) array of landmarks of nauplius body}
   \item{vf_dir}{(char) path to directory containing files of vector field}
   \item{id}{(int) vector of integers specifying the frames id of vector fields}
   \item{vect_scal}{(num) passed to \code{link{get_fluxln}}, single value}
-  \item{relative}{(logical) if \code{TRUE}, \code{refv} will be calculated from \code{body_land_array}}
-  \item{ln_width}{passed to \code{link{get_fluxln}}, single value}
-  \item{ln_width_scal}{passed to \code{link{get_fluxln}}, single value}
-  \item{t_stamp}{passed to \code{link{refv}}}
-  \item{scal}{passed to \code{link{get_fluxln}}}
+  \item{type}{(char) either for top view or side view videos}
+  \item{relative}{(logical) if \code{TRUE}, \code{refv} will be calculated from 
+    \code{body_land_array}}
+  \item{ln_width}{passed to \code{\link{get_fluxln}}, single value}
+  \item{ln_width_scal}{passed to \code{\link{get_fluxln}}, single value}
+  \item{t_stamp}{passed to \code{\link{calc_refv}}}
+  \item{scal}{passed to \code{\link{get_fluxln}}}
+  \item{xycoord}{xy coordinates of two points defining the line segment to 
+    calculate flux, should in \code{R \link{xy.coords}} format}
   \item{nseg}{(int) how many segments the flux line consists of, arbitrarily set}
 }
 \value{
@@ -43,13 +50,34 @@ proj_v(xycoord, vf_path, nseg = 8, side = c('right', 'left'))
 \code{proj_v} returns \code{nseg} number of projected vectors 
 }
 \details{
-\code{tcalc_flux} is a wrapper of \code{calc_flux}, and \code{calc_flux} is a wrapper of \code{proj_vf}.
+\code{tcalc_flux} is a wrapper of \code{calc_flux}, and \code{calc_flux} is a 
+wrapper of \code{proj_vf}.
 
-Given xy coordinates of two points in the vector field, \code{proj_v} interpolate vectors on points on line segment formed by these two points, project them on normal direction, and returns their magnitude with direction indicated by sign. There are two possible unit normal vectors to the line segment, and determined as follows: 1) the two points forming the line segment is viewed as a vector with first point as the starting point and second as the ending point; 2) Rotate this vector 90 degrees clockwise and anticlockwise gives two normal vectors. Argument \code{side} of \code{'right'} outputs the projected values of clockwise normal direction and \code{'left'} outputs the anticlockwise counterpart. Changing the side only flip the sign of the values.
+Given xy coordinates of two points in the vector field, \code{proj_v} 
+interpolate vectors on points on line segment formed by these two points, 
+project them on normal direction, and returns their magnitude with direction 
+indicated by sign. There are two possible unit normal vectors to the line 
+segment, and determined as follows: 1) the two points forming the line segment 
+is viewed as a vector with first point as the starting point and second as the 
+ending point; 2) Rotate this vector 90 degrees clockwise and anticlockwise gives 
+two normal vectors. Argument \code{side} of \code{'right'} outputs the projected 
+values of clockwise normal direction and \code{'left'} outputs the anticlockwise 
+counterpart. Changing the side only flip the sign of the values.
 
-\code{calc_flux} takes the mean of the magnitudes of the projected vectors and times it with the length of the line segment, giving 2D 'flux'. To change the frame of reference, \code{refv} can be specified to give the velocity of frame of reference (e.g. moving body of nauplius). \code{refv} should be velocity that has only direction in one axis, i.e. in the axis normal to the flux line. Thus it is only a scalar value with plus minus sign, and the sign should be designated in the same direction as that of normal vector specified by \code{side}.
+\code{calc_flux} takes the mean of the magnitudes of the projected vectors and 
+times it with the length of the line segment, giving 2D 'flux'. To change the 
+frame of reference, \code{refv} can be specified to give the velocity of frame 
+of reference (e.g. moving body of nauplius). \code{refv} should be velocity that 
+has only direction in one axis, i.e. in the axis normal to the flux line. Thus 
+it is only a scalar value with plus minus sign, and the sign should be 
+designated in the same direction as that of normal vector specified by 
+\code{side}.
 
-\code{tcalc_flux} is the wrapper function used in the manuscript to batch process 2D flux over many frames of videos, specifically use the flux line definition described in the manuscript (see \code{\link{get_fluxln}}). For generalized use, \code{calc_flux} is the recommended function, which allows user to insert custom definition of flux line.
+\code{tcalc_flux} is the wrapper function used in the manuscript to batch 
+process 2D flux over many frames of videos, specifically use the flux line 
+definition described in the manuscript (see \code{\link{get_fluxln}}). For 
+generalized use, \code{calc_flux} is the recommended function, which allows 
+user to insert custom definition of flux line.
 }
 \seealso{
 \code{\link{get_fluxln}}, \code{\link{calc_refv}}

man/calc_r.Rd

@@ -3,7 +3,8 @@
 \alias{calc_s}
 \title{Calculate area of influence}
 \description{
-Calculate area of influence (and radius of circle with equivalent area) from generated flow.
+Calculate area of influence (and radius of circle with equivalent area) from 
+generated flow.
 }
 \usage{
 calc_r(dir, idlist, thre = c(0.5, 0.95), thre.len = 15, val.area)
@@ -15,7 +16,8 @@ calc_s(dir, idlist, ustar = 0.0005, val.area)
   \item{idlist}{(int) index to frames for calculations}
   \item{thre}{(num) threshold values to adjust U*, two values are required}
   \item{thre.len}{(int) number of U* values to use}
-  \item{val.area}{(num) area of each velocity vector value covers, by default  is \eqn{16px \times 16px \times (\textnormal{scale in mm/px})^2}}
+  \item{val.area}{(num) area of each velocity vector value covers, by default  
+    is \eqn{16px \times 16px \times (\textnormal{scale in mm/px})^2}}
   \item{ustar}{(num) theshold value for area calculation used in \code{cal_s}}
 }
 \value{
@@ -24,9 +26,14 @@ calc_s(dir, idlist, ustar = 0.0005, val.area)
   \item{u}{(num) theshold values used by \code{calc_r}}
 }
 \details{
-\code{calc_s} is intended for calculation of area of influence from flow exceeding a single threshold value.
+\code{calc_s} is intended for calculation of area of influence from flow 
+exceeding a single threshold value.
 
-\code{calc_r} is intended for calculation of area of influence over a series of threshold values, facilitating the calculation of flow attenuation over distance by using another function: \code{\link{calc_power}}. Values output from \code{calc_r} (\code{r} and \code{u}) are in matrix, with the second dimension being the values of theshold used in calculations.
+\code{calc_r} is intended for calculation of area of influence over a series of 
+threshold values, facilitating the calculation of flow attenuation over distance 
+by using another function: \code{\link{calc_power}}. Values output from 
+\code{calc_r} (\code{r} and \code{u}) are in matrix, with the second dimension 
+being the values of theshold used in calculations.
 }
 
 \seealso{

man/disp.Rd

@@ -25,5 +25,12 @@ Direction of displacement is determined by dot product between displacement
 vector and vector from centroid to tail processes (pointing in posterior 
 direction).
 
-Calculation of displacement depends on computation of lag differences (see \code{\link{diff}}) and thus the returned vector of values is shorter than the number of input time frames. \code{win_size} is equivalent to value of \code{lag} argument of \code{\link{diff}} +1. \code{keep_len} prevent the shortening of returned values by inserting \code{NA}(s) padding, which makes subsequent indexing covenient. However, presence of \code{NA}s could also interfere with subsequent processing such as smoothing (e.g. Savitzky-Golay filter in \link[signal]{sgolayfilt}). 
+Calculation of displacement depends on computation of lag differences 
+(see \code{\link{diff}}) and thus the returned vector of values is shorter than 
+the number of input time frames. \code{win_size} is equivalent to value of 
+\code{lag} argument of \code{\link{diff}} +1. \code{keep_len} prevent the 
+shortening of returned values by inserting \code{NA}(s) padding, which makes 
+subsequent indexing covenient. However, presence of \code{NA}s could also 
+interfere with subsequent processing such as smoothing (e.g. Savitzky-Golay 
+filter in \link[signal]{sgolayfilt}). 
 }

man/npiv.Rd

@@ -11,14 +11,23 @@ larvae with contrasting feeding modes.
 
 To reproduce the results, please refer to readme at Github repository for 
 explanation on how to use the package and updates.
+}
 
+\details{
 Functions included in the package were developed for analyses of data generated 
-from \href{http://life.bio.sunysb.edu/morph/soft-dataacq.html}{\code{TPSDig2}} and 
-\href{https://www.lavision.de/en/products/davis-software/}{\code{DaVis}} softwares 
-for kinematics and hydrodynamics analyses, respectively. \code{TPSDig2} is a landmark 
-registration tool and was used for digitization of body and appendages positions. 
-\code{DaVis} is a software used for particle image velocimetry, and outputs velocity 
-and vorticity fields. There is no utility tools for direct data import from other 
-softwares but all underlying calculations use \code{R}'s \code{\link{matrix}} or
-\code{\link{array}} classes of data.
+from \href{http://life.bio.sunysb.edu/morph/soft-dataacq.html}{\code{TPSDig2}} 
+and \href{https://www.lavision.de/en/products/davis-software/}{\code{DaVis}} 
+softwares for kinematics and hydrodynamics analyses, respectively. 
+\code{TPSDig2} is a landmark registration tool and was used for digitization of 
+body and appendages positions. \code{DaVis} is a software used for particle 
+image velocimetry, and outputs velocity and vorticity fields. There is no 
+utility tools for direct data import from other softwares but all underlying 
+calculations use \code{R}'s \code{\link{matrix}} or \code{\link{array}} classes 
+of data.
+
+Most of the functions were written specifically for the manuscript, especially 
+those for kinematics analyses as they rely on the specific definitions of 
+landmarks on nauplius larva. However, some functions such as 
+\code{\link{calc_flux}} and \code{\link{calc_r}}, are suitable for general 
+use with any velocity field data.
 }

man/phase_diff.Rd

@@ -2,7 +2,8 @@
 \alias{phase_diff}
 \title{Calculate phase of beating}
 \description{
-Given angular positions, calculate proportion of appendages moving in same directions.
+Given angular positions, calculate proportion of appendages moving in same 
+directions.
 }
 \usage{
 phase_diff(langle_smooth) 
@@ -17,7 +18,9 @@ phase_diff(langle_smooth)
 }
 
 \details{
-This function works with returned value of \code{\link{ang_sep}} (the \code{langle} result). It is recommended to smooth the angle data before use of this function to remove digitization errors.
+This function works with returned value of \code{\link{ang_sep}} (the 
+\code{langle} result). It is recommended to smooth the angle data before use of 
+this function to remove digitization errors.
 }
 \seealso{
 \code{\link{ang_sep}}