Merge pull request #5 from msrosenberg/dev-branch

refactoring caption generation for most customizability
close #3

MetaWin_mac.spec

@@ -43,6 +43,7 @@ added_files = [("resources/images/[email protected]", "resources/images"),
 			   ("resources/images/[email protected]", "resources/images"),
 			   ("resources/images/[email protected]", "resources/images"),
 			   ("resources/images/[email protected]", "resources/images"),
+			   ("resources/images/[email protected]", "resources/images"),
 
 			   ("resources/images/metawin3icon.png", "resources/images"),
 			   ("resources/images/draw_forest.png", "resources/images"),

MetaWin_windows.spec

@@ -43,6 +43,7 @@ added_files = [("resources/images/[email protected]", "resources/images"),
 			   ("resources/images/[email protected]", "resources/images"),
 			   ("resources/images/[email protected]", "resources/images"),
 			   ("resources/images/[email protected]", "resources/images"),
+			   ("resources/images/[email protected]", "resources/images"),
 
 			   ("resources/images/metawin3icon.png", "resources/images"),
 			   ("resources/images/draw_forest.png", "resources/images"),

resources/metawin_help.html

@@ -55,6 +55,7 @@ <h1>Help Table of Contents</h1>
                   <li><a href="#graph_tab">Graph Tab</a>
                     <ul>
                       <li><a href="#graph_edit">Editing Figures</a></li>
+                      <li><a href="#captions_note">A Note on Captions</a></li>
                     </ul>
                   </li>
                   <li><a href="#phylogeny_tab">Phylogeny Tab</a></li>
@@ -424,6 +425,25 @@ <h4 id="markers_styles">Markers</h4>
                 the chosen marker is a filled marker. Unfilled markers will turn invisible if the no fill option is
                 checked.
             </p>
+            <h3 id="captions_note">A Note on Captions</h3>
+            <p>
+                <span class="metawin">MetaWin</span> will autogenerate captions for each figure it creates, including
+                references in some cases. As style elements of figures can be user edited, this creates a bit of a
+                challenge for captioning, particularly as it relates to specifying color. Computers can
+                generate over 16.7 million unique colors, most of which obviously do not have unique names.
+                Although exact, specifying colors by RGB or hex number in captions would not be particularly
+                useful. Therefore, whenever a caption includes a reference to a color, a color name is chosen by
+                matching the specific color to the closest named color from a set of approximately 1,000
+                named colors based on a <a href="https://blog.xkcd.com/2010/05/03/color-survey-results/">survey done at
+                XKCD</a>. This set was chosen primarily because of it's size; other standard color names,
+                <em>e.g.,</em> CSS4, only include names for fewer than 150 colors. With that many crowd-coursed color
+                names, many me be a bit odd, so simply be warned if strange color labels appear.
+            </p>
+            <p>
+                Currently only line and markers description appear in captions. Line descriptions include only color
+                and style (solid, dahsed, etc.), while markers include color and shape (two colors if the primary
+                and border colors are different). Properties such as size and thickness are not included in captions.
+            </p>
 
           <h2 id="phylogeny_tab">Phylogeny Tab</h2>
             <p>
@@ -2487,7 +2507,7 @@ <h3>Output Example</h3>
             <blockquote class="output-example">
                 <p>
                     Normal Quantile plot following Wang and Bushman (1998). The standardized effect size is the
-                    efffect size divided by the square-root of its variance. The solid line represents the regression
+                    effect size divided by the square-root of its variance. The solid line represents the regression
                     and the dashed lines the 95% prediction envelope.
             </p>
                 <p>

src/MetaWinAnalysis.py

@@ -1798,62 +1798,56 @@ def do_meta_analysis(data, options, decimal_places: int = 4, alpha: float = 0.05
     output, all_citations = options.report_choices()
     output_blocks.extend(output)
     if options.structure == SIMPLE_MA:
-        (output, figure, fig_caption, chart_data, analysis_values,
+        (output, figure, chart_data, analysis_values,
          citations) = MetaWinAnalysisFunctions.simple_meta_analysis(data, options, decimal_places, alpha, norm_ci)
     elif options.structure == GROUPED_MA:
-        (output, figure, fig_caption, chart_data, analysis_values,
+        (output, figure, chart_data, analysis_values,
          citations) = MetaWinAnalysisFunctions.grouped_meta_analysis(data, options, decimal_places, alpha, norm_ci)
     elif options.structure == CUMULATIVE_MA:
-        output, figure, fig_caption, chart_data = MetaWinAnalysisFunctions.cumulative_meta_analysis(data, options,
-                                                                                                    decimal_places,
-                                                                                                    alpha, norm_ci)
+        output, figure, chart_data = MetaWinAnalysisFunctions.cumulative_meta_analysis(data, options,
+                                                                                       decimal_places, alpha, norm_ci)
         analysis_values = None
         citations = []
     elif options.structure == REGRESSION_MA:
-        (output, figure, fig_caption, chart_data, analysis_values,
+        (output, figure, chart_data, analysis_values,
          citations) = MetaWinAnalysisFunctions.regression_meta_analysis(data, options, decimal_places, alpha, norm_ci)
     elif options.structure == COMPLEX_MA:
         output, analysis_values, citations = MetaWinAnalysisFunctions.complex_meta_analysis(data, options,
                                                                                             decimal_places, alpha,
                                                                                             norm_ci)
         figure = None
-        fig_caption = None
         chart_data = None
     elif options.structure == NESTED_MA:
-        (output, figure, fig_caption, chart_data, analysis_values,
+        (output, figure, chart_data, analysis_values,
          citations) = MetaWinAnalysisFunctions.nested_meta_analysis(data, options, decimal_places, alpha, norm_ci)
     elif options.structure == TRIM_FILL:
-        (output, figure, fig_caption, chart_data, analysis_values,
+        (output, figure, chart_data, analysis_values,
          citations) = MetaWinAnalysisFunctions.trim_and_fill_analysis(data, options, decimal_places, alpha, norm_ci)
     elif options.structure == JACKKNIFE:
-        (output, figure, fig_caption,
-         chart_data, citations) = MetaWinAnalysisFunctions.jackknife_meta_analysis(data, options, decimal_places,
-                                                                                   alpha, norm_ci)
+        (output, figure,  chart_data,
+         citations) = MetaWinAnalysisFunctions.jackknife_meta_analysis(data, options, decimal_places, alpha, norm_ci)
         analysis_values = None
     elif options.structure == PHYLOGENETIC_MA:
         output, citations = MetaWinAnalysisFunctions.phylogenetic_meta_analysis(data, options, tree, decimal_places,
                                                                                 alpha, norm_ci)
         analysis_values = None
         figure = None
-        fig_caption = None
         chart_data = None
     elif options.structure == RANKCOR:
         output, citations = MetaWinAnalysisFunctions.rank_correlation_analysis(data, options, decimal_places)
         figure = None
-        fig_caption = None
         chart_data = None
         analysis_values = None
     else:
         output = []
         analysis_values = None
         figure = None
-        fig_caption = None
         chart_data = None
         citations = []
     all_citations.extend(citations)
     output_blocks.extend(output)
     output_blocks.extend(create_reference_list(all_citations))
-    return output_blocks, figure, fig_caption, chart_data, analysis_values
+    return output_blocks, figure, chart_data, analysis_values
 
 
 def meta_analysis(sender, data, last_effect, last_var, decimal_places: int = 4, alpha: float = 0.05,
@@ -1909,12 +1903,9 @@ def meta_analysis(sender, data, last_effect, last_var, decimal_places: int = 4,
                 meta_analysis_options.structure = None
 
         if meta_analysis_options.structure is not None:
-            output, figure, fig_caption, chart_data, _ = do_meta_analysis(data, meta_analysis_options, decimal_places,
-                                                                          alpha, tree, norm_ci)
+            output, figure, chart_data, _ = do_meta_analysis(data, meta_analysis_options, decimal_places, alpha, tree,
+                                                             norm_ci)
             sender.last_effect = meta_analysis_options.effect_data
             sender.last_var = meta_analysis_options.effect_vars
-            return output, figure, fig_caption, chart_data
-        else:
-            return None, None, None, None
-    else:
-        return None, None, None, None
+            return output, figure, chart_data
+    return None, None, None