From 690ddffdd5ec2f3a40313962eaa521686da644e2 Mon Sep 17 00:00:00 2001
From: Sahil Jhawar <55475299+sahiljhawar@users.noreply.github.com>
Date: Sun, 3 Nov 2024 11:55:50 +0100
Subject: [PATCH] systematics docs (#387)

* systematics docs

* bibtex in readme
---
 README.md          | 12 +++++++
 doc/index.rst      |  1 +
 doc/systematics.md | 78 ++++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 91 insertions(+)
 create mode 100644 doc/systematics.md

diff --git a/README.md b/README.md
index 4cb496fc..c25f306d 100644
--- a/README.md
+++ b/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.
diff --git a/doc/index.rst b/doc/index.rst
index a8c4254b..464c6d51 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -485,6 +485,7 @@ User Guide
    models
    training
    data_inj_obs
+   systematics
    fitting
    lfi_analysis
    gw_inference
diff --git a/doc/systematics.md b/doc/systematics.md
new file mode 100644
index 00000000..53459a0f
--- /dev/null
+++ b/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.