Metadata-Version: 2.1
Name: hundlab-AFAT
Version: 2.0.0
Summary: Automated Fibrosis Analysis Toolkit: A tool to quantify the amount of fibrosis in Masson’s Trichrome stains
Home-page: https://github.com/hundlab/MAT
Author: Daniel Gratz
Author-email: hund.1@osu.edu
License: UNKNOWN
Description: # Automated Fibrosis Analysis Toolkit (AFAT)
        
        *This tool was documented in [our paper](http://doi.org/10.1016/j.mex.2019.11.028) on marcophage and fibrosis quantification*
        
        *Hundlab Website: [hundlab.org](http://hundlab.org/)*
        
        *PyPI: [pypi.org/project/hundlab-AFAT](https://pypi.org/project/hundlab-AFAT/)*
        
        *Github: [github.com/hundlab/MAT](https://github.com/hundlab/AFAT)*
        
        ## Setup
        
        ### Windows
        
        1. Python 3 will need to be installed prior to setting up AFAT, preferably any python
            greater than 3.7. Python 3 can be downloaded from the [python website](http://python.org).
            The x86-64 executable installer is reccommended, as the default install configuration 
            will set python to open .py files by double clicking. If it is installed correctly opening
            cmd or powershell window and typing `py --version` will print the installed python
            version.
        
        2.  Install AFAT by opening a cmd or powershell window and running
            `py -m pip install hundlab-AFAT`, this should install AFAT and all of its dependancies.
        
        3.  Once AFAT has been installed it can be run via cmd, powershell or the start menu. To run
             type `AutomatedFibrosisAnalysisToolkit.py`. To create a desktop shortcut type
             `AutomatedFibrosisAnalysisToolkit.py` into the start menu select `Copy full path`, then on the 
             Desktop `right-click` -> `new` -> `new shortcut` and paste the path when it askes for a
             path.
        
             If AFAT does not run above as described this means that the python scipts directory has
             not been added to the windows path. To find the install location of python type 
             `py -0p` this will give the location of the python executable. In the same directory
             as python.exe, is a Scripts directory and the `AutomatedFibrosisAnalysisToolkit.py` will
             be in there. Once the AFAT script has been found, a shortcut can be made to it directly
             and placed on the desktop.
        
        After installation, the `ConfigureColorRules.py` tool can be run in the same manner as AFAT.
        
        *Note that it may take a few seconds for AFAT to start.*
        
        ### Mac/Linux
        
        1. Python 3 will need to be installed prior to setting up AFAT. Python 3 can be 
            installed via your package manager in linux, or downloaded from python.org for mac.
            If it is installed correctly opening a terminal and typing `python --version` (in some 
            distributions such as Ubuntu the command is `python3`) should start a python prompt. It 
            may also be necessary to install Tkinter. On unbuntu the package is `python3-tk`.
        
        2. Install AFAT using pip: `python -m pip install hundlab-AFAT`
        
        3. To run AFAT use the command `AutomatedFibrosisAnalysisToolkit.py`
        
        After installation, the `ConfigureColorRules.py` tool can be run in the same manner as AFAT.
        
        ## Usage
        
        ### Version 1.0 
        
        Our paper on AFAT and MAT outline the general usage instructions and processing steps that AFAT uses
        to quantify the fibrosis and tissue content in each image. This is still an excellent starting point
        for anyone new to using AFAT. Further, see the changes and instructions below for version 2.0.
        
        ### Version 2.0
        
        There were two primary aims in updating AFAT:
        
        1. To reduce the memory usage of AFAT. This goal arose from the need to processes more detailed images
           of large sections of tissue as our lab equipment has improved. AFAT now uses around 4Gb of RAM for
           a 500Mb image (8bit color only).
        
        2. To make configuring AFAT more user friendly. To this aim we have added an easier to use interface
           for running simulations that no longer requires editing python files. Further, we have added
           a configuration tool, that allows the color profiles to be retuned to account for differences
           between stainings, or changed entirely to allow for different types of staining altogether.
        
        ### Automated Fibrosis Analysis Toolkit
        
        ![Image AFAT configure and run](./images/AFAT_configure_run.PNG)
        
        This is the new configuration panel to select all of the inputs needed for AFAT to run the analysis.
        First, using `Choose Images` select any images you want to be analyzed in one batch. No special per
        batch processing is done, so the results will be equivalent if the images are run separately or in a
        batch, however it is likely more convenient to configure the analysis once, and then run it on all the
        images of interest. In regards to aim 1 of version 2.0, each image is loaded separately so that
        the overall memory usage is minimized. Second, use `Choose Save File` to select an output csv file
        to contain all of the results from the analysis (pixel counts from each step and final percentage
        stain out of stain and tissue). I typically create a new folder and save the csv file in there, so
        that all of the results of the simulation are together in one folder. The next button, 
        `Choose Save Directory`, selects the directory where the image files showing the final color
        mask for tissue, stain, background and other/unclassified will be saved. In addition to the image
        files, new with version 2.0 the settings that were used (including the color profiles) will be saved
        in that directory as well.
        
        The color rules file and settings files are the detailed configuration for each analysis. A new tool
        for creating your own color rules file will be documented below. Using this file you can change the colors
        that AFAT will detect as tissue, stain or background. When an analysis is run, the settings will be saved
        (including the color rules) in a `settings.yaml` file. These settings can then be used by a latter analysis
        on new images, or to redo the analysis on existing images.
        
        *Note: There is some randomness in the analysis that may result in multiple runs of the same image yeilding
        slightly different results.*
        
        The check boxes at the bottom allow for control over what is saved an shown to the user. `Show Images` is not
        checked by default, as showing the diagnostic images from each analysis may use a large amount of memory, when
        these images can be saved to be viewed latter.
        
        ### Configure Color Rules
        
        ![Image Configuration menu for color rules](./images/color_rules_configure.PNG)
        
        This is the main configuration menu for customizing the color rules. The configuration uses the HSV colorspace with all values being between 0 and 255. More information on HSV can be found online, but briefly: H refers to
        hue, the color; S refers to saturation, the intensity of the color (0 being no color/gray, 255 being intense/rich color); and V is called value, which is also related to color intensity with 0 being black and 255 being intense/rich color. Together S and V define color vs white vs black vs gray. Initially the default rules are loaded
        . These rules may be changed and new values may be added by filling in both blanks in for H, S or V. Similarly,
        existing rules may be removed by deleting the entries in both blanks. When making changes be sure to deselect
        the number entry box for your change to be applied (this will also be reflected in a status update in the
        bottom left-hand corner of the window).
        
        ![Image Configuration display for color rules](./images/color_rules_view.jpg)
        
        An image may be loaded using the file menu on the main configuration window. The loaded image will show up in
        this secondary viewing window with additional information about the color rules. First, the bottom left-hand
        status bar displays information on the pixel the mouse is hovering over. Specifically, in the green
        highlighted section the HSV values are displayed as well as which category that pixel would be classified
        as (using only the color rules and not the full AFAT analysis). This can be helpful for examining the normal
        range of colors that different sections of the image take on. It is not necessary that every pixel is
        classified by the color rules, but rules should capture the majority of their intended targets without
        capturing unintended targets. Sometimes it is not easy to create a rule that excludes all of the undesired
        pixels, in which case it may be beneficial to crop or edit out parts of the image prior to analysis. 
        
        In the top right-hand icon bar, highlighted in red, are toggle buttons to show the boundaries of each section
        type. These can be useful for finding regions of the image which were not categorized correctly. Note: once
        toggled they may use up a relatively large amount of memory.
        
        Once color rules have been defined, they may be saved using the file menu on the main configuration window.
        
        ## Advanced Usage
        
        This section details the two settings files used by AFAT: `settings.yaml` and `color_rules.yaml`. While these
        two files are show separately, they can be combined into the settings file.
        
        ### Settings file
        
        ```yaml
        ###############################################################################
        # k neighbors classifier settings
        ## this is the second pass which attempts to classify pixes missed in the first
        ## pass into blue, red, or unidentifiable.
        
        #raw settings for KNeighborsClassifier
        #see https://scikit-learn.org/stable/modules/generated/sklearn.neighbors.KNeighborsClassifier.html#sklearn.neighbors.KNeighborsClassifier
        KNN:
          raw:
            n_neighbors: 5
            n_jobs: -1
        
        # minimum fraction of neighbors with the same label needed to classify a pixel
        #default 1 or 100% of neighbors must be the same
          min_consensus: 0.8
        
        
        # These settins control the maximum number of pixels to be used by KNN
        # so if there are more pixels in the image than max_pixels only max_pixel
        # number of pixels will be used
          max_pixels: 10_000_000
        
        # The pixels are resampled so that there are fixed fractions of each group
        # the fraction of background to be used will be calcuated by 
        # 1 - frac_stain - frac_tissue
          frac_stain: 0.375
          frac_tissue: 0.375
        
        
        ###############################################################################
        # other settings
        
        # save mask images to a directory
        save_images: True
        
        # show image plots
        show_images: False
        
        # save settings yaml file with analysis
        # will be saved in the same location as the csv data file
        save_settings: True
        ###############################################################################
        ```
        
        Of primary interest in the settings file is the KNN settings. The `raw` settings
        will be passed directly to the KNN constructor and can configure most aspects
        of the classifier itself. At the moment, the two options specified are 
        `n_neighbors` and `n_jobs`, which control the number of already classified pixels
        to be used to classify an unknown/other pixel and the number of threads KNN should
        use, respectively. The `min consensus` setting specifies a threshold for the number
        of neighbors which must agree in order for the pixel to be classified. (Given that
        we are using 5 neighbors the number of agreeing neighbors will be one of 1/5... 5/5).
        If consensus is set to 0, then all unknown/other pixels will be classified based
        one the plurality of their neighbors.
        
        The `max_pixels` settings controls the maximum number of pixels to be used to train
        the KNN. This is set to prevent AFAT from using excessive memory, or computational
        time. If the total number of pixels in the image is less than `max_pixels` only that
        number of pixels will be used to train the KNN. The `frac_stain` and `frac_tissue`
        control the fraction of training pixels which are from each group. White pixels make
        up the rest of the training group, frac_white = 1 - frac_stain - frac_tissue. This
        means that if there are not enough pixels from a particular group (usually this is
        true for the stain group) they will be resampled (duplicated) until enough pixels
        are available. Briefly, this is desirable as stain is often underrepresented and
        over sampling can help to ensure that unknown pixels have a change of being classified
        as stain.
        
        ### Color Rules file
        
        ```yaml
        color_rules:
          background:
            S:
            - - 0
              - 15
            V:
            - - 192
              - 255
          tissue:
            H:
            - - 199
              - 255
            - - 0
              - 50
            S:
            - - 26
              - 255
          stain:
            H:
            - - 148
              - 183
            S:
            - - 40
              - 255
            V:
            - - 0
              - 150
        
        ```
        
        Color rules can be specified manually by editing the color rules file. Like when using
        the configuration tool, they are specified using ranges in the HSV colorspace.
        
Platform: UNKNOWN
Description-Content-Type: text/markdown
