scalpelStep3: Perform Step 3 of SCALPEL.
In scalpel: Processes Calcium Imaging Data

Description Usage Arguments Details Value See Also Examples

This step involves spatial component selection and temporal component estimation. We estimate the temporal components corresponding to the dictionary elements from Step 2 by solving a sparse group lasso problem with a non-negativity constraint.

scalpelStep3(
  step2Output,
  lambdaMethod = "trainval",
  lambda = NULL,
  minClusterSize = 1,
  alpha = 0.9,
  removeBorder = FALSE,
  excludeReps = NULL
)

`step2Output`	An object of class `scalpel` or `scalpelStep2`, which result from running the `scalpel` or `scalpelStep2` functions, respectively.
`lambdaMethod`	A description of how lambda should be chosen: either `"trainval"` (default), `"distn"`, or `"user"`. A value of `"trainval"` means lambda will be chosen using a training/validation set approach. A value of `"distn"` means lambda will be chosen as the negative of the 0.1% quantile of elements of active pixels (i.e., those contained in at least one dictionary element) of Y. Using `"distn"` is computationally faster than `"trainval"`. Alternatively with `"user"`, the value of lambda can be directly specified using `lambda`.
`lambda`	The value of lambda to use when fitting the sparse group lasso. By default, the value is automatically chosen using the approach specified by `lambdaMethod`. If a value is provided for `lambda`, then `lambdaMethod` will be ignored.
`minClusterSize`	The minimum number of preliminary dictionary elements that a cluster must contain in order to be included in the sparse group lasso. The default value is 1 (i.e., all possible dictionary elements are included).
`alpha`	The value of alpha to use when fitting the sparse group lasso. The default value is 0.9.
`removeBorder`	A logical scalar indicating whether the dictionary elements containing pixels in the 10-pixel border of the video should be removed prior to fitting the sparse group lasso. The default value is `FALSE`.
`excludeReps`	A vector giving the indices of which dictionary elements to exclude, where the indices refer to the columns of `step2Output$A`. The default value is `NULL` and no dictionary elements are excluded. Users may also specify `"discarded"`, which will exclude all dictionary elements discarded using a previous call to `reviewNeurons` or `reviewNeuronsInteractive`.

To solve the sparse group lasso problem in this step, we minimize the following over Z with all non-negative elements:

0.5*sum((Y - AfilterTilde %*% Z)^2) + lambda*alpha*sum(Z)
+ lambda*(1-alpha)*sum(sqrt(rowSums(Z^2)))

where AfilterTilde is a scaled version of Afilter.

Several files containing data from this step and a summary of the step are saved in the folder "outputFolder/Step1_version/Step2_omega_omega_cutoff_cutoff/Step3_lambdaMethod_lambdaMethod_ minClusterSize_minClusterSize_alpha_alpha_removeBorder_removeBorder" where version is a 5-digit unique identifier that is automatically generated in Step 1, omega and cutoff are the user-supplied parameters from Step 2, and lambdaMethod, minClusterSize, alpha, and removeBorder are the user-supplied parameters from this step. If dictionary elements were manually excluded using excludeReps, this is appended to the folder name.

An object of class scalpelStep3, which can be summarized using summary and used with the plotting functions plotResults, plotResultsAllLambda, plotSpatial, plotTemporal, and plotBrightest.

Afilter: A matrix containing the filtered dictionary elements, where the ith column of Afilter is a vector of 1's and 0's, indicating whether each pixel is contained in the ith filtered dictionary element. Note that Afilter is equivalent to A after removing the components excluded due to being on the border (if removeBorder=TRUE) or having fewer preliminary dictionary elements in their cluster than minClusterSize.
Zhat: A matrix containing the estimated temporal components, where the ith row of Zhat is the estimated calcium trace corresponding to the ith spatial component (i.e., the ith column of Afilter).
lambda: The value of lambda used in fitting the sparse group lasso.
ZhatList: A list of matrices containing the estimated temporal components for alternative values of lambda specified in lambdaSeq. These can be plotted using plotResultsAllLambda.
lambdaSeq: A vector with length equaling the length of ZhatList, where the ith element indicates the value of lambda corresponding to the temporal components in ZhatList[[i]].
clustersUse: A vector with length equaling the number of columns of Afilter, where the ith element indicates which column of step2Output$A the ith column of Afilter equals.
Other elements: As specified by the user or returned from a previous step.

The entire SCALPEL pipeline can be implemented using the scalpel function. The other steps in the pipeline can be run using the scalpelStep0, scalpelStep1, scalpelStep2 functions. Results from this step can be summarized using summary, loaded at a later time using getScalpelStep3, and plotted using plotSpatial, plotTemporal, plotResults, and plotBrightest.

## Not run: 
### many of the functions in this package are interconnected so the
### easiest way to learn to use the package is by working through the vignette,
### which is available at ajpete.com/software

#assumes you have run the example for the "scalpelStep2" function

#run Step 3 of SCALPEL
Step3Out = scalpelStep3(step2Output = Step2Out)
summary(Step3Out)

## End(Not run)