config.yml

# Configuration template file for CellscannerCLI v2.0.0
# In this template, we use the test case (input files) under /Testfiles, assuming we have saved them locally
# on our computer, under ~/software/Cellscanner

# ---------------------
# Import data
# ---------------------
output_directory:
  path: CellScanner/cs_output
  required: false
  description: >
    Directory where CellScanner will save intermediate files and findings.
    If Docker is being used, this will automatically point to the mounted /media directory.
    However, if you are running CellScanner as a Docker, please make sure you mount the directory path to the `/media` folder of the container.
  default: Directory where CellscannerCLI.py is located.
  type: str

blank_files:
  directories:
    - directory:
        path: CellScanner/CS2TutorialFiles
        filenames:
          - 01-t12_d50_wc_btri_control-H7.fcs
          - 01-t12_d50_wc_btri_control-H8.fcs
  required: true
  description: >
    In the `path` provide the directory where blanks are located.
    If no `path` is provided, CellScanner will fail.
    Under `filenames`, provide the filenames of the blank files. 
    If no filenames are provided, CellScanner will assume that any .fcs file under the `path` is a blank.
    Example: docker run -v ~/software/CellScannerApp/Testfiles/:/media cellscanner
    You can use both relative paths and paths based on the home directory (~).

species_files:
  directories:
    - directory:
        path: CellScanner/CS2TutorialFiles
        filenames:
          - 01-t12_d50_wc_btA-D1.fcs
          - 01-t12_d50_wc_btB-D2.fcs
          - 01-t12_d50_wc_btC-D3.fcs
          - 01-t12_d50_wc_riA-D4.fcs
          - 01-t12_d50_wc_riB-D5.fcs
          - 01-t12_d50_wc_riC-D6.fcs
        species_names:
          - BT
          - BT
          - BT
          - RI
          - RI
          - RI
  required: true
  description: >
    Provide files to be used for the training of the model. 
    If your files are under different pathways, you may add as many `directory` entries as you wish.
    A directory needs to have all `path`, `filenames` and `species_names`.
    Important! Species names need to be in the same order as the filenames so CellScanner can map correctly which species is described by each file.
    You can use both relative paths and paths based on the home directory (~).

coculture_files:
  directories:
    - directory:
        path: CellScanner/CS2TutorialFiles
        filenames:
          - 01-t12_d50_wc_btriA-D7.fcs
          - 01-t12_d50_wc_btriB-D8.fcs
          - 01-t12_d50_wc_btriC-D9.fcs
  required: true
  description: >
    Provide the coculture files you wish to classify. 
    You may have as many `file_path` entries as you wish; each `file_path` stands for a certain `path` and for each, you may specify certain co-culture .fcs files of your interest.
    If a `path` has no `filenames`, all .fcs files in the `path` will be used.
    You can use both relative paths and paths based on the home directory (~).

prev_trained_model:
  path:
  required: false
  default:
  description: >
    (optional)
    In case you want to use a previously trained model, you may provide the path to its files.
    Make sure that the path provided includes all the following 3 files: 
    - trained_model.keras
    - scaler.pkl
    - label_encoder.pkl
    If any of these files is missinge, CellScanner will fail.
    Attention! When a previous model is used, you need to make sure you provide the scaling_constant you used to train the model.
  type: str

# ---------------------
# Training parameters
# ---------------------
umap_events:
  value: 1000
  required: false
  default: 1000
  description: >
    Select number of random events to be selected from each species data to be used for the training of the model with UMAP
  type: int

n_neighbors:
  value: 50
  required: false
  default: 50
  description: >
    The size of the local neighborhood UMAP will look at when attempting to learn the manifold structure of the data.
    https://umap-learn.readthedocs.io/en/latest/parameters.html#n-neighbors
  type: int

umap_min_dist:
  min_dist: 0.0
  required: false
  default: 0.0
  description: >
    How tightly UMAP is allowed to pack points together. Up to 0.99
  type: float

scaling_constant:
  value: 150
  required: false
  default: 150
  description: >
    Value
  type: int

nn_blank:
  value: 20
  required: false
  default: 20
  description: >
    "Neighbor threshold:"
  type: int

nn_non_blank:
  value: 25
  required: false
  default: 25
  description: >
    "Neighbor threshold (non-Blank):"
  type: int

folds:
  value: 0
  required: false
  default: 0
  description: >
    CellScanner uses the StratifiedKFold() scikit-learn feature to implement cross-validation.
    Here, you need to set the number of splitting iterations (train/test sets) in the cross-validator.
  type: int

epochs:
  value: 50
  required: false
  default: 50
  description: >
    Number of epochs to train the model. An epoch is an iteration over the entire x and y data provided.
    The model is not trained for a number of iterations given by epochs, but merely until the epoch of index epochs is reached.
    See https://www.tensorflow.org/api_docs/python/tf/keras/Sequential#fit
  type: int

batch_size:
  value: 32
  required: false
  default: 32
  description: >
    Number of samples per gradient update.
  type: int

early_stopping_patience:
  value: 10
  required: false
  default: 10
  description: >
    Early stopping is a form of regularization used to avoid overfitting when training 
    a model with an iterative method. In CellScanner's implementation, we monitor the value of the 
    accuracy. Patience stands for the mumber of epochs with no improvement after which training will be stopped.
    For more: https://www.tensorflow.org/api_docs/python/tf/keras/callbacks/EarlyStopping
  type: int

# ---------------------
# Prediction parameters
# ---------------------
x_axis:
  name:
  required: false
  default: First column as in the coculture file.
  desription: >
    The first channel of the coculture data to be used in the 3D plot.
  type: str

y_axis:
  name:
  required: false
  default: First column as in the coculture file.
  desription: >
    The second channel of the coculture data to be used in the 3D plot.
  type: str

z_axis:
  name:
  required: false
  default: First column as in the coculture file.
  desription: >
    The third channel of the coculture data to be used in the 3D plot.
  type: str

filter_out_uncertain:
  value: false
  threshold: 0.5
  required: false
  default: false
  description: >
    Set true in case you wish to filter out uncertain predictions. 
    In case you wish to filter out uncertain predictions, an uncertainty threshold is required.
    Uncertainties are predicted using Shannon entropy and thus, the maximum entropy is log(number_of_classes).
    Therefore, threshold may range from 0 to log(number_of_classes) and the lower the threshold, the stricter the filtering, 
    the more uncertain predictions will be filtered out (assigned as Unknown).
    You may set this value with one of the following ways:
    - set any value between 0 and log(number_of_classes)
    - set it to -1 and CellScanner will compute the generally used 0.5 threshold of the maximum entropy, and will use this as the threshold
    - set its value as `true` and leave the `threshold` parameter empty. In this case, CellScanner will automatically set the threshold 
    to the one that returns the maximum accuracy on your training set.
  type: bool

# ---------------------
# Gating parameters
# ---------------------
gating:
  value: true
  required: false
  default: false
  description: >
    Set whether you wish data to be gated or not.
  type: bool

#   -------------------------      For all stains     -------------------------
#
# To enable gating, you need to provide at least one `Stain` which requires three parameters:
# - channel (str): takes values the exact name of a column in the coculture file.
# - sign (str): can be either `greater_than` or `less_than`, mentioning whether the channel needs to have a value
#          higher or lower from the one you are about to set as threshold.
# - value (int): the threshold of the stain.
#
# IMPORTANT: Some visualization software may transform raw data.  !!
# Ensure you set the threshold based on the raw data, not post-transformation.
#
# Gating can be applied in both training model step, to "filter" the entries used from the blanks and the monoculture s
# but also in the prediction step.
# CellScanner allows you to have different values for the two steps, but using different values is considered an advance use for experts.
#
# Last, for the prediction step, you may also apply as many line gating filters as you wish by simply adding stains in the extra_stains
#
#  - stain:
#     channel:
#     sign:
#     value:
#     label:
#

stain1_train:
  channel: FITC-A
  sign: greater_than
  value: 2000000
  required: false
  sign_values:
    - greater_than
    - less_than
  description: >
    This stain specifically marks dead cells; 
    Any event meeting the threshold will be classified as `dead`.
  type: Stain

stain2_train:
  channel: PerCP-H
  sign: greater_than
  value: 500000
  description: >
    This stain specifically describes total cells; 
    all events where the threshold is met will be classified as `cells`. The rest of the events will be classified as `debris`.
  required: false
  type: Stain

stain1_predict:
  channel: FITC-A
  sign: greater_than
  value: 2000000
  required: false
  description: >
    This stain specifically marks dead cells; 
    Any event meeting the threshold will be classified as `dead`.
  type: Stain

stain2_predict:
  channel: PerCP-H
  sign: greater_than
  value: 500000
  required: false
  description: >
    This stain specifically describes total cells; 
    all events where the threshold is met will be classified as `cells`. The rest of the events will be classified as `debris`.
  type: Stain

extra_stains:
  stains:
    - stain:
      channel:
      sign:
      value:
      label:
  required: false
  description: >
    If you would like to apply further/other stains, please provide the 3 required parameters for each.
    In case you would like to have several, just copy-paste the `-stain` entry and the following 3 lines, as many times as you wish
    and fill in the relative information for each stain.
  type: list of Stain