writing java documentation for T cell agents

src/arcade/patch/agent/cell/PatchCellCART.java

@@ -13,11 +13,11 @@
 import static arcade.patch.util.PatchEnums.State;
 
 /**
- * Implementation of {@link Cell} for generic CART cell.
+ * Implementation of {@link PatchCell} for generic CART cell.
  *
  * <p>{@code PatchCellCART} agents exist in one of thirteen states: neutral, apoptotic, migratory,
  * proliferative, senescent, cytotoxic (CD8), stimulatory (CD4), exhausted, anergic, starved, or
- * paused. The neutral state is an transition state for "undecided" cells, and does not have any
+ * paused. The neutral state is a transition state for "undecided" cells, and does not have any
  * biological analog.
  *
  * <p>{@code PatchCellCART} agents have two required {@link Process} domains: metabolism and
@@ -64,25 +64,49 @@ public abstract class PatchCellCART extends PatchCell {
     /** Cell activation flag */
     protected boolean activated;
 
-    /** lack of documentation so these parameters are TBD */
+    /** number of current PDL-1 receptors on CART cell */
     protected int selfReceptors;
 
+    /** initial number of PDL-1 receptors on CART cell */
     protected int selfReceptorsStart;
+
+    /** number of bound CAR antigens */
     protected int boundAntigensCount;
+
+    /** number of bound PDL-1 antigens */
     protected int boundSelfCount;
 
-    /** lack of documentation so these loaded parameters are TBD */
+    /** number of neighbors that T cell is able to search through */
     protected final double searchAbility;
 
+    /** binding affinity for CAR receptor */
     protected final double carAffinity;
+
+    /** tuning factor for CAR binding */
     protected final double carAlpha;
+
+    /** tuning factor for CAR binding */
     protected final double carBeta;
+
+    /** binding affinity for PDL-1 receptor */
     protected final double selfReceptorAffinity;
+
+    /** tuning factor for PDL-1 receptor binding */
     protected final double selfAlpha;
+
+    /** tuning factor for PDL-1 receptor binding */
     protected final double selfBeta;
+
+    /** fraction of cell surface that contacts when binding */
     protected final double contactFraction;
+
+    /** max antigens threshold for T cell exhaustion */
     protected final int maxAntigenBinding;
+
+    /** number of CARs on T cell surface */
     protected final int cars;
+
+    /** simulation time since T cell was last activated */
     protected int lastActiveTicker;
 
     /** Fraction of exhausted cells that become apoptotic. */
@@ -98,52 +122,38 @@ public abstract class PatchCellCART extends PatchCell {
     protected final double proliferativeFraction;
 
     /**
-     * Creates a tissue {@code PatchCellCART} agent. *
-     *
-     * <p>Loaded parameters include:
-     *
-     * <ul>
-     *   <li>{@code EXHAUSTED_FRACTION} = fraction of exhausted cells that become apoptotic
-     *   <li>{@code SENESCENT_FRACTION} = fraction of senescent cells that become apoptotic
-     *   <li>{@code ANERGIC_FRACTION} = fraction of anergic cells that become apoptotic
-     *   <li>{@code PROLIFERATIVE_FRACTION} = fraction of proliferative cells that become apoptotic
-     *   <li>{@code CAR_ANTIGENS} = Cell surface antigen count
-     *   <li>{@code SELF_TARGETS} = Cell surface PDL1 count
-     *   <li>{@code SEARCH_ABILITY} = TBD
-     *   <li>{@code CAR_AFFINITY} = TBD
-     *   <li>{@code CAR_ALPHA} = TBD
-     *   <li>{@code CAR_BETA} = TBD
-     *   <li>{@code SELF_RECEPTOR_AFFINITY} = TBD
-     *   <li>{@code SELF_ALPHA} = TBD
-     *   <li>{@code SELF_BETA} = TBD
-     *   <li>{@code CONTACT_FRACTION} = TBD
-     *   <li>{@code MAX_ANTIGEN_BINDING} = TBD
-     *   <li>{@code CARS} = TBD
-     *   <li>{@code SELF_RECEPTORS} = TBD
-     *   <li>{@code SELF_RECEPTORS_START} = TBD
-     * </ul>
-     *
-     * < THERE IS A LACK OF DOCUMENTATION FOR THE REST OF THE LOADED PARAMS SO THEY ARE TBD>
+     * Creates a {@code PatchCellCART} agent. *
      *
-     * @param id the cell ID
-     * @param parent the parent ID
-     * @param pop the cell population index
-     * @param state the cell state
-     * @param age the cell age
-     * @param divisions the number of cell divisions
+     * @param container the cell container
      * @param location the {@link Location} of the cell
      * @param parameters the dictionary of parameters
-     * @param volume the cell volume
-     * @param height the cell height
-     * @param criticalVolume the critical cell volume
-     * @param criticalHeight the critical cell height
      */
     public PatchCellCART(PatchCellContainer container, Location location, Parameters parameters) {
         this(container, location, parameters, null);
     }
 
     /**
-     * Creates a tissue {@code PatchCell} agent with population links.
+     * Creates a {@code PatchCellCART} agent. *
+     *
+     * <p>Loaded parameters include:
+     *
+     * <ul>
+     *   <li>{@code EXHAU_FRACTION} = fraction of exhausted cells that become apoptotic
+     *   <li>{@code SENESCENT_FRACTION} = fraction of senescent cells that become apoptotic
+     *   <li>{@code ANERGIC_FRACTION} = fraction of anergic cells that become apoptotic
+     *   <li>{@code PROLIFERATIVE_FRACTION} = fraction of proliferative cells that become apoptotic
+     *   <li>{@code SELF_RECEPTORS} = current number of PDL-1 receptors on cell surface
+     *   <li>{@code SEARCH_ABILITY} = number of neighbors that T cell can search through
+     *   <li>{@code CAR_AFFINITY} = CAR receptor binding affinity
+     *   <li>{@code CAR_ALPHA} = tuning factor for CAR binding
+     *   <li>{@code CAR_BETA} = tuning factor for CAR binding
+     *   <li>{@code SELF_RECEPTOR_AFFINITY} = PDL-1 receptor binding affinity
+     *   <li>{@code SELF_ALPHA} = tuning factor for PDL-1 receptor binding
+     *   <li>{@code SELF_BETA} = tuning factor for PDL-1 receptor binding
+     *   <li>{@code CONTACT_FRAC} = fraction of surface area that contacts target cell when binding
+     *   <li>{@code MAX_ANTIGEN_BINDING} = maximum bound antigen count for T cell exhaustion
+     *   <li>{@code CARS} = number of CAR receptors on the cell
+     * </ul>
      *
      * @param container the cell container
      * @param location the {@link Location} of the cell
@@ -179,15 +189,14 @@ public PatchCellCART(
         cars = parameters.getInt("CARS");
     }
 
-    /* need to implement bindTarget equivalent here*/
     /**
      * Determines if CAR T cell agent is bound to neighbor through receptor-target binding.
      *
      * <p>Searches the number of allowed neighbors in series, calculates bound probability to
      * antigen and self receptors, compares values to random variable. Sets flags accordingly and
      * returns a target cell if one was bound by antigen or self receptor.
      *
-     * @param state the MASON simulation state
+     * @param sim the MASON simulation
      * @param loc the location of the CAR T-cell
      * @param random random seed
      */
@@ -297,7 +306,7 @@ public PatchCellTissue bindTarget(
     /**
      * Sets the cell binding flag.
      *
-     * @param antigenFlag the target cell antigen binding state
+     * @param flag the target cell antigen binding state
      */
     public void setAntigenFlag(AntigenFlag flag) {
         this.binding = flag;
@@ -312,7 +321,11 @@ public AntigenFlag getAntigenFlag() {
         return this.binding;
     }
 
-    /** Returns activation status */
+    /**
+     * Returns the cell activation status
+     *
+     * @return the activation status
+     */
     public boolean getActivationStatus() {
         return this.activated;
     }

src/arcade/patch/agent/cell/PatchCellCARTCD4.java

@@ -16,32 +16,25 @@
 public class PatchCellCARTCD4 extends PatchCellCART {
 
     /**
-     * Creates a tissue {@code PatchCellCARTCD4} agent. *
+     * Creates a T cell {@code PatchCellCARTCD4} agent. *
      *
-     * <p>Loaded parameters include:
-     *
-     * <ul>
-     *   <li>{@code STIMULATORY_FRACTION} = fraction of stimulatory cells that become apoptotic
-     * </ul>
-     *
-     * @param id the cell ID
-     * @param parent the parent ID
-     * @param pop the cell population index
-     * @param state the cell state
-     * @param age the cell age
-     * @param divisions the number of cell divisions
+     * @param container the cell container
      * @param location the {@link Location} of the cell
      * @param parameters the dictionary of parameters
-     * @param volume the cell volume
-     * @param height the cell height
-     * @param criticalVolume the critical cell volume
-     * @param criticalHeight the critical cell height
      */
     public PatchCellCARTCD4(
             PatchCellContainer container, Location location, Parameters parameters) {
         this(container, location, parameters, null);
     }
 
+    /**
+     * Creates a T cell {@code PatchCellCARTCD4} agent. *
+     *
+     * @param container the cell container
+     * @param location the {@link Location} of the cell
+     * @param parameters the dictionary of parameters
+     * @param links the map of population links
+     */
     public PatchCellCARTCD4(
             PatchCellContainer container, Location location, Parameters parameters, GrabBag links) {
         super(container, location, parameters, links);
@@ -146,15 +139,14 @@ public void step(SimState simstate) {
                     } else {
                         // if CD4 cell is properly activated, it can stimulate
                         super.setState(State.STIMULATORY);
-                        // reset the cell
                         this.lastActiveTicker = 0;
                         this.activated = true;
                         if (target.isStopped()) {
                             target.binding = (AntigenFlag.UNBOUND);
                         }
                         target.setState(State.QUIESCENT);
                         this.binding = AntigenFlag.UNBOUND;
-                        // need to reset
+                        // reset the cell
                         PatchActionReset reset =
                                 new PatchActionReset(
                                         this,

src/arcade/patch/agent/cell/PatchCellCARTCD8.java

@@ -16,43 +16,33 @@
 
 public class PatchCellCARTCD8 extends PatchCellCART {
     /**
-     * Creates a tissue {@code PatchCellCARTCD8} agent. *
+     * Creates a T cell {@code PatchCellCARTCD8} agent. *
      *
-     * <p>Loaded parameters include:
-     *
-     * <ul>
-     *   <li>{@code CYTOTOXIC_FRACTION} = fraction of cytotoxic cells that become apoptotic
-     * </ul>
-     *
-     * @param id the cell ID
-     * @param parent the parent ID
-     * @param pop the cell population index
-     * @param state the cell state
-     * @param age the cell age
-     * @param divisions the number of cell divisions
+     * @param container the cell container
      * @param location the {@link Location} of the cell
      * @param parameters the dictionary of parameters
-     * @param volume the cell volume
-     * @param height the cell height
-     * @param criticalVolume the critical cell volume
-     * @param criticalHeight the critical cell height
      */
     public PatchCellCARTCD8(
             PatchCellContainer container, Location location, Parameters parameters) {
         this(container, location, parameters, null);
     }
 
+    /**
+     * Creates a T cell {@code PatchCellCARTCD8} agent. *
+     *
+     * @param container the cell container
+     * @param location the {@link Location} of the cell
+     * @param parameters the dictionary of parameters
+     * @param links the map of population links
+     */
     public PatchCellCARTCD8(
             PatchCellContainer container, Location location, Parameters parameters, GrabBag links) {
         super(container, location, parameters, links);
     }
 
     @Override
     public PatchCellContainer make(int newID, CellState newState, MersenneTwisterFast random) {
-
         divisions--;
-        // return new PatchCellCARTCD8(newID, id, pop, newState, age, divisions, newLocation,
-        //     parameters, volume, height, criticalVolume, criticalHeight);
         return new PatchCellContainer(
                 newID,
                 id,
@@ -146,11 +136,10 @@ public void step(SimState simstate) {
                         super.setAntigenFlag(AntigenFlag.UNBOUND);
                         this.activated = false;
                     } else {
-                        // if CD4 cell is properly activated, it can stimulate
+                        // if CD8 cell is properly activated, it can be cytotoxic
                         this.lastActiveTicker = 0;
                         this.activated = true;
                         super.setState(State.CYTOTOXIC);
-                        // need to call kill
                         PatchActionKill kill =
                                 new PatchActionKill(
                                         this,
@@ -159,7 +148,7 @@ public void step(SimState simstate) {
                                         ((PatchSimulation) simstate).getSeries(),
                                         parameters);
                         kill.schedule(sim.getSchedule());
-                        // need to reset
+                        // cell resets after binding
                         PatchActionReset reset =
                                 new PatchActionReset(
                                         this,

src/arcade/patch/agent/cell/PatchCellTissue.java

@@ -14,15 +14,6 @@
 
 /** Extension of {@link PatchCell} for healthy tissue cells. */
 public class PatchCellTissue extends PatchCell {
-    // /** Fraction of necrotic cells that become apoptotic. */
-    // private final double necroticFraction;
-
-    // /** Fraction of senescent cells that become apoptotic. */
-    // private final double senescentFraction;
-
-    // these two variables are public bc I don't want to implement setter/getter methods for sims
-    // that do not use CART cells.
-
     /** Cell surface antigen count */
     int carAntigens;
 
@@ -76,8 +67,6 @@ public PatchCellContainer make(int newID, CellState newState, MersenneTwisterFas
                 criticalHeight);
     }
 
-    /* consider making PatchCell parameters protected instead of private */
-
     @Override
     public void step(SimState simstate) {
         Simulation sim = (Simulation) simstate;