From 35b77f28b4ee9ad18d61610caafdcc33c83c1689 Mon Sep 17 00:00:00 2001
From: Tom Vo <tomvothecoder@gmail.com>
Date: Mon, 10 Jan 2022 15:26:05 -0800
Subject: [PATCH] Add FAQs page to docs (#181)

- Add section for handling opening files with conflicting data var values
---
 docs/faqs.rst  | 22 ++++++++++++++++++++++
 docs/index.rst |  1 +
 2 files changed, 23 insertions(+)
 create mode 100644 docs/faqs.rst

diff --git a/docs/faqs.rst b/docs/faqs.rst
new file mode 100644
index 00000000..92b932fb
--- /dev/null
+++ b/docs/faqs.rst
@@ -0,0 +1,22 @@
+==========================
+Frequently Asked Questions
+==========================
+
+How do I open files that have conflicting values for a data variable(s)?
+------------------------------------------------------------------------
+In xarray, the default setting for checking compatibility across files is ``compat='no_conflicts'``.
+If conflicting values for a data variable exists between the files, xarray raises ``MergeError: conflicting values for variable <DATA VAR NAME> on objects to be combined. You can skip this check by specifying compat="override".``
+
+Let's say you try opening two files using ``xcdat.open_mfdataset()`` and the aforementioned ``MergeError`` appears for the ``lat_bnds`` data var.
+You perform floating point comparison for ``lat_bnds`` and find a very small difference at specific coordinates.
+
+To workaround this data quality issue and proceed with opening the files, pass these keyword arguments:
+
+1. ``compat="override"``: skip comparing and pick variable from first dataset
+2. ``join="override"``:  if indexes are of same size, rewrite indexes to be those of the first object with that dimension. Indexes for the same dimension must have the same size in all objects.
+
+   - ``join`` is set to `"outer_join"` by default, which might not be desired.
+
+``xcdat.open_mfdataset('path/to/files/*.nc', compat="override", join="override")``
+
+More information here: https://xarray.pydata.org/en/stable/generated/xarray.open_mfdataset.html#xarray-open-mfdataset
\ No newline at end of file
diff --git a/docs/index.rst b/docs/index.rst
index cc165cb1..8f6ddc7a 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -85,6 +85,7 @@ See `LICENSE <LICENSE>`_ for details
    Getting Started <getting_started>
    API Reference <api>
    Xarray API Reference <https://xarray.pydata.org/en/stable/api.html>
+   Frequently Asked Questions <faqs>
 
 .. toctree::
    :maxdepth: 2