parameters can now be constrained in range (fixtop, fixbottom, `f…

…ixslope`) (#35) * report slope in per-replicate serum titers * require `fixslope` in `curvefit_params` * add `fixslope` to test config * implement `fixslope`
jbloomlab · Mar 26, 2024 · d14467f · d14467f
1 parent 684233e
commit d14467f
Show file tree

Hide file tree

Showing 33 changed files with 1,935 additions and 1,967 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,7 +1,10 @@
 # CHANGELOG
 
 ## version 3.0.0
-- Update `seqneut-pipeline` conda environment in `environment.yml`. Use new `neutcurve`, also update other packages (`pandas`, `snakemake`, `markdown`, `papermill`) to latest versions.
+- In the `curvefit_params`, now `fixslope` should be specified in addition `fixtop` and `fixbottom`. In addition, all three of these can be set to constraint ranges rather than just totally free or to fixed values. Alongside this change, the slope of curve fits are now reported in key output files. Addresses [this issue](https://github.com/jbloomlab/neutcurve/issues/53) and [this issue](https://github.com/jbloomlab/seqneut-pipeline/issues/32).
+  - This is a **backward-incompatible change** in the configuration YAML, now you must specify `fixslope` under `curvefit_params`.
+
+- Update `seqneut-pipeline` conda environment in `environment.yml`. Update `neutcurve` 2.0.0, also update other packages (`pandas`, `snakemake`, `markdown`, `papermill`) to latest versions.
 
 ### version 2.2.0
 - Add the `add_htmls_to_docs` option, which can be specified in `Snakefile` to add additional HTML documentation to pipeline.

diff --git a/README.md b/README.md
@@ -340,17 +340,23 @@ The default can be defined like this:
 ```
 default_process_plate_curvefit_params: &default_process_plate_curvefit_params
   frac_infectivity_ceiling: 1
-  fixtop: false
+  fixtop: [0.75, 1.0]
   fixbottom: 0
+  fixslope: [0.8, 5]
 ```
 
 The specific meaning of these curve-fitting parameters are as follows:
 
  - `frac_infectivity_ceiling`: ceiling to apply to all fraction infectivities before fitting curves. You may want to this to one to put a ceiling on all values >1. In principle, no values should be >1 in the absence of experimental noise.
 
- - `fixtop`: fix the top plateau of the neutralization curve. Typically you might either set to 1, or "false" if you want to let the top be a free parameter. In general, "false" is recommended.
+ - `fixtop`: how to set the top plateau of the neutralization curve. You can set it to:
+   - A list of length two specifying a reasonable range, such as `[0.75, 1.0]`, in which case the top is optimized within that range. **This is typically the recommended setting.**
+   - A fixed value to fix to a specific number, typically 1. This is recommended if you want to force all curves to have a top plateau of one.
+   - The value `false` if you want it to be a totally free parameter. This is not recommended as you can sometimes get spurious fits of a very large value when the data don't capture fully neutralization.
 
- - `fixbottom`: fix the bottom plateau of the neutralization curve to this value. Typically it should be 0 unless you have a good reason otherwise; set to "false" to make it a free parameter.
+ - `fixbottom`: how to set the bottom plateau of the neutralization curve to this value. Like `fixtop`, it can be a length-two list, a fixed value, or `false`. Typically you should set it to 0 unless you have a good reason otherwise.
+
+ - `fixslope`: how to set the slope of the neutralization curve. Like `fixtop`, it can be a length-two list, a fixed value, or `false`. If you don't know the "slope" of the neutralization curve, setting to `false` is a reasonable choice. However, in many cases it is preferable to set to a range that encompasses "reasonable" slopes. Note that what is "reasonable" will depend on the units of the concentration, but when they are serum dilutions a "reasonable" range is often `[0.8, 5]`.
 
 #### curvefit_qc
 This key defines some parameters on quality-control performed after the curve-fitting; viral-barcode / serum-replicate combinations that fail this QC are dropped.
@@ -359,15 +365,15 @@ You typically want to use the [YAML anchor/merge](https://ktomk.github.io/writin
 The default can be defined like this:
 ```
 default_process_plate_curvefit_qc:  &default_process_plate_curvefit_qc
-  max_frac_infectivity_at_least: 0.5
+  max_frac_infectivity_at_least: 0
   min_R2: 0.75
   serum_replicates_ignore_curvefit_qc: []
   barcode_serum_replicates_ignore_curvefit_qc: []
 ```
 
 The specific meanings of these QC parameters are:
 
- - `max_frac_infectivity_at_least`: drop any viral-barcode / serum-replicate combination that does not have a maximum frac infectivity across all concentrations of at least this value. Typically you might want to set a value >0.5, the exception being if you have a serum so potent it is neutralizing at all dilutions tested.
+ - `max_frac_infectivity_at_least`: drop any viral-barcode / serum-replicate combination that does not have a maximum frac infectivity across all concentrations of at least this value. Typically if you want to allow curves where the sera neutralize at all tested concentrations then you should set a value of 0. But you should set a value >0.5 if you want to require all sera to have a midpoint within the dilution range.
 
  - `min_R2`: drop any viral-barcode / serum-replicate combinations where the fit curve does not have a [coefficient of determination](https://en.wikipedia.org/wiki/Coefficient_of_determination) at least this large (a coefficient of determination of 1 is a perfect fit). Used to drop very poor fitting curves. Reasonable values might be in the 0.6 to 0.8 range, although you should also just look at the curves being dropped to see if they look good.
 

diff --git a/docs/M099d0_titers.html b/docs/M099d0_titers.html
diff --git a/docs/M099d30_titers.html b/docs/M099d30_titers.html
diff --git a/docs/Y044d30_titers.html b/docs/Y044d30_titers.html
diff --git a/docs/Y154d182_titers.html b/docs/Y154d182_titers.html
diff --git a/docs/aggregate_qc_drops.html b/docs/aggregate_qc_drops.html
diff --git a/docs/process_plate11.html b/docs/process_plate11.html
diff --git a/docs/process_plate2.html b/docs/process_plate2.html
diff --git a/docs/titers.html b/docs/titers.html
diff --git a/notebooks/process_plate.py.ipynb b/notebooks/process_plate.py.ipynb
@@ -1184,6 +1184,7 @@
     "    replicate_col=\"barcode\",\n",
     "    fixtop=curvefit_params[\"fixtop\"],\n",
     "    fixbottom=curvefit_params[\"fixbottom\"],\n",
+    "    fixslope=curvefit_params[\"fixslope\"],\n",
     ")"
    ]
   },
@@ -1365,6 +1366,7 @@
     "    replicate_col=\"plate_barcode\",\n",
     "    fixtop=curvefit_params[\"fixtop\"],\n",
     "    fixbottom=curvefit_params[\"fixbottom\"],\n",
+    "    fixslope=curvefit_params[\"fixslope\"],\n",
     ")\n",
     "\n",
     "fit_params_qc = fits_qc.fitParams(average_only=False, no_average=True)\n",

diff --git a/notebooks/serum_titers.py.ipynb b/notebooks/serum_titers.py.ipynb
@@ -143,6 +143,7 @@
     "        \"midpoint\",\n",
     "        \"top\",\n",
     "        \"bottom\",\n",
+    "        \"slope\",\n",
     "    ]\n",
     "]\n",
     "assert per_rep_titers.notnull().all().all()\n",

diff --git a/test_example/config.yml b/test_example/config.yml
@@ -55,11 +55,12 @@ default_process_plate_qc_thresholds: &default_process_plate_qc_thresholds
 
 default_process_plate_curvefit_params: &default_process_plate_curvefit_params
   frac_infectivity_ceiling: 1
-  fixtop: false
+  fixtop: [0.75, 1]
   fixbottom: 0
+  fixslope: [0.8, 5]
 
 default_process_plate_curvefit_qc:  &default_process_plate_curvefit_qc
-  max_frac_infectivity_at_least: 0.5
+  max_frac_infectivity_at_least: 0
   min_R2: 0.8  # you may be able to relax this to more like 0.7 or 0.75
   serum_replicates_ignore_curvefit_qc: []
   barcode_serum_replicates_ignore_curvefit_qc: []