palmettobug.Entrypoint.bead_norm
================================

.. py:module:: palmettobug.Entrypoint.bead_norm

.. autoapi-nested-parse::

   This module contains the functions that handles bead normalization of CyTOF solution mode data. One function ( CyTOF_bead_normalize() )
   is available in the public (non-GUI) API of PalmettoBUG, so the others are really more private / helper functions for that.


   While the PalmettoBUG project as a whole is licensed under the GPL3 license, including this file, portions of this file
   are derived / translated from Premessa / Cytof-Normalization packages::

       https://github.com/nolanlab/bead-normalization   &   https://github.com/ParkerICI/premessa

   Which were also GPL3 licensed. 

   Neither of the above listed packages provide copyright statements (author / date of copyright). 
   Premessa was written by Pier Federico Gherardini.

   In particular, the mathematical operations / algorithm itself was directly translated from Premessa (which is written in R) into Python,
   including the finding of rolling medians, slopes, and then interpolating to normalize. 

   see Assets / Other_License_Details.txt for more information on 3rd-party sources of code / ideas in this package.



Functions
---------

.. autoapisummary::

   palmettobug.Entrypoint.bead_norm.CyTOF_bead_normalize


Module Contents
---------------

.. py:function:: CyTOF_bead_normalize(bead_fcs_folder: str, to_normalize_fcs_folder: str, output_folder: str, bead_channels: list, channels_to_normalize: Union[list, None] = None, include_figures: bool = True) -> None

   This function performs the Premessa-style CyTOF normalization of the function above (normalize_pipeline_one_fcs) on all the FCS files 
   in a pair of beads / non-beads folders.

   Args:
       bead_fcs_folder (str | Pathlike): 
           file path to a directory containg fcs files of only beads

       to_normalize_fcs_folder (str | Pathlike): 
           file path to a directory containg fcs files that you want to be normalized. Usually 
           the non-beads, live, singlets (already gated in a program like FlowJo)

       output_folder (str | Pathlike): 
           file path to a directory where you want the normalized fcs' and figures will be written. Will 
           attempt to create the directory if it does not exist 

       bead_channels (list): 
           a list of the columns (i.e., metal channel / antigen) in the beads that will be used to calculate the slopes for normalization

       channels_to_normalize (list | None): 
           a list of the columns (i.e., metal channel / antigen) that will be normalized for analysis. 
           If None is passed in, will automatically try to detect all metal channels by looking for the 
           following regex: 

                   r".+Di"

           It is best to explicitly define the channels to normalize, as this regex may not capture the channels in your data successfully! 

       include_figures (bool): 
           whether to export figures of the normalization (True) or not (False)

   Returns:
       None

   Inputs/Outputs:
       Inputs: 
           reads in two folders, specified by bead_fcs_folder & to_normalize_fcs_folder, containing data from a CyTOF experiment
           with only beads remaining in bead_fcs_folder (non-beads gated out)) and with the events to nomalize in to_normalize_fcs_folder. 
           Normally, the to_normalize_fcs_folder .fcs files would be gated to exclude beads / dead cells, which would be more computationally
           efficient, but technically that isn't necessary as long as those are gated out afterwards. 
           Each folder should contain .fcs files and ONLY .fcs files.
           
           NOTE: It is assumed that the order of the files in each folder match (as in, the first file in os.listdir(bead_fcs_folder) are 
           the matching beads from the first file in os.listdir(to_normalize_fcs_folder))

       Outputs: 
           Outputs normalized beads .fcs files to output_folder/normalized_beads folder and normalized non-beads .fcs files to
           output_folder/normalized folder. The files in the output folders should match the same filenames as the two input folders.
           Additionally, if include_figures is True -- will export plots of the normalization to the output_folder/normalization_figures
           folder (as PNG files).