Package: collageradiomicstypes
Co-occurrence of Local Anisotropic Gradient Orientations (CoLlAGe)Table of ContentsScienceOverviewFeaturesReferencesCodeIdempotenceDocumentationDependenciesInstallation & UsageExecutive Summary for ExpertsDockerDocker Setupcollageradiomics-examples Docker Imagecollageradiomics-pip Docker ImagePipPython UsageBasic ExampleReal DataContactScienceOverviewBack toTable of ContentsCoLlAGecaptures subtle anisotropic differences in disease pathologies by measuring entropy of co-occurrences of voxel-level gradient orientations on imaging computed within a local neighborhood.CoLlAGeis based on the hypothesis that disruption in tissue microarchitecture can be quantified on imaging by measuring the disorder in voxel-wise gradient orientations. CoLlAGe involves assigning every image voxel a ‘disorder value’ associated with the co-occurrence matrix of gradient orientations computed around every voxel.Details on extraction ofCoLlAGefeatures are included in[1]. After feature extraction, the subsequent distribution or different statistics such as mean, median, variance etc can be computed and used in conjunction with a machine learning classifier to distinguish similar appearing pathologies. The feasibility of CoLlAGe in distinguishing cancer from treatment confounders/benign conditions and characterizing molecular subtypes of cancers has been demonstrated in the context of multiple challenging clinical problems.FeaturesBack toTable of ContentsEach of the 13CoLlAGecorrelate to one of the 13 Haralick texture features[2]:AngularSecondMomentContrastCorrelationSumOfSquareVarianceSumAverageSumVarianceSumEntropyEntropyDifferenceVarianceDifferenceEntropyInformationMeasureOfCorrelation1InformationMeasureOfCorrelation2MaximalCorrelationCoefficientReferencesBack toTable of ContentsIf you make use of this implementation, please cite the following paper:[1] Prasanna, P., Tiwari, P., & Madabhushi, A. (2016). "Co-occurrence of Local Anisotropic Gradient Orientations (CoLlAGe): A new radiomics descriptor. Scientific Reports", 6:37241.[2] R. M. Haralick, K. Shanmugam and I. Dinstein, "Textural Features for Image Classification," in IEEE Transactions on Systems, Man, and Cybernetics, vol. SMC-3, no. 6, pp. 610-621, Nov. 1973,doi: 10.1109/TSMC.1973.4309314.CodeIdempotenceBack toTable of ContentsOurCoLlAGemodule includes parameter tuning information in the output. It contains the image(s) and mask(s), and the settings applied upon them. This allows multiple fully reproducible runs without having to remember or find the original parameters.DocumentationBack toTable of Contentshttp://collageradiomics.rtfd.io/Dependencies:Back toTable of ContentsWe thank these generous developers that allowed us to build collageradiomics without reinventing the wheel:matplotlibnumpyscikit-learnscikit-buildmahotasscipy(Note: We are using==for version numbers of our dependencies as a design choice.)Installation & UsageThese instructions will help set up theCoLlAGecore module and examples. They assume you are working out of a terminal such asPowershellon Windows orKonsoleon Linux.Executive Summary for ExpertsBack toTable of ContentsIf you are already well-versed inDockerandpip, here is a quick list of commands for each operating system:Linuxsudodockerpullradxtools/collageradiomics-pip:latest
sudodockerrun-itradxtools/collageradiomics-pip

gitclonehttps://github.com/radxtools/collageradiomics.git
sudodockerpullradxtools/collageradiomics-examples:latest
sudodockerrun-it-p8888:8888-v$PWD:/rootradxtools/collageradiomics-examples

pip3installcollageradiomicsWindowsdocker pull radxtools/collageradiomics-pip:latestdocker run -it -v ${PWD}:/root radxtools/collageradiomics-pipgit clone https://github.com/radxtools/collageradiomics.gitdocker pull radxtools/collageradiomics-examples:latestdocker run -it -p 8888:8888 -v ${PWD}:/root radxtools/collageradiomics-examplespip install collageradiomicsYou may wish to jump right to somePythonexamples.DockerBack toTable of ContentsDockeris like a stand-alone operating system container that comes pre-installed with all the dependencies already set up properly. It allows you to jump right into coding withCoLlAGe. We offer 2Dockerimages: a basic core image for you to start coding with theCoLlAGefeatures (calledcollageradiomics-pip) and an image that contains a runningJupyternotebook withCoLlAGepre-installed and examples ready to run (calledcollageradiomics-examples).Docker SetupBack toTable of ContentsLinuxUbuntu:https://docs.docker.com/engine/install/ubuntu/CentOS:https://docs.docker.com/engine/install/centos/Debian:https://docs.docker.com/engine/install/debian/Fedora:https://docs.docker.com/engine/install/fedora/General Linux:https://docs.docker.com/engine/install/binaries/macOSFollow instructions here:https://docs.docker.com/docker-for-mac/install/WindowsClick hereand follow the instructions to installDocker.Search forDockerin your start manu and run it:If it's running you should see an icon:collageradiomics-examples Docker ImageBack toTable of ContentsThisDockerimage contains a running Jupyter notebook with theCoLlAGemodule pre-installed. From the cloned repository directory, we will start up aDockerimage which will run a live web server and host aJupyternotebook at the URLhttp://localhost:8888which contains examples of using the code.Note: Using this method requires you to pull the code from our repository. If you don't need theJupyterexamples and just want to start usingCoLlAGeright away, you can skip this step and jump to the instructions forCorebyclicking here.LinuxNote: This was tested on Ubuntu 19.10 and 20.04Install git:user@machine:~$sudoapt-yinstallgitReading package lists... DoneBuilding dependency treeReading state information... Donegit is already the newest version (1:2.20.1-2ubuntu1.19.10.3).0 upgraded, 0 newly installed, 0 to remove and 0 not upgraded.user@machine:~$Clone the repository:user@machine:~$gitclonehttps://github.com/radxtools/collageradiomics.gitCloning into 'collageradiomics'...remote: Enumerating objects: 280, done.remote: Total 280 (delta 0), reused 0 (delta 0), pack-reused 280userReceiving objects: 100% (280/280), 1.48 MiB | 9.23 MiB/s, done.Resolving deltas: 100% (125/125), done.user@machine:~$cdcollageradiomicsuser@machine:~/collageradiomics$ls-lPull the latestDockerimage:user@machine:~/collageradiomics$sudodockerpullradxtools/collageradiomics-examples:latestlatest: Pulling from radxtools/collageradiomics-examplesDigest: sha256:107a2804e76b156f40d571b8422f822a3712353645c86e5cc2275d2aea85c9beStatus: Image is up to date for radxtools/collageradiomics-examples:latestdocker.io/radxtools/collageradiomics-examples:latestuser@machine:~/collageradiomics$Run theDockerimage:user@machine:~/collageradiomics$sudodockerrun-it-p8888:8888-v$PWD:/rootradxtools/collageradiomics-examples[I 06:35:13.806 NotebookApp] Writing notebook server cookie secret to /tmp/notebook_cookie_secret[W 06:35:14.030 NotebookApp] All authentication is disabled.  Anyone who can connect to this server will be able to run code.[I 06:35:14.033 NotebookApp] Serving notebooks from local directory: /root[I 06:35:14.034 NotebookApp] The Jupyter Notebook is running at:[I 06:35:14.034 NotebookApp] http://d41cc76f5035:8888/[I 06:35:14.034 NotebookApp] Use Control-C to stop this server and shut down all kernels (twice to skip confirmation).You can now skip over theWindowsinstallation instructions and jump straight to theExploring The Examplessection.WindowsInstallgit. A quick online search for"git for Windows"will provide you with several options for installing thegitcommand. If it's correctly installed, the following should output your current version of git:Windows PowerShellCopyright (C) Microsoft Corporation. All rights reserved.Try the new cross-platform PowerShell https://aka.ms/pscore6PS C:\Users\user> git --versiongit version 2.26.2.windows.1PS C:\Users\user>Clone the repository:Windows PowerShellCopyright (C) Microsoft Corporation. All rights reserved.Try the new cross-platform PowerShell https://aka.ms/pscore6PS C:\Users\user> git clone https://github.com/radxtools/collageradiomics.gitCloning into 'collageradiomics'...remote: Enumerating objects: 280, done.Receiving objects:  97% (272/280), 1.24 MiB | 1.02 MiB/sused 280 eceiving objects:  91% (255/280), 1.24 MiB | 1.02 MiB/sReceiving objects: 100% (280/280), 1.48 MiB | 1.09 MiB/s, done.Resolving deltas: 100% (125/125), done.PS C:\Users\user> cd collageradiomicsPS C:\Users\user\collageradiomics> dirDirectory: C:\Users\user\collageradiomicsMode                LastWriteTime         Length Name----                -------------         ------ ----d-----       2020-06-24      3:31                dockerd-----       2020-06-24      3:31                jupyterd-----       2020-06-24      3:31                moduled-----       2020-06-24      3:31                sample_data-a----       2020-06-24      3:31            215 .gitignore-a----       2020-06-24      3:31          35823 LICENSE-a----       2020-06-24      3:31           4045 README.md-a----       2020-06-24      3:31            136 start.shPS C:\Users\user\collageradiomics>GiveDockeraccess to your cloned repository:Right click on the context menu near the clock:SelectDashboard:After you click onDashboard, a window will pop up. Click on the gear icon forSettingsand move toResources:arrow_right:File Sharing.Add your cloned repository folder:Pull the latestDockerimage:Windows PowerShellCopyright (C) Microsoft Corporation. All rights reserved.Try the new cross-platform PowerShell https://aka.ms/pscore6PS C:\Users\user\collageradiomics> docker pull radxtools/collageradiomics-examples:latestlatest: Pulling from radxtools/collageradiomics-examplesd51af753c3d3: Already existsfc878cd0a91c: Already exists6154df8ff988: Already existsfee5db0ff82f: Already existsa6501aa3ed52: Already existsDigest: sha256:107a2804e76b156f40d571b8422f822a3712353645c86e5cc2275d2aea85c9beStatus: Downloaded newer image for radxtools/collageradiomics-examples:latestdocker.io/radxtools/collageradiomics-examples:latestPS C:\Users\user\collageradiomics> docker pull radxtools/collageradiomics-examples:latestlatest: Pulling from radxtools/collageradiomics-examplesDigest: sha256:107a2804e76b156f40d571b8422f822a3712353645c86e5cc2275d2aea85c9beStatus: Image is up to date for radxtools/collageradiomics-examples:latestdocker.io/radxtools/collageradiomics-examples:latestPS C:\Users\user\collageradiomics>Run theDockerimage:Windows PowerShellCopyright (C) Microsoft Corporation. All rights reserved.Try the new cross-platform PowerShell https://aka.ms/pscore6PS C:\Users\user> cd collageradiomicsPS C:\Users\user\collageradiomics> docker run -it -p 8888:8888 -v ${PWD}:/root radxtools/collageradiomics-examples[I 08:28:36.091 NotebookApp] Writing notebook server cookie secret to /tmp/notebook_cookie_secret[W 08:28:36.576 NotebookApp] All authentication is disabled.  Anyone who can connect to this server will be able to run code.[I 08:28:36.585 NotebookApp] Serving notebooks from local directory: /root[I 08:28:36.585 NotebookApp] The Jupyter Notebook is running at:[I 08:28:36.585 NotebookApp] http://c5745f91dbee:8888/[I 08:28:36.585 NotebookApp] Use Control-C to stop this server and shut down all kernels (twice to skip confirmation).Exploring The ExamplesBack toTable of ContentsOpen up a web browser tohttp://localhost:8888Navigate to theJupyter:arrow_right:Examplesdirectory.Click on one of the example*.ipynbfiles.RunCell:arrow_right:Run all.Feel free to add your own cells and run them to get familiar with theCoLlAGecode.To stop theJupyternotebook and exit theDockerimage, pressCtrl+Ctwice:[I 07:05:36.271 NotebookApp] The Jupyter Notebook is running at:[I 07:05:36.271 NotebookApp] http://4f033d68769d:8888/[I 07:05:36.271 NotebookApp] Use Control-C to stop this server and shut down all kernels (twice to skip confirmation).^C[I 07:05:37.628 NotebookApp] interruptedServing notebooks from local directory: /root0 active kernelsThe Jupyter Notebook is running at:http://4f033d68769d:8888/Shutdown this notebook server (y/[n])? ^C[C 07:05:38.744 NotebookApp] received signal 2, stopping[I 07:05:38.745 NotebookApp] Shutting down 0 kernelsuser@machine:~/collageradiomics$collageradiomics-pip Docker ImageBack toTable of ContentsThis is the most straightforward way to start playing with the code. And it does not require thegitcommands that theJupyterexamples require. This is simply a pre-built container that lets you start trying out the module inPythonimmediately.LinuxPull the latestDockerimage:user@machine:~$sudodockerpullradxtools/collageradiomics-pip:latestlatest: Pulling from radxtools/collageradiomics-pipDigest: sha256:8fc7d61dbe6ad64eeff9c69cfaa788d90c61861bff8aaf8865ed1318c5666250Status: Image is up to date for radxtools/collageradiomics-pip:latestdocker.io/radxtools/collageradiomics-pip:latestuser@machine:~/collageradiomics$Run theDockerimage:user@machine:~/collageradiomics$sudodockerrun-it-v$PWD:/rootradxtools/collageradiomics-piproot@12b12d2bff59:/#WindowsPull the latestDockerimage:Windows PowerShellCopyright (C) Microsoft Corporation. All rights reserved.Try the new cross-platform PowerShell https://aka.ms/pscore6PS C:\Users\user> docker pull radxtools/collageradiomics-pip:latestlatest: Pulling from radxtools/collageradiomics-pipd51af753c3d3: Already existsfc878cd0a91c: Already exists6154df8ff988: Already existsfee5db0ff82f: Already existse4255cf4d4f9: Downloading [=================>                                 ]  62.34MB/178.6MB14a983cf96b6: Downloading [===========================>                       ]  55.72MB/102.9MB14a983cf96b6: Pull completeDigest: sha256:8fc7d61dbe6ad64eeff9c69cfaa788d90c61861bff8aaf8865ed1318c5666250Status: Downloaded newer image for radxtools/collageradiomics-pip:latestdocker.io/radxtools/collageradiomics-pip:latestPS C:\Users\user>Run theDockerimage:Windows PowerShellCopyright (C) Microsoft Corporation. All rights reserved.Try the new cross-platform PowerShell https://aka.ms/pscore6PS C:\Users\user> docker pull radxtools/collageradiomics-pip:latestPS C:\Users\user> docker run -it radxtools/collageradiomics-piproot@461c5017ce0e:/#Inside The ContainerBack toTable of ContentsIf your terminal prompt changes toroot@[random_string]:/#then you are now working inside the standardizedDockersandbox container environment.Test the python module by making sure the following command outputsTrueto the terminal:root@12b12d2bff59:/#python-c'import numpy as np; import collageradiomics; print(not not len(collageradiomics.__name__) and not not len(collageradiomics.Collage.from_rectangle(np.random.rand(20,20,3), 2, 2, 10, 10).execute()));'Trueroot@12b12d2bff59:/#Starting coding withCoLlAGeinPython(click here to jump to code examples):root@12b12d2bff59:/#pythonPython 3.8.2 (default, Apr 27 2020, 15:53:34)[GCC 9.3.0] on linuxType "help", "copyright", "credits" or "license" for more information.>>> import collageradiomics>>> collageradiomics.__name__'collageradiomics'>>>Exit theDockercontainer:>>> quit()root@12b12d2bff59:/#exitexitPipBack toTable of ContentsTo use this module in your existingPythondevelopment environment, you can install ourpipmodule.LinuxInstallpip:user@machine:~$sudoapt-yinstallpython3-pipReading package lists... DoneBuilding dependency treeReading state information... Donepython3-pip is already the newest version (18.1-5).0 upgraded, 0 newly installed, 0 to remove and 0 not upgraded.user@machine:~$Install ourCoLlAGemodule:user@machine:~$pip3installcollageradiomics--upgradeCollecting collageradiomicsDownloading https://files.pythonhosted.org/packages/58/46/73d6b5a6d0d2b952086a1c9c4ae339087e4678f421044847ab2ea8728adf/collageradiomics-0.0.1a39-py3-none-any.whl...(some output omitted for brevity)...Successfully installed collageradiomics-...user@machine:~$(Note: For some operating systems, the command is simplypipinstead ofpip3.)WindowsInstallPythonusingthis link.Test thatPythonis properly installed in the Powershell:Windows PowerShellCopyright (C) Microsoft Corporation. All rights reserved.Try the new cross-platform PowerShell https://aka.ms/pscore6PS C:\Users\user> python --versionPython 3.8.2PS C:\Users\user> pythonPython 3.8.2 (tags/v3.8.2:7b3ab59, Feb 25 2020, 23:03:10) [MSC v.1916 64 bit (AMD64)] on win32Type "help", "copyright", "credits" or "license" for more information.>>> quit()PS C:\Users\user>Install pip by downloading thisget-pip.py fileand running the following command:Windows PowerShellCopyright (C) Microsoft Corporation. All rights reserved.Try the new cross-platform PowerShell https://aka.ms/pscore6PS C:\Users\user> python get-pip.pyCollecting pipDownloading pip-20.1.1-py2.py3-none-any.whl (1.5 MB)|████████████████████████████████| 1.5 MB 3.2 MB/sCollecting wheelUsing cached wheel-0.34.2-py2.py3-none-any.whl (26 kB)Installing collected packages: pip, wheelAttempting uninstall: pipFound existing installation: pip 20.0.2Uninstalling pip-20.0.2:Successfully uninstalled pip-20.0.2Successfully installed pip-20.1.1 wheel-0.34.2PS C:\Users\user> pip -Vpip 20.1.1 from c:\users\robto\appdata\local\programs\python\python38\lib\site-packages\pip (python 3.8)PS C:\Users\user>Install our moduleWindows PowerShellCopyright (C) Microsoft Corporation. All rights reserved.Try the new cross-platform PowerShell https://aka.ms/pscore6PS C:\Users\user> pip install collageradiomics --upgradeVerify its installation inPython:Windows PowerShellCopyright (C) Microsoft Corporation. All rights reserved.Try the new cross-platform PowerShell https://aka.ms/pscore6PS C:\Users\user> python>>> import collageradiomics>>>If you get an error like the one below, which can happen for some versions of python, callimportagain:Windows PowerShellCopyright (C) Microsoft Corporation. All rights reserved.Try the new cross-platform PowerShell https://aka.ms/pscore6PS C:\Users\user> python>>> import collageradiomicsCould not import submodules (exact error was: DLL load failed while importing _bbox: The specified module could not be found.).There are many reasons for this error the most common one is that you haveeither not built the packages or have built (using `python setup.py build`) orinstalled them (using `python setup.py install`) and then proceeded to testmahotas **without changing the current directory**.Try installing and then changing to another directory before importing mahotas.>>> import collageradiomics>>>Python UsageBack toTable of Contentscollageradiomics can be implemented inPythonthrough thecollageradiomicspip module. It has a intuitive interface - simply create aCollageobject and run theexecute()function.ContactBack toTable of ContentsPlease report any issues or feature requests via theIssuestabAdditional information can be found on theBrIC Labwebsite.