systematics docs

README.md

@@ -54,6 +54,18 @@ When utilizing this code for a publication, kindly make a reference to the packa
       url={https://doi.org/10.1038/s41467-023-43932-6}
 }
 ```
+If you are using the systematics error, please also cite the paper [A data-driven approach for modeling the temporal and spectral evolution of kilonova systematic uncertainties](https://arxiv.org/abs/2410.21978). The BibTeX entry for the paper is:
+```bibtex
+@article{Jhawar:2024ezm,
+    author = "Jhawar, Sahil and Wouters, Thibeau and Pang, Peter T. H. and Bulla, Mattia and Coughlin, Michael W. and Dietrich, Tim",
+    title = "{A data-driven approach for modeling the temporal and spectral evolution of kilonova systematic uncertainties}",
+    eprint = "2410.21978",
+    archivePrefix = "arXiv",
+    primaryClass = "astro-ph.HE",
+    month = "10",
+    year = "2024"
+}
+```
 
 ### Acknowledgments
 If you benefited from participating in our community, we ask that you please acknowledge the Nuclear Multi-Messenger Astronomy collaboration, and particular individuals who helped you, in any publications.

doc/index.rst

@@ -485,6 +485,7 @@ User Guide
    models
    training
    data_inj_obs
+   systematics
    fitting
    lfi_analysis
    gw_inference

doc/systematics.md

@@ -0,0 +1,78 @@
+
+## Systematics Uncertainties
+
+NMMA currently uses `--error-budget` to specify the constant systematic uncertainties to be added to the likelihood quadrature.
+
+However, it is now possible to use systematic error ($\sigma_{sys}$) prior  in form of a freely sampled parameter, time dependent and/or filter dependent systematic error. This can done by specifying the file path using the `--systematics-file` in `lightcurve-analysis` command.
+
+For more information on systematics error, please refer to the [paper](https://arxiv.org/abs/2410.21978).
+
+The following are the examples of the systematics file:
+
+#### Example 1: Freely sampled (time independent) systematic error
+
+In this case the systematic error is freely sampled and is not dependent on time or filter.
+
+```yaml
+config:
+  withTime:
+    value: true
+    filters:
+      - null
+    time_nodes: 4
+    type: "Uniform"
+    minimum: 0
+    maximum: 2
+  withoutTime:
+    value: false
+    type: "Uniform"
+    minimum: 0
+    maximum: 2
+```
+
+#### Example 2: Time dependent systematic error
+
+In this configuration, a single systematic error is applied across all filters.
+
+```yaml
+config:
+  withTime:
+    value: true
+    filters:
+      - null
+    time_nodes: 4
+    type: "Uniform"
+    minimum: 0
+    maximum: 2
+  withoutTime:
+    value: true
+    type: "Uniform"
+    minimum: 0
+    maximum: 2
+```
+
+#### Example 3: Time and filter dependent systematic error
+
+In this configuration, the `sdssu` and ~ztfr~ filters are sampled together for systematic errors, while the `2massks` filter is sampled independently. All other filters are grouped and sampled together
+
+```yaml
+config:
+  withTime:
+    value: true
+    filters:
+      - [sdssu, ztfr]
+      - [2massks]
+      - null
+    time_nodes: 4
+    type: "Uniform"
+    minimum: 0
+    maximum: 2
+  withoutTime:
+    value: true
+    type: "Uniform"
+    minimum: 0
+    maximum: 2
+```
+
+### Distribution types
+Distribution can be of any of the `analytical` prior from [bilby](https://git.ligo.org/lscsoft/bilby). Please refer to bilby documentation for more information on the available distribution type and their usage. Only positional arguments are required for any of the distrbutions.