{"id":21375004,"url":"https://github.com/davidbhr/compactionanalyzer","last_synced_at":"2025-06-24T10:09:01.173Z","repository":{"id":169385181,"uuid":"278071833","full_name":"davidbhr/CompactionAnalyzer","owner":"davidbhr","description":"A python package to analyze the matrix fiber orientation and intensity around cells in fiber matrices (as a proxy for cellular forces).  ","archived":false,"fork":false,"pushed_at":"2025-01-17T16:33:46.000Z","size":1696341,"stargazers_count":9,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-05-07T07:39:26.053Z","etag":null,"topics":["cell-mechanics","collagen","contractility","ecm","fibers","fibrosis","image-processing","imaging","mechanobiology","microscopy","orientation","tfm","traction-force-microscopy"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/davidbhr.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2020-07-08T11:32:17.000Z","updated_at":"2025-01-17T16:32:02.000Z","dependencies_parsed_at":null,"dependency_job_id":"ab405e27-fc5f-457a-af99-2f54427eefb1","html_url":"https://github.com/davidbhr/CompactionAnalyzer","commit_stats":null,"previous_names":["davidbhr/compactionanalyzer"],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/davidbhr/CompactionAnalyzer","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davidbhr%2FCompactionAnalyzer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davidbhr%2FCompactionAnalyzer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davidbhr%2FCompactionAnalyzer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davidbhr%2FCompactionAnalyzer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/davidbhr","download_url":"https://codeload.github.com/davidbhr/CompactionAnalyzer/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davidbhr%2FCompactionAnalyzer/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261649855,"owners_count":23189753,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cell-mechanics","collagen","contractility","ecm","fibers","fibrosis","image-processing","imaging","mechanobiology","microscopy","orientation","tfm","traction-force-microscopy"],"created_at":"2024-11-22T08:46:25.412Z","updated_at":"2025-06-24T10:08:56.154Z","avatar_url":"https://github.com/davidbhr.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# CompactionAnalyzer \n\nCells apply contractile forces to their surrounding e.g. during migration, development, wound healing, or in various diseases. To study these processes, cellular forces can be measured using traction force microscopy. However, 3D traction force microscopy can be very laborious (nonlinear FE models, rheology, regularization). In 3D fiber networks, alignment and compaction of fibers is a consequence of cellular forces. The method here quantifies the amount of fiber alignment \u0026 fiber density around cells in fiber matrices. These quantities can then be used as an proxy value of contractile force (or for different purposes).\n\n\u003cp align=\"center\"\u003e\n\u003cimg src=\"../master//docs/images/TimelapseHSC.gif\" width=\"700\" /\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\nHepatic stellate cell compacting a collagen type I hydrogel over time.\n\u003c/p\u003e\n\n## Quantification of tissue compaction around cells\n\nPython package to quantify the tissue compaction (as a measure of the contractile strength) generated by cells or multicellular spheroids that are embedded in fiber materials. For this we provide the two following approaches:\n\n* Evaluating the directionality of fibers towards the cell center.\n* Evaluating the increased fiber intensity around the cell.  \n\n\n\u003cimg src=\"../master//docs/images/Fig1-rawtostructure.png\" width=\"1000\" /\u003e\n\n\n\n## Installation\n\nSimply install the CompactionAnalyzer via Pip by running following command in the console:\n\n```python\npip install CompactionAnalyzer\n```\n\n\nAlternativley, you can download a standalone \".exe\" executable of the 3D TFM software saenopy [here](https://github.com/rgerum/saenopy/releases).\nCompactionAnalyzer is included here, just select the \"Orientation\" tab.\n\n\n*Alternatively: The package can be installed by cloning this repository or downloading the repository as a zip file [here](https://github.com/davidbhr/CompactionAnalyzer/zipball/master). For installation, run the following command within the unzipped folder, in which the *setup.py* file is located: `pip install -e .`. This automatically downloads and installs all other required packages.*\n\n\n## Preprint\nIf you want to read more or to cite *CompactionAnalyzer* you can refer to our preprint:\n\n*Fiber alignment in 3D collagen networks as a biophysical marker for cell contractility* \\\nDavid Böhringer, Andreas Bauer, Ivana Moravec, Lars Bischof, Delf Kah, Christoph Mark, Thomas J Grundy, Ekkehard Goerlach, Geraldine M O'Neill, Silvia Budday, Pamela Strissel, Reiner Strick, Andrea Malandrino, Richard Gerum, Michael Mak, Martin Rausch, Ben Fabry \\\n**doi:  https://doi.org/10.1101/2023.06.28.546896**\n\n\n## Tutorial\n\nThe scripts within the turorial folder might be a good start to get familiar with the analyis: The script `CompactionAnalysis_cells_collagen.py` evaluates 4 example cells that are embedded in collagen and compacted the surrounding collagen. Fiber stucture was recorded using 2nd harmonic imaging and cell outline using calcein staining. \n\nFurther scripts `CompactionAnalysis_empty_collagen.py` \u0026 `CompactionAnalysis_artificial_data.py` evaluate empty collagen gels that show random fiber allignement and artifiacl data with random allignement. \n\nIn these script we start to import all necessary functions using\n\n```python\nfrom CompactionAnalyzer.CompactionFunctions import *\n```\n\nFor the analysis, we need per cell an image of the fiber structure (e.g. 2nd harmonic, confocal reflection or stained fluorescence images; maximum intensity projection around the cells might be useful) and an image of the cell for segmentation (staining or brightfield). \n\nWe define the input data for the fibers using `fiber_list_string` ant the cells using `cell_list_string` (here we can utilize the * place holder to selecet multiple images).  `generate_lists()` then searches all specified fiber and cell paths and creates the output subfolder in the specified `output_folder` directory completley automatically.\n\n```python\noutput_folder = \"C:\\user\\Analysis_output\"                     # output folder that will be created and filled automatically\nfiber_list_string =  r\"C:\\user\\imagedata\\cell_*\\*ch00*.tif\"   # input fiber images of all cells \ncell_list_string =  r\"C:\\user\\imagedata\\cell_*\\*ch01*.tif\"    # input stained images of all cells \n\nfiber_list,cell_list, out_list = generate_lists(fiber_list_string, cell_list_string, output_main =output_folder)\n```\n\nWe now want to start the analysis and compute the orientation of individual fibers using structure tensor analysis. Here *sigma_tensor* is the kernel size that determines the length scale on which the strucutre is analysed. The kernel size should be in the range of the structure-size we want to look at and can be optimized for the individual application. For our fiber gels we use a value of 7 µm, which is in range of the pore size. The script `DetermineWindowSize.py` in the tutorial folder provides a template to systematically test different windowsizes on the same image pair and from that select the ideal size of the `sigma_tensor` for this setup (which displays a peak in the orientation).\n\n\nWe can adjust all of the following paramters before starting the analysis. The corresponding pixel scale is set as `scale` and the segmentiation can be changed by using the `segmention_thres` or by changing the local contrast enhancement via `seg_gaus1, seg_gaus2`. With `show_segmentation = True` we can inspect the segmentation or - if preferred - segment the mask manually by clicking using `manual_segmention  = True`. Further, a maximal distance around the cell center can be specified for the analysis using `max_dist`. \n\n```python\nscale =  0.318                  # imagescale in um per pixel\nsigma_tensor = 7/scale          # sigma of applied gauss filter / windowsize for the structure tensor analysis in px\n                                # should be in the order of the objects to analyze !! \n                                # 7 um for collagen \nedge = 40                       # Cut off pixels at the edge since values at the border cannot be trusted\nsegmention_thres = 1.0          # for cell segmentation, thres 1 equals normal otsu threshold , change to detect different percentage of bright pixel\nmax_dist = None                 # optional: specify the maximal distance around cell center for the analysis (in px)\nseg_gaus1, seg_gaus2 = 0.5,100  # 2 gaus filters used as bandpassfilter for local contrast enhancement; For seg_gaus2 = None a single gauss filter is applied\nmax_dist = None,                # optional: specify the maximal distance around cell center for analysis (in px)\nregional_max_correction = True  # background correction using regional maxima approach\nshow_segmentation = False       # display the segmentation output (script won't run further)\nsigma_first_blur  = 0.5         # slight first bluring of whole image before appplying the structure tensor\nangle_sections = 5              # size of angle sections in degree \nshell_width =  None             # pixel width of distance shells (px-value=um-value/scale)\nmanual_segmention = False       # segmentation of mask by manual clicking the cell outline\nplotting = True                 # creates and saves individual figures additionally to the excel files \ndpi = 200                       # resolution of figures \nSaveNumpy = False               # saves numpy arrays for later analysis - can create large data files\nnorm1=1,norm2 = 99              # contrast spreading for input images between norm1- and norm2-percentile; values below norm1-percentile are set to zero and\n                                # values above norm2-percentile are set to 1\nseg_invert=False                # if segmentation is inverted dark objects are detected inseated of bright objects\nseg_iter = 1                    # number of repetitions of  binary closing, dilation and filling holes steps\nsegmention_method=\"otsu\"        # use \"otsu\", \"entropy\" or \"yen\"  as segmentation method\nsegmention_min_area = 1000      # small bjects below this px-area are removed during cell segmentation\nload_segmentation = False       # if True enter the path of the segementation.npy - file in path_seg\npath_seg = None                 # to load a mask\n```\n\n\nNow we start to analyse all our cells individually using the single function `StuctureAnalysisMain` (follow the scripts in the tutorial folder):\n\n```python\n# Start the structure analysis with the above specified parameters\nStuctureAnalysisMain(fiber_list=fiber_list,\n                     cell_list=cell_list, \n                     out_list=out_list,\n                     scale=scale, \n                     sigma_tensor = sigma_tensor , \n                     ...)\n```\n\n\nFor each cell we now receive 3 excel files: \n\n* `results_total.xlsx`    - Evaluating the overall orientation within the field of view \n* `results_distance.xlsx` - Evaluating the orientation \u0026 Intensity in distance shells towards the cell surface\n* `results_angle.xlsx`    - Evaluating  the orientation \u0026 Intensity in angle sections around the cell center\n\nTo compare different cells we can utilize e.g the total orientation within a field of view (requires that all cells have the same Field of View) or could also compare the intensity values in the first distance shell(s). \n\n\n\u003cimg src=\"../master//docs/images//Fig2-orientationeval.png\" width=\"1000\" /\u003e\n\n\nIf we want to evaluate a measurement containing multiple cells, we can read in all excel files (of individual cells) in the underlying folders of the given `data` path and combine them in a new excel file by using:\n\n```python\nSummarizeResultsTotal(data=\"Analysis_output\", output_folder= \"Analysis_output\\Combine_Set1\")\nSummarizeResultsDistance(data=\"Analysis_output\", output_folder= \"Analysis_output\\Combine_Set1\")\n```\n\n \u003e Note: These function searches all subfolders for the *\"results_total.xlsx\"* and *\"results_distance.xlsx\"* files. If you want to discard outliers it might be practical to rename the corresponding files to for example *\"_results_total.xlsx\"* and *\"_results_distance.xlsx\"*)\n\n\nWe receive a compromised excel sheet that returns the global analysis for all cells and another excel sheet with the mean distance analysis. The different columns `Mean Angle` and `Orientation` refer to the angular deviation between all orientation vectors to the respective cell center and the hereby resulting orientation. These quantities are weighted by the coherency (orientation strength) and additionally also by both, the coherency and the image intensity.  From the different cells we now can calculate different quantities, as for example the mean `Orientation (weighted by intensity and coherency)` of all cells, which is named `Overall weighted Oriantation (mean all cells)` and also stored in the same excel file.\n\n\n\u003cimg src=\"../master/docs/images/Fig3-combineexcel.png\" width=\"800\" /\u003e\n\n## Graphical User Interface (GUI)\n\nFor an easy use of the CompactionAnalyzer, we provide a graphical user interface (GUI) that simplifies the execution and evaluation of several experiments. To start the GUI, just run the script `GUI.py`. Pairs of fiber and cell images can be loaded individually or batchwise by using the *-placeholder.\n\n\u003cimg src=\"../master//docs/images//GUI_readimages.png\" width=\"800\" /\u003e\n\nParameters can be configurated and the cell-segmentationen viewed and changed individually per cell. Upon `Run` the analysis is started and results will be stored in specified output folder.\n\n\u003cimg src=\"../master//docs/images//GUI_evaluation.png\" width=\"800\" /\u003e\n\nFor data analysis, the `results_total.xlsx` files can be loaded again individually or batchwise by using the *-placeholder. Intensity and Orientation can then be evaluated individually or by adding several cells to user defined groups. Bar and distance plots (mean+-se) are created automatically and individual python-scripts to re-plot the data can be exported.\n\n\u003cimg src=\"../master//docs/images//GUI_DataAnalysis.png\" width=\"800\" /\u003e\n\n\n\n## Resolving Drug Effects \u0026 Multicellular Compaction Assay\n\nAn application of the CompactionAnalyzer is resolving drug-dependend effects on cell contractility of individual cells or mutlicellular aggregates. \n\n\u003e Additionally, absolute forces of spheroids can be measured using the *jointforces* python package [here](https://github.com/christophmark/jointforces), which requires additonal material measurements \u0026 timelapse imaging. Absolute forces of cell can be assesed using *saenopy* [here](https://github.com/rgerum/saenopy), which requires additonal material measurements and two (larger) 3D stacks of the contracted and realaxed state per cell.\n\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdavidbhr%2Fcompactionanalyzer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdavidbhr%2Fcompactionanalyzer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdavidbhr%2Fcompactionanalyzer/lists"}