This README.txt file was generated by Demi E. Moed on 7/10/2024.

*********************
*General Information*
*********************
Title: Code and Sample Data for "Mesoscale Polymer Ribbon Arrays: High Aspect Ratio Surface Structures and Their Digital Reconstruction

Authors: Demi E. Moed, Michael S. Dimitriyev, Benjamin R. GreenVall, Gregory M. Grason, Alfred J. Crosby*

Corresponding Author Contact Information:
Name: Alfred J. Crosby
Institution: Department of Polymer Science & Engineering, University of Massachusetts Amherst
Address: 120 Governors Dr., Amherst, Massachusetts, 01003, United States of America
E-mail: crosby@mail.pse.umass.edu

Resources: Please reference https://doi.org/10.48550/arXiv.2403.17283 for access to the relevant paper. 

**************
*System Setup*
**************

System Software Requirements:
	MATLAB R2022a or later with the following toolboxes installed:
		-Image Processing Toolbox
		-Statistics and Machine Learning Toolbox
		-Computer Vision Toolbox
	FIJI/ImageJ

Setup:
	The working directory should contain the folder Matlab Code, which contains the following scripts:
		1. autoRunFinal.m

	As well as the following functions:
		1. breakup2Seg.m
		2. curvatureCalculation.m
		3. curvatureCalculation2.m
		4. end2endSeparation.m
		5. endPointConnector.m
		7. junctionEval.m
		7. junctionTrace.m
		8. nearestNeighborContacts.m
		9. nearestNeighborsDist.m
		10. neighborRange.m
		11. ribbonAnalysisMasterFunction.m
		12. segmentBreakup.m
		13. segmentEval.m
		14. segmentFinalProcessing.m
		15. sortAndCombine.m
		16. spareConnection.m
		17. tangleAssessment.m
		18. vectorConnect.m
		19. voxelizeVectorize.m

	The working directory should also contain:
		-A folder in which the confocal microscopy data is stored (Sample Data Sets -> Confocal Microscopy Tif Stacks). 
			Each individual region and time stamp imaged by confocal microscopy should be saved as a separate .tif stack.
			These are inputs to the algorithm pipeline.
		-A folder in which the skeletonized data is stored (Sample Data Sets --> Skeletonized Ribbon Arrays)
			These are produced by FIJI/ImageJ in Protocol I, described below.
			These are then read in by the MATLAB segmentation code described below in Protocol II.
		-An output folder, here titled "ProcessedData" for convenience
	
	Other Notes:
		-All 3D confocal microscopy data must be saved as a .tiff stack following any processing using the microscope's proprietary software.
		-Here, the folder titled Reference Datasets contains a set of pre-processed data for your reference. These are the results you should get from the four sample datasets.

**************
*Instructions*
**************

I. Run FIJI/ImageJ Skeletonization
	a) With FIJI/ImageJ, open z-stack: File --> Open --> Select .tif Stack
	b) Remove Empty Frames: Image --> Stacks --> Tools --> Slice Keeper
		1) Your first slice should be no more than 2 frames below the base of your lowest ribbon
		2) Your last slice should be no more than 2 frames above the tip of your tallest ribbon
		3) Incriment: 1
	c) Apply Gaussian Blur: Process --> Filters --> Gaussian Blur 3D
		-A sigma of 2 in all directions works for the test data, but this can be adjusted to match your dataset
	d) Binarize: Image --> Adjust --> Threshold
		1) Check "Dark background"
		2) Check "Stack histogram"
		3) Check "Don't Reset Range"
		4) Uncheck "Raw Values"
		5) Use Default method and B&W
		6) Adjust top slider to appropriate threshold**
			-For the sample data sets, a threshold between 16 and 32 works well
		7) Apply -> Convert to Mask
			i) Method: Default
			ii) Background: Dark
			iii) Check "Create new stack" and "Black Background (of binary masks)"
	e) Skeletonize: Plugins --> Skeleton --> Skeletonize 2D/3D
	f) Ensure White Background:
		1) If the resulting skeleton is black pixels on a white background, move directly to step g.
		2) If the resulting skeleton is white pixels on a black background: Image -> Lookup Tables -> Invert LUT
	g) Export: File --> Save as --> Tiff
		1) For ease of future batch processing, make sure all skeletonized .tiff stacks are saved in the same file folder. Note that the file name will propogate through all future steps.

**If the threshold is too low, the ribbons will bleed into one another. If the threshold is too high, the dimmest sections of certain ribbons will be excluded.

II. Run MATLAB Skeleton Analysis:
	a) Open autoRunFinal.m
	a) Update the following:
		1) Variables pxSize and zSize should match the parameters of your data collection
			-For the sample datasets, pxSize is 1.24, and zSize is 4.65. The code asssumes all distances are in microns
		2) Variables xLimit, yLimit, and zLimit should match the boundaries of your imaging area
			-For the sample datasets,  xLimit is 1272.79, yLimit is equal to the xLimit, and zLimit is 800
		3) outputFolder string should match the name of the intended folder destination of your processed data
			-For the sample datasets, this is ProcessedData
	c) Run autoRunFinal.m
		1) When the file directory opens, navigate to the desired file repository (Sample Data Sets -> Skeletonized Arrays)
		3) Select the skeletonized .tiff stacks you wish to analyze. The batch processing of the code requires a minimum of 2.
		4) Click "Open."
		5) The code will automatically process all selected files in order of selection. Total run time will depend on number, size, and complexity of files. This may take several hours, and it is recommend to run large batches overnight.
		6) The command window will update with the fraction of datasets completed and the total runtime after each file is analyzed.
	d) All processed data will be saved using the specified dataset's fileName into outputFolder.
			-fileNameAnalysis.xls contains the computed statistics for that particular dataset. The first sheet details the statistics for each individual ribbon, and the second contains the metrics for all points independent of the ribbon of origin.
			-fileNameRawResultsPlot.png depicts the reconstructed ribbon array
			-fileNameSmoothedPlot.png depicts the ribbon array with the tether points removed and the ribbons smoothed
			-fileNameRibbonData.mat contains three 1xn cell arrays, corresponding to the raw ribbon reconstructed data (rawRibbons), the smoothed data (smoothedRibbons), the curvature of each point along a ribbon's backbone as a function of its position along the ribbon's length (lenCur)

== References ==
1. X. Feng, C. J. Burke, M. Zhuo, H. Guo, K. Yang, A. Reddy, I. Prasad, R. M. Ho, A. Avgeropoulos, G. M. Grason and E. L. Thomas, Nature, 2019, 575, 175–179.
2. X. Huang, D. Wen, Y. Zhao, Q. Wang, W. Zhou and D. Deng, Results Phys, 2016, 6, 170–177.
3. G. Gaiselmann, I. Manke, W. Lehnert and V. Schmidt, Image Analysis and Stereology, 2013, 32, 57–63.
4. L. R. Gómez, N. A. García and T. Pöschel, Proc Natl Acad Sci U S A, 2020, 117, 3382-3387.
5. P. Latil, L. Orgéas, C. Geindreau, P. J. J. Dumont and S. Rolland du Roscoat, Compos Sci Technol, 2011, 71, 480–488.
6. J. Lux, Image Analysis and Stereology, 2013, 32, 13–25.
7. G. Gaiselmann, R. Thiedmann, I. Manke, W. Lehnert and V. Schmidt, Comput Mater Sci,2012, 59, 75–86.