Initial README.md

README.md

-# bjerknes_feedback_symmetry
+```
+####################################################################
+#                                                                  #
+#   ------------------------------------------------------------   #
+#   A comparison of the atlantic and pacific bjerknes feedbacks:   #
+#   seasonality, symmetry, and stationarity                        #
+#   ------------------------------------------------------------   #
+#                                                                  #
+#   T. DIPPE, J. F. LÜBBECKE, R. J. GREATBATCH                     #
+#                                                                  #
+#   in                                                             #
+#                                                                  #
+#   JOURNAL OF GEOPHYSICAL RESEARCH: OCEANS                        #
+#                                                                  #
+#                                                                  #
+#   Readme for using the Matlab scripts                            #
+#                                                                  #
+####################################################################
 
-"A comparison of the atlantic and pacific bjerknes feedbacks: seasonality, symmetry, and stationarity" by T. DIPPE, J. F. LÜBBECKE, R. J. GREATBATCH in Journal of Geophysical Research: Oceans
\ No newline at end of file
+# --------- #
+# TECHNICAL #
+# --------- #
+
+Matlab version used for all analysis: Matlab 2018
+
+# ------- #
+# GENERAL #
+# ------- #
+
+Many scripts will be made up of a group of three to four scripts. These are:
+
+- <name>.m: The main script that does the principal calculations
+
+- <name>_settings.m: Prescribing all kinds of settings, including paths and
+  various plotting options
+
+- <name>_plots.m or similar: Plots
+
+- <name>_wrapper.m: A wrapper around the main script that allows looping over,
+  for example, feedback elements or basins
+
+  For a given script <name>, I will refer to the bundle as <name>*.m
+
+Note that I do not provide any functions related to correct plotting, such as
+functions that create customized colorbars. If you run into trouble with the
+plotting scripts, contact me at the address given below.
+
+
+# ------------- #
+# USED DATASETS #
+# ------------- #
+
+- AVISO-SSH:        https://www.aviso.altimetry.fr/en/home.html
+
+- ERSST:            https://www.ncdc.noaa.gov/data-access/marineocean-data/
+                    extended-reconstructed-sea-surface-temperature-ersst-v5
+
+- ERA-Interim USTR: https://www.ecmwf.int/en/forecasts/datasets/archive-
+                    datasets/reanalysis-datasets/era-interim
+
+- ERA-40 USTR:      https://apps.ecmwf.int/datasets/data/era40-moda/
+
+- ORAS4 data:       http://icdc.cen.uni-hamburg.de/projekte/easy-init/
+                    easy-init-ocean.html
+
+
+# --------------- #
+# LIST OF SCRIPTS #
+# --------------- #
+
+# FUNCTIONS
+# +++++++++
+
+- bootstrapFeedbackStrength() and bootstrapFeedbackStrengthDiff(): Significance
+               test for feedback strengths and their differences.
+
+- calcAnomalies(): Calculates the anomalies, and allows for variable detrending
+
+- calcIndexAveraged(): Calculates an index, requires a file that describes the
+                       grids that the variables are given on, including the
+                       spatial extent of each grid cell to apply the correct
+                       spatial averaging. (The grid files are stored in my case
+                       in the file modelGrids.mat, which contains a structure
+                       for each grid, which in turn stores information such as
+                       box_grid_area.)
+
+- calculateFeedback(): Perform a robust regression to estimate the strength of a
+                       given feedback element.
+
+- diagnoseLag(): Diagnose the lag at which the feedback strength between two
+                 variables is maximum.
+
+- eventCharacteristics(): Identifies events in a time series and returns various
+                          statistical measures about them. This function is the
+                          backbone of the SST event analysis in the Discussion.
+
+- testValue(): Given a distribution, a significance level and a test value,
+               discern whether the test value sits on the "significant" tails of
+               the distribution.
+
+
+# PREPARING THE DATA
+# ++++++++++++++++++
+
+- zonal_analysis_region_definition.m: Define the equatorial area and zonal bins
+  to analyse
+
+- calculate_equatorial_indices*.m: Calculate indices for each zonal bin defined
+  in zonal_analysis_region_definition.m. These datasets are the basis for most
+  of the analysis.
+
+# ANALYSIS
+# ++++++++
+
+Fig. 1: compare_oras4_ersst*.m
+
+Fig. 2: diagnose_zonal_feedback_lags.*
+
+Fig. 3: Created in MacOS's Keynote
+
+Fig. 4-6: lagged_feedback_strength*.m to diagnose the strengths of the feedback
+          elements, and diagnose_feedback_strength_difference_significance*.m to
+          test the significance
+
+Fig. 7: total_bjerknes_feedback_from_regression*.m
+
+Fig. 8: compare_aviso_oras4_strengths_Atl3_Nino34*.m
+
+Figs. 9-11: decadal_feedback_variations*.m
+
+Fig. 12: zonal_enso_properties*.m
+
+Fig. 13: decadal_sst_event_variations*.m
+
+Figs. A1-A2: calculate_instantaneous_feedback*.m, and
+             compare_lagged_instantaneous_feedback_strengths*.m
+
+Figs. A3-A5: total_bjerknes_feedback_from_regression*.m
+
+
+# ------- #
+# CONTACT #
+# ------- #
+
+Contact me via tina (DOT) dippe (AT) gmail (DOT) com if you have questions.
+```