Release v1.0 (#8)

* Update changelog
* Improve modeling README
* Add "Known Issues" section to main README
* Add release table to main README
* Add and update links
* Add and update references
* General: fix typos, improve formulation, usw.

Author: yvonnefroehlich

003_modeling/README.md

@@ -1,11 +1,11 @@
 # Instruction: How to perform a modeling run for a single seismological recording station
 
-- created: Michael Grund (ORCID 0000-0001-8759-2018)\
+- Created: Michael Grund (ORCID 0000-0001-8759-2018)\
   https://github.com/michaelgrund/sws_tools
-- re-written: Yvonne Fröhlich (ORCID 0000-0002-8566-0619)\
+- Re-written: Yvonne Fröhlich (ORCID 0000-0002-8566-0619)\
   https://github.com/yvonnefroehlich/sws-plotting-and-modeling
 
-_Details_: [Supporting Information](https://academic.oup.com/gji/article/223/3/1525/5893297#supplementary-data) of [Grund & Ritter (2020)](https://doi.org/10.1093/gji/ggaa388.)
+_Details_: [Supporting Information](https://academic.oup.com/gji/article/223/3/1525/5893297#supplementary-data) of [Grund & Ritter (2020)](https://doi.org/10.1093/gji/ggaa388).
 
 
 ## Requirements
@@ -14,45 +14,45 @@ _Details_: [Supporting Information](https://academic.oup.com/gji/article/223/3/1
   - Deep Learning Toolbox
   - Mapping Toolbox
 
-- _MATLAB Seismic Anisotropy Toolbox_ (MSAT) by [Walker & Wookey (2012)](https://doi.org/10.1016/j.cageo.2012.05.031)
+- _MATLAB Seismic Anisotropy Toolkit_ (MSAT) by [Walker & Wookey (2012)](https://doi.org/10.1016/j.cageo.2012.05.031)
   - Download it from (last access 2022/07/05)
-    - https://www1.gly.bris.ac.uk/MSAT/
+    - https://www1.gly.bris.ac.uk/MSAT/ _or_
     - https://github.com/andreww/MSAT
   - Install MSAT
   - Add the whole MSAT package to your _MATLAB_ path
   - If you want to get familiar with the modeling in MSAT and the behavior of different settings
   change to the directory `MSAT/examples/splitting_model/` in which the script `split_model.m` is located.
-  This script is described in the publication Walker & Wookey (2012).
+  This script is described in the publication [Walker & Wookey (2012)](https://doi.org/10.1016/j.cageo.2012.05.031).
   You can play around with different parameters and see how these affect the splitting parameters.
 
 
 ## Forward Calculation
 
-_Please note_: For small stepsizes computation time and structure size increases significantly.
+_Please note_: For small stepsizes, computation time and structure size increase significantly
 
 - Precompute splitting parameters for the different model types: **`SWS_modeling_precomp_models_main.m`**
 
 |step_phi / deg|step_dt / s|step_dips / deg|step_dddir / deg|size / GB|publication|
 |---|---|---|---|---|---|
 |45 |1.00|15|45|0.008|provided TEST_data|
-|5  |0.25|5 |5 |4.7  |Ritter, Fröhlich, Sanz Alonso, Grund (2022)|
-|5  |0.20|5 |5 |6.6  |Grund & Ritter (2020)|
+|5  |0.25|5 |5 |4.7  |[Ritter, Fröhlich, Sanz Alonso & Grund (2022)](https://doi.org/10.1007/s10950-022-10112-w)|
+|5  |0.20|5 |5 |6.6  |[Grund & Ritter (2020)](https://doi.org/10.1093/gji/ggaa388)|
 
 - All models of all model types are merged in a single nested _MATLAB_ structure with fields:
   - 1 | `modout.phi_eff`: effective or apparent phi values over backazimuth
   - 2 | `modout.dt_eff`: effective or apparent dt values over backazimuth
   - 3 | `modout.mod_paras`: model parameters depending on model type
-    - one horizontal layer see `SWS_modeling_precomp_singlelayer.m` _or_
-    - two horizontal layers see `SWS_modeling_precomp_twolayers.m` _or_
-    - one dippping layer see `SWS_modeling_precomp_dippinglayer.m`, `SWS_modeling_calc_dipping.m`
+    - One horizontal layer see `SWS_modeling_precomp_singlelayer.m` _or_
+    - Two horizontal layers see `SWS_modeling_precomp_twolayers.m` _or_
+    - One dippping layer see `SWS_modeling_precomp_dippinglayer.m`, `SWS_modeling_calc_dipping.m`
   - 4 | `modout.type`: string corresponding to the model type
-    - one horizontal layer as 'single_layer' _or_
-    - two horizontal layers as 'two_layers' _or_
-    - one dipping layer as 'dipping'
+    - One horizontal layer as 'single_layer' _or_
+    - Two horizontal layers as 'two_layers' _or_
+    - One dipping layer as 'dipping'
 
 ## Comparison & Visualization
 
-_Please note_: SWS data input is expected to be in standard _SplitLab_ and/or _StackSplit_ output format (`SWS_modeling_read_data.m`).
+_Please note_: SWS data input is expected to be in standard _SplitLab_ and/or _StackSplit_ output format (`SWS_modeling_read_data.m`)
 
 - The observed SWS data is compared against all pre-computed models of all model types: **`SWS_modeling_calc_misfit.m`**
 - The root mean square error (RMSE) between the observed and pre-computed splitting parameters is calculated

003_modeling/SWS_modeling_calc_misfit.m

@@ -652,7 +652,7 @@
         res_phi(kk,1) = abs( find_theo_phi - meas_phiSC(kk,2) );
 
         % if there is a residuum > 90, calc 180-res_phi to consider
-        % the flip from -90° to +90°
+        % the flip from -90 deg to +90 deg
         if res_phi(kk,1) > 90
             res_phi(kk,1) = 180-res_phi(kk,1);
         end

003_modeling/SWS_modeling_plot_results.m

@@ -80,7 +80,7 @@ function SWS_modeling_plot_results( ...
 %--------------------------------------------------------------------------
 % BAZ range to plot
 
-% % Ritter et al. 2022 Journal of Seismology
+% % Ritter et al. (2022) Journal of Seismology
 % baz2plot_start = 0;
 % baz2plot_end = 100;
 
@@ -95,7 +95,7 @@ function SWS_modeling_plot_results( ...
 leg_symb_simw_split = 'square';
 leg_symb_simw_null = 'square';
 
-% % Ritter et al. 2022 Journal of Seismology
+% % Ritter et al. (2022) Journal of Seismology
 % % -> only stack splits in NE quadrant
 % leg_symb_stack_split = 'diamond';
 
@@ -120,7 +120,7 @@ function SWS_modeling_plot_results( ...
 
 
 %==========================================================================
-%% shift phi -90°-90° -> 0°-180°
+%% shift phi -90 deg to 90 deg -> 0 deg to 180 deg
 %==========================================================================
 % >>> adjust stations for your needs <<<
 
@@ -427,7 +427,7 @@ function SWS_modeling_plot_results( ...
     %......................................................................
     % plot RMSE values
 
-    % standard for plot backazimuth 0°-360°
+    % standard for plot backazimuth 0 deg to 360 deg
     str_rms = ['RMSE_{tot} = ' num2str(models_2plot(1).RMSE,'%4.2f'), ...
                ', RMSE_{\phi} = ' num2str(models_2plot(1).RMSE_phi,'%4.2f') '\circ', ...
                ', RMSE_{\delta{\itt}} = ' num2str(models_2plot(1).RMSE_dt,'%4.2f') ' s'];
@@ -438,18 +438,19 @@ function SWS_modeling_plot_results( ...
                'Color',colmod_bf_1, 'BackgroundColor','white', ...
                'FaceAlpha',0.7)
 
-%     % Ritter et al. 2022, Journal of Seismology
-%     % plot backazimuth 0°-110°
-%     str_rms = {['RMSE_{tot} = ' num2str(models_2plot(1).RMSE,'%4.2f')], ...
-%                ['RMSE_{\phi} = ' num2str(models_2plot(1).RMSE_phi,'%4.2f') '\circ'], ...
-%                ['RMSE_{\delta{\itt}} = ' num2str(models_2plot(1).RMSE_dt,'%4.2f') ' s']};
-%     annotation('textbox', [0.140 0.595 0 0], ...
-%                'String',str_rms, 'FitBoxToText','on', 'Margin',1, ...
-%                'HorizontalAlignment','left', ...
-%                'VerticalAlignment','bottom', ...
-%                'Color',colmod_bf_1, 'BackgroundColor','white', ...
-%                'FaceAlpha',0.7)
-
+%     % Ritter et al. (2022), Journal of Seismology
+%     % plot backazimuth 0 deg to 110 deg
+%{
+     str_rms = {['RMSE_{tot} = ' num2str(models_2plot(1).RMSE,'%4.2f')], ...
+                ['RMSE_{\phi} = ' num2str(models_2plot(1).RMSE_phi,'%4.2f') '\circ'], ...
+                ['RMSE_{\delta{\itt}} = ' num2str(models_2plot(1).RMSE_dt,'%4.2f') ' s']};
+     annotation('textbox', [0.140 0.595 0 0], ...
+                'String',str_rms, 'FitBoxToText','on', 'Margin',1, ...
+                'HorizontalAlignment','left', ...
+                'VerticalAlignment','bottom', ...
+                'Color',colmod_bf_1, 'BackgroundColor','white', ...
+                'FaceAlpha',0.7)
+%}
 
 %==========================================================================
     % subplot - panel 2 - dt
@@ -666,7 +667,7 @@ function SWS_modeling_plot_results( ...
                 end
             % multi splits = stack splits
             else
-                % Ritter et al. 2022 Journal of Seismology
+                % Ritter et al. (2022) Journal of Seismology
                 % no single splits in NE quadrant after stack,
                 % so no entry in legend for single splits
                 % and only entry for stack splits
@@ -776,7 +777,7 @@ function SWS_modeling_plot_results( ...
 
             % multi splits = stack splits
             else
-                % Ritter et al. 2022 Journal of Seismology
+                % Ritter et al. (2022) Journal of Seismology
                 % no single splits in NE quadrant after stack,
                 % so no entry in legend for single splits
                 % and only entry for stack splits
@@ -878,7 +879,7 @@ function SWS_modeling_plot_results( ...
 
     if strcmp({staname_split},'BFO') && baz2plot_end==100
         % BAZ range to plot 0 deg to 100 deg
-        % -> Ritter et al. 2022 Journal of Seismology
+        % -> Ritter et al. (2022) Journal of Seismology
         h_leg_split.Position = [0.195 0.360 0.065 0.1];
     else
         % BAZ range to plot 0 deg to 360 deg
@@ -1242,31 +1243,28 @@ function SWS_modeling_plot_results( ...
 
 %--------------------------------------------------------------------------
 %   % plot polyons around clusters
-%   % Ritter et al. 2022 Journal of Seismology
 
-%     % BFO
-%     if strcmp(staname_split,"BFO")==1 && ...
-%        modrange_upp==100 && ...
-%        strcmp(data_used,"multiWS")==1 &&
-%
-%         x_pol_1 = [0.35 0.35 0.9 1.15 1.15 0.6];
-%         y_pol_1 = [ -90  -75  -50 -50  -60 -90];
-%         pol_1 = polyshape(x_pol_1,y_pol_1);
-%
-%         x_pol_2 = [0.9 0.35 0.35 1.2 1.9 1.9 1.4 0.9 0.9 1.9 1.9 0.9];
-%         y_pol_2 = [-35  -15   25  45  45  35  35  15 -25 -25 -35 -35] ;
-%         pol_2 = polyshape(x_pol_2,y_pol_2);
-%
-%         x_pol_3 = [ 1 0.40 0.40 0.9 1.7 2.6 2.6  1];
-%         y_pol_3 = [50   70   90  90  60  60  50 50];
-%         pol_3 = polyshape(x_pol_3,y_pol_3);
-%
-%         plot(pol_1, 'FaceColor','r', 'EdgeColor','k', 'Facealpha',0.25)
-%         plot(pol_2, 'FaceColor','b', 'EdgeColor','k', 'Facealpha',0.25)
-%         plot(pol_3, 'FaceColor','r', 'EdgeColor','k', 'Facealpha',0.25)
-%
-%         disp('BFOpolyons')
-%     end
+    % Ritter et al. (2022) Journal of Seismology
+    % BFO, BAZ 30 deg to 110 deg, horiztonal tow-layer model
+%{
+   x_pol_1 = [0.35 0.35 0.9 1.15 1.15 0.6];
+   y_pol_1 = [ -90  -75  -50 -50  -60 -90];
+   pol_1 = polyshape(x_pol_1,y_pol_1);
+
+   x_pol_2 = [0.9 0.35 0.35 1.2 1.9 1.9 1.4 0.9 0.9 1.9 1.9 0.9];
+   y_pol_2 = [-35  -15   25  45  45  35  35  15 -25 -25 -35 -35] ;
+   pol_2 = polyshape(x_pol_2,y_pol_2);
+
+   x_pol_3 = [ 1 0.40 0.40 0.9 1.7 2.6 2.6  1];
+   y_pol_3 = [50   70   90  90  60  60  50 50];
+   pol_3 = polyshape(x_pol_3,y_pol_3);
+
+   plot(pol_1, 'FaceColor','r', 'EdgeColor','k', 'Facealpha',0.25)
+   plot(pol_2, 'FaceColor','b', 'EdgeColor','k', 'Facealpha',0.25)
+   plot(pol_3, 'FaceColor','r', 'EdgeColor','k', 'Facealpha',0.25)
+
+   disp('BFOpolyons')
+%}
 
 %--------------------------------------------------------------------------
     % RMSE color-coding

003_modeling/SWS_modeling_plot_stereo_synthetic.m

@@ -92,7 +92,7 @@ function SWS_modeling_plot_stereo_synthetic( ...
 % schematic sketches
 lengthbar_lay = 0.145;
 
-% Ritter et al. 2022 Journal of Seismology
+% Ritter et al. (2022) Journal of Seismology
 col_lay_upp = [255 165 079] ./256; % orange
 col_lay_low = [0.8 0.8 0.8]; % light gray
 col_lay_one = [255 165 079] ./256; % orange
@@ -355,7 +355,7 @@ function SWS_modeling_plot_stereo_synthetic( ...
 % in direction of downdip-dir and perpendicular to it
 % >>> only valid for assuming the fast axis plunges with dip direction <<<
 
-    % first plot nulls in downdipdir +-180°
+    % first plot nulls in downdipdir +-180 deg
     bazi_nulls = [downdipdir downdipdir+180];
     inc_nulls = [10 10];
     for k = 1:2
@@ -364,8 +364,8 @@ function SWS_modeling_plot_stereo_synthetic( ...
               'MarkerSize',marks, 'linewidth',linewcirc);
     end
 
-    % second find positions where bar orientation exact +-90° baz
-    % >>> for dipdir 90, 270° the nulls are not correctly shown <<<
+    % second find positions where bar orientation exact +-90 deg BAZ
+    % >>> for dipdir 90, 270 deg the nulls are not correctly shown <<<
     if downdipdir < 90
         first = azim_rounded_all + 90;
         firstmin = min(first);

README.md

@@ -9,17 +9,11 @@ _MATLAB_ functions for visualization and modeling of shear wave splitting observ
 ## Citation
 
 If you make use of this material, please acknowledge the relating publications in which framework these functions were implemented:
-
-<!---
-- **_Fröhlich, Yvonne, Grund, Michael & Ritter, Joachim R. R. (2022)_**. Laterally and vertically varying seismic anisotropy in the lithosphere-asthenosphere system revealed from SK(K)S splitting at neighboring sites in the Upper Rhine Graben area, Central Europe. in preparation for *Geophysical Journal International*.
--->
 - [**_Ritter, Joachim R. R., Fröhlich, Yvonne, Sanz Alonso, Yasmin & Grund, Michael (2022)_**](https://doi.org/10.1007/s10950-022-10112-w). Short-scale laterally varying SK(K)S shear wave splitting at BFO, Germany – implications for the determination of anisotropic structures. *Journal of Seismology*. https://doi.org/10.1007/s10950-022-10112-w.
 - [**_Grund, Michael & Ritter, Joachim R. R. (2020)_**](https://doi.org/10.1093/gji/ggaa388). Shear-wave splitting beneath Fennoscandia – evidence for dipping structures and laterally varying multilayer anisotropy. *Geophysical Journal International*, 223, 1525-1547. https://doi.org/10.1093/gji/ggaa388.
 - [**_Grund, Michael (2019)_**](https://doi.org/10.5445/IR/1000091425). Exploring geodynamics at different depths with shear wave splitting. *Dissertation*, Karlsruhe Institute of Technology (KIT). https://doi.org/10.5445/IR/1000091425.
 
-<!---
-Furthermore you can cite the [Zenodo Doi]() given above.
--->
+Furthermore you can cite the Zenodo DOI.
 
 
 ## Content
@@ -76,7 +70,7 @@ _Details_: [Supporting Information](https://academic.oup.com/gji/article/223/3/1
   - Joint fitting of fast polarization direction and delay time, separate fitting of the fast polarization direction
 - **Result visualization**
   - Backazimuthal variation of the splitting parameters (forward calculation and observation)
-  - Model type distribution (histogram)
+  - Model type distribution (bar plot)
   - Model parameter distribution (scatter plot)
   - Stereoplot of synthetic splitting parameters (polar plot)
 - **Result data**
@@ -96,8 +90,8 @@ _Tested with_: R2022a, R2021a,b under Linux and Windows
   - Mapping Toolbox
   - [_MATLAB Seismic Anisotropy Toolkit_ (MSAT)](https://www1.gly.bris.ac.uk/MSAT/) ([**_Walker & Wookey 2012_**](https://doi.org/10.1016/j.cageo.2012.05.031))
 - **Data**: Shear wave splitting observations
-  - Output *.txt files (_nulls_, _splits_) of _SplitLab_ versions 1.5.0 (original) or 1.2.1 (**_Porritt 2014_**)
-  - Output *.mat structure and *.txt files (STACK, SIMW) of _StackSplit_
+  - Output *.txt files (_nulls_, _splits_) of _SplitLab_ version 1.5.0 ([**_Wüstefeld et al. 2008_**](https://doi.org/10.1016/j.cageo.2007.08.002)) or 1.2.1 (**_Porritt 2014_**)
+  - Output *.mat structure and *.txt files (STACK, SIMW) of _StackSplit_ ([**_Grund 2017_**](https://doi.org/10.1016/j.cageo.2017.04.015))
 - **Colormaps** (optional): Color-coding of the fast polarization direction and the root mean square error
   - [MatPlotLib Perceptually Uniform Colormaps](https://de.mathworks.com/matlabcentral/fileexchange/62729-matplotlib-perceptually-uniform-colormaps)\
     version v2.1.3, MATLAB File Exchange, last access 2022 June 26
@@ -109,17 +103,25 @@ _Tested with_: R2022a, R2021a,b under Linux and Windows
 
 ## Releases
 
-- dev ([main branch](https://github.com/yvonnefroehlich/sws-visualization-and-modeling/tree/main))
-<!---
-- [v1.0]()
--->
+|release|publication|
+|---|---|
+|dev |reflects [main branch](https://github.com/yvonnefroehlich/sws-visualization-and-modeling/tree/main)|
+|v1.0|related to [Ritter, Fröhlich, Sanz Alonso & Grund (2022)](https://doi.org/10.1007/s10950-022-10112-w)|
 
 For details of the individual releases as well as for changes and differences compared to [sws_tools](https://github.com/michaelgrund/sws_tools) by [Michael Grund](https://github.com/michaelgrund) see the [changelog](https://github.com/yvonnefroehlich/sws-visualization-and-modeling/blob/main/changelog.md).
 
 
+## Known Issues
+
+- Modeling of multi-event analysis: Only using either STACK or SIMW results is supported
+- Model parameter distribution for one dipping layer: Under development, not fully tested
+- Synthetic stereoplot for one dipping layer: Backazimuths of predicted nulls are partly wrong
+- Synthetic stereoplot for one dipping layer: Gray arrow is partly not exactly placed in the center
+
+
 ## Contributing
 
-For bug reports, suggestions or recommendations feel free to open an issue or submit a pull request directly here on GitHub.
+For bug reports, suggestions or recommendations feel free to open an issue or submit a pull request directly here on [GitHub](https://github.com/yvonnefroehlich/sws-visualization-and-modeling/tree/main).
 
 
 ## References