Documentation Improved - Built in Help Pages

New Version for Packaging and Release ready: Added more documentation in built in help pages and on webpage.
mbisbano1 · Jun 11, 2022 · d7fead2 · d7fead2
1 parent 4a0b126
commit d7fead2
Show file tree

Hide file tree

Showing 37 changed files with 653 additions and 1,182 deletions.
diff --git a/DirectionalFactorPolarPlotsV3.mlapp b/DirectionalFactorPolarPlotsV3.mlapp
diff --git a/HTML/DirectivityEquationFull.png b/HTML/DirectivityEquationFull.png
diff --git a/HTML/DirectivityHelp1.html b/HTML/DirectivityHelp1.html
@@ -0,0 +1,44 @@
+<!DOCTYPE html []>
+<html>
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="author" content="MarkdownViewer++" />
+    <title>DirectivityHelp1.md</title>
+    <style type="text/css">
+
+/* Avoid page breaks inside the most common attributes, especially for exports (i.e. PDF) */
+td, h1, h2, h3, h4, h5, p, ul, ol, li {
+    page-break-inside: avoid; 
+}
+
+        </style>
+  </head>
+  <body>
+    <h3 id="directivity-calculations-quantify-directive-gain">
+      <strong>Directivity Calculations: Quantify Directive Gain</strong>
+    </h3>
+    <p>Directivity Calculations are performed following a modified version of Equation 7.6.8 from KFCS. Assuming Uniformity in Phi, we can simplify this and only integrate through theta, as shown in the equation below.</p>
+	<img src="DirectivityEquationFull.png">
+    <p>Computation is done using MATLAB's trapz() function, which approximates integration through the Trapezoidal Riemann Sum. Accuracy is proportional to the theta measurement step sizes, with larger step sizes resulting in more gross approximations.</p>
+    <p>To avoid complications at zero crossings of the sin(theta) function, inputs are broken up in quadrant segments, integrated separately, and then summed. Due to this, the input format for data is quite particular. Some rules for input formats are listed below:</p>
+    <ol>
+      <li>
+        <p>
+          <strong>Uniform Theta Step Size</strong>: The difference in theta from one data point to the next must be uniform over the entire set of data. Meaning measurements taken from 0 to 360 degrees with a step size of 1 degree will be taken at 0, 1, 2, ..., 358, 359 degrees.</p>
+      </li>
+      <li>
+        <p>
+          <strong>Theta Bounds</strong>: The edges of sample points must be in an order expected by Directivity Calculation code. You cannot expect data taken starting at 30 degrees and going to 389 degrees to work properly, and to compensate for this you may need to manually reformat some measurement data before inputting/importing it into this program. Acceptable formats are listed below, with dTheta being the theta step size between each sample:</p>
+        <ul>
+          <li>-180 to (180-dTheta) degrees</li>
+          <li>-90 to (90-dTheta) degrees</li>
+          <li>0 to (360-dTheta) degrees</li>
+        </ul>
+      </li>
+      <li>
+        <p>
+          <strong>Sample Overlap</strong>: Notice in the Theta Bounds rule that the range does not allow overlapping samples (0 and 360 degrees, etc), so if your imported data contains these overlap points, you must remove them manually, either using the Remove First/Last Element buttons or externally before importing. An example would be data collected between 0 and 360 with a dTheta of 0.1 degree. The correct range for importing would have a <strong>minimum</strong> theta of 0 degrees and a <strong>maximum</strong> theta of 359.9 degrees.</p>
+      </li>
+    </ol>
+  </body>
+</html>
diff --git a/HTML/FunctionBankHelp.html b/HTML/FunctionBankHelp.html
@@ -0,0 +1,80 @@
+<!DOCTYPE html []>
+<html>
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="author" content="MarkdownViewer++" />
+    <title>FunctionBank.md</title>
+    <style type="text/css">
+
+/* Avoid page breaks inside the most common attributes, especially for exports (i.e. PDF) */
+td, h1, h2, h3, h4, h5, p, ul, ol, li {
+    page-break-inside: avoid; 
+}
+
+        </style>
+  </head>
+  <body>
+    <h3 id="function-bank-specify-what-to-plot">
+      <strong>Function Bank: Specify what to Plot</strong>
+    </h3>
+    <ul>
+      <li>
+        <h4 id="function-toggles">
+          <strong>Function Toggles</strong>
+        </h4>
+        <ul>
+          <li>Enable/Disable the plotting of a given function. If the Function # button is Gray, it will be plotted.</li>
+        </ul>
+      </li>
+      <li>
+        <h4 id="equation-entry-fields">
+          <strong>Equation Entry Fields</strong>
+        </h4>
+        <ul>
+          <li>Manually specify an equation to plot as a function of theta. These boxes will be pre-filled upon starting the program with some examples.</li>
+          <li>
+            <strong>ABSOLUTE VALUE</strong> is taken on the resulting values before plotting.</li>
+          <li>
+            <strong>SYNTAX</strong>: All equations should follow the standard matlab equation syntax, and the <strong>theta</strong> variable is a vector so the . (dot) operator should be used for multiplications or divides.</li>
+          <li>
+            <strong>Predefined Functions</strong>: Functions that are selected in the Predefined Patterns tab will type in the correct equation here for the user.</li>
+          <li>
+            <strong>SINC &amp; JINC</strong>: To use SINC and JINC functions, you must use type them specially, as they are not standard functions in Matlab and as such I had to add my own versions to this app. These functions remove the discontinuity at x == 0. Call these using the app.mysinc(argument) notation.
+<ul><li><strong>SINC</strong>: y = app.mysinc(x) = sin(pi * x)/(pi * x)</li><li><strong>JINC</strong>: y = app.myjinc(x) = 2*besselj(1,x)/(x)</li></ul></li>
+        </ul>
+      </li>
+      <li>
+        <h4 id="legend-entries">
+          <strong>Legend Entries</strong>
+        </h4>
+        <ul>
+          <li>If the Plot Legend is enabled, the strings shown in these fields will be displayed for the given functions' Legend Entry.</li>
+        </ul>
+      </li>
+      <li>
+        <h4 id="directivities">
+          <strong>Directivities</strong>
+        </h4>
+        <ul>
+          <li>If the function being plotted is correctly imported/typed in properly <strong>AND</strong> it is computationally reasonable to solve the Directivity for, the functions' directivity will be displayed here after <strong>Plot Function</strong> is clicked. If the calculation of Directivity fails for any reason, the field will be populated with a -1. Read more about the calculation of Directivity values in the Directivity help tab.</li>
+        </ul>
+      </li>
+      <li>
+        <h4 id="line-type">
+          <strong>Line Type</strong>
+        </h4>
+        <ul>
+          <li>To allow greater differentiation between different functions being plotted (especially when only using black and white) each functions' line type can be specified. This dropdown allows the user to select the line type for each function.</li>
+        </ul>
+      </li>
+      <li>
+        <h4 id="line-color">
+          <strong>Line Color</strong>
+        </h4>
+        <ul>
+          <li>Each functions' color can be specified for plotting. This dropdown allows the user to specify the color of each function. By Right clicking the 'Line Color' text a few presets for line colors are available.</li>
+        </ul>
+      </li>
+    </ul>
+  </body>
+</html>
diff --git a/HTML/ImportDataHelp.html b/HTML/ImportDataHelp.html
@@ -0,0 +1,37 @@
+<!DOCTYPE html []>
+<html>
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="author" content="MarkdownViewer++" />
+    <title>ImportDataHelp.md</title>
+    <style type="text/css">
+
+/* Avoid page breaks inside the most common attributes, especially for exports (i.e. PDF) */
+td, h1, h2, h3, h4, h5, p, ul, ol, li {
+    page-break-inside: avoid; 
+}
+
+        </style>
+  </head>
+  <body>
+    <h3 id="import-data-take-lab-results-to-publication">
+      <strong>Import Data: Take Lab Results to Publication</strong>
+    </h3>
+    <p>The Import Data tab is likely the most complicated of all sections in this program. With a bit of patience it should become straight forward. I am open to critiques on the user interface here if you as a user have any suggestions!</p>
+    <p>
+      <strong>Principle of Operation</strong>:
+- <strong>Table Workspace</strong>: This is where imported data can be modified and manipulated before plotting. Think of this table as a temporary location just for the viewing of data. During a session, there are six save slots available for imported functions to plot. Using the Table Workspace the user can view what is stored in these slots and modify as they please. All the plotting of imported data is done with the data currently saved in save slots. That means, just because data is displayed in the table, does not mean it is the data that has been plotted.</p>
+    <ul>
+      <li>
+        <strong>Excel/CSV/MAT Importing</strong>: Click the corresponding import button for your data format. This will load the data into the Table Workspace. Right clicking each of these buttons will allow the user to view a template version of an importable file. These templates must be followed <strong>EXACTLY</strong>. Having extra calculations off to the side will throw off the importing process.
+<ul><li><strong>For Excel</strong>: If you are following the templates as shown, and imports are still not working, you may have stray (invisible) data in some other cells. Select the first two columns of data and copy; then create a new spreadsheet and right click in the top left cell, selecting Paste -&gt; Values. This new spreadsheet should work.</li></ul></li>
+      <li>
+        <strong>Operations on Table Data</strong>: Data imported into the table may not be formatted properly for plotting, so there are a limited number of automated functions that can be performed on that data included in this program. The Table data <strong>must then be saved into a save slot for viewing</strong>.
+<ul><li><strong>Take Absolute Value</strong>: Directional Factor plots are only meant to display magnitude, so if imported data has negative values, you can use this to take the absolute value of every DF data point in the table.
+<ul><li><strong>DF(i) = abs(DF(i))</strong> for all i</li></ul></li><li><strong>Scale By Max Value</strong>: Directional Factor plots are meant to display radius values in the range of 0 to 1. If the imported data in the table needs to be scaled down to this range, this button will do so.
+<ul><li><strong>DF(i) = DF(i)/MAX(DF)</strong> for all i</li></ul></li><li><strong>Insert/Remove Elements</strong>: For directivity calculations, the start/stop angles are important. This is discussed in more detail in the <strong>Directivity Help</strong> section. If imported data has a few extra data points at the beginning or end, these can be removed, or data points can be added if there are a few missing at the edges.
+<strong>Imported Save Slots</strong>:</li><li><strong>Save</strong>: Take data in Table Workspace and store in selected Import Save Slot.</li><li><strong>Load</strong>: Load data from selected Import Save Slot into Table Workspace.
+The save slots provide a way of plotting more than just one imported dataset at a time, as well as making the code convenient to write. As mentioned above, Data in the Table Workspace is not what gets plotted, when adding the imported data to a Function Bank. When the User clicks the <strong>Add</strong> button to add data to a function bank, the data saved in the currently selected <strong>Import Save Slot</strong> is what gets transferred to the Function Bank. That means when data is imported from Excel/CSV/MAT files it is not yet saved to a Import Save Slot, and thus will not be the data plotted if you click the <strong>Add</strong> button. You need to Select an Import Slot you don't mind overwriting and select hit <strong>Save</strong>, and only then will Add store the most recent data in the selected Function Bank.</li></ul></li>
+    </ul>
+  </body>
+</html>
diff --git a/HTML/MoreHelp.html b/HTML/MoreHelp.html
@@ -0,0 +1,22 @@
+<!DOCTYPE html []>
+<html>
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="author" content="MarkdownViewer++" />
+    <title>MoreHelp.md</title>
+    <style type="text/css">
+
+/* Avoid page breaks inside the most common attributes, especially for exports (i.e. PDF) */
+td, h1, h2, h3, h4, h5, p, ul, ol, li {
+    page-break-inside: avoid; 
+}
+
+        </style>
+  </head>
+  <body>
+    <h3 id="more-help-on-github-page">
+      <strong>More Help on GitHub Page</strong>
+    </h3>
+    <p>If you are having issues beyond what is explained in these Help Tabs, feel free to browse for help on the Project's GitHub page. You will be able to see the source code, latest releases, and can even report an issue through the Issues page linked below. This will generate an email with your issues to every GitHub account that maintains the repository, and offers a clean method for those fixing it to track progress and update you once it has been resolved. Any critiques on the user interface or requests for more features are welcome, and can also be made through the <em>Issues</em> page as well.</p>
+  </body>
+</html>
diff --git a/HTML/PlotSetupHelp.html b/HTML/PlotSetupHelp.html
@@ -0,0 +1,144 @@
+<!DOCTYPE html []>
+<html>
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="author" content="MarkdownViewer++" />
+    <title>PlotSetupHelp.md</title>
+    <style type="text/css">
+
+/* Avoid page breaks inside the most common attributes, especially for exports (i.e. PDF) */
+td, h1, h2, h3, h4, h5, p, ul, ol, li {
+    page-break-inside: avoid; 
+}
+
+        </style>
+  </head>
+  <body>
+    <h3 id="plot-setup-tab-configuring-the-plot-to-your-liking">
+      <strong>Plot Setup Tab: Configuring the plot to your liking</strong>
+    </h3>
+    <ul>
+      <li>
+        <h4 id="plot-style">
+          <strong>Plot Style</strong>
+        </h4>
+        <ul>
+          <li>Choose between a normal linear scale or a dB scale.</li>
+        </ul>
+      </li>
+      <li>
+        <h4 id="scale-factor">
+          <strong>Scale Factor</strong>
+        </h4>
+        <ul>
+          <li>In the conversion from linear to dB, there are two common scale factors used depending on convention and the units being measured/reported. In the world of EE, we commonly use 10 for representing Power measurements and 20 for things that can be squared to represent power, like Voltage or Pressure.
+<ul><li>10 for Power</li><li>20 for Pressure, Voltage, etc.</li></ul></li>
+        </ul>
+      </li>
+      <li>
+        <h4 id="radial-label-location">
+          <strong>Radial Label Location</strong>
+        </h4>
+        <ul>
+          <li>This Selection box determines where in the figure the radial axis labels are located.</li>
+        </ul>
+      </li>
+      <li>
+        <h4 id="db-scale-maximum-db-scale-minimum">
+          <strong>dB Scale Maximum &amp; dB Scale Minimum</strong>
+        </h4>
+        <ul>
+          <li>Conventionally, a dB polar plot for displaying directivity will have a maximum of 0 and a minimum of 40, but these values may be tweaked to suit more flexible needs.</li>
+        </ul>
+      </li>
+      <li>
+        <h4 id="y-minimum">
+          <strong>Y Minimum</strong>
+        </h4>
+        <ul>
+          <li>This value adjusts how much room is left below the origin of the polar plot. For plots where the entire functions fall between -90 and 90 degrees, this can be set to 0, but when you want the full 360 degrees displayed this should be set to 1.</li>
+        </ul>
+      </li>
+      <li>
+        <h4 id="theta-label-step-value">
+          <strong>Theta Label Step Value</strong>
+        </h4>
+        <ul>
+          <li>This parameter adjusts at which angle increments the angle label lines are drawn in the background of the plot. Default is 30 degrees.</li>
+        </ul>
+      </li>
+      <li>
+        <h4 id="max-theta">
+          <strong>Max Theta</strong>
+        </h4>
+        <ul>
+          <li>This parameter adjusts the maximum +- angle drawn on for angle label lines. If you only want the top half of the polar plot, you may set this to 90, otherwise keeping this at 180 will be sufficient for most cases.</li>
+        </ul>
+      </li>
+      <li>
+        <h4 id="radial-label-values-decreasing-order">
+          <strong>Radial Label Values: Decreasing Order</strong>
+        </h4>
+        <ul>
+          <li>This field is where the radius labels are entered. To work correctly, they must be entered in decreasing order.
+<ul><li>For linear plots they should start from a maximum like 1, and decrease. They should not contain 0.</li><li>For dB plots, they should start at a maximum less than or equal to the defined <strong>dB Scale Maximum</strong> and decrease.</li></ul></li>
+        </ul>
+      </li>
+      <li>
+        <h4 id="radial-label-value-one-sided-bandwidths">
+          <strong>Radial Label Value One Sided Bandwidths</strong>
+        </h4>
+        <ul>
+          <li>This field is where shape of the plot template is defined, for each <strong>Radial Label Value</strong> listed above, specify what the maximum (one sided) angle you want that radial arch to cross is. You must have atleast the same amount of values here as in the <strong>Radial Label Value</strong> field.
+<ul><li><strong>For 360 Degree Plots</strong> If you want 360 degree plots, you must set every one of these values to 180. This will allow all of the radius marker lines to swing from -180 to 180 degrees.</li><li><strong>For 180 Degree Plots</strong> If you only want to see the top half of the plot, you must set every one of these values to 90. This will allow all of the radius marker lines to swing from -90 to 90 degrees.</li></ul></li>
+        </ul>
+      </li>
+      <li>
+        <h4 id="default-settings-modes">
+          <strong>Default Settings Modes</strong>
+        </h4>
+        <ul>
+          <li>These Toggle buttons offer a few pre-configured settings for many use cases.</li>
+        </ul>
+      </li>
+      <li>
+        <h4 id="half-power-helper-line">
+          <strong>Half Power Helper Line</strong>
+        </h4>
+        <ul>
+          <li>This Toggle button enables/disables the drawing of the -3dB marker line. This is useful for many engineering applications, and is plotted with grey dotted lines. For dB plots it is always drawn at -3dB, but for linear plots it is either drawn at 0.707 or 0.5, depending on the selected Scale Factor.</li>
+        </ul>
+      </li>
+      <li>
+        <h4 id="discard-redundant-mirrors">
+          <strong>Discard Redundant Mirrors</strong>
+        </h4>
+        <ul>
+          <li>This Toggle button enables/disables the plotting of functions (that the application determines sufficiently symmetrical over the horizontal axis) below the horizontal axis.
+<ul><li>For 360° plots this setting depends on your preference.</li><li>For 180° plots the setting should have no effect.</li></ul></li>
+        </ul>
+      </li>
+      <li>
+        <h4 id="legend-settings">
+          <strong>Legend Settings</strong>
+        </h4>
+        <ul>
+          <li>The user can configure if/where the Legend appears near the plot. After updating any of these settings click <strong>Plot Function</strong> again to update the display.</li>
+        </ul>
+      </li>
+      <li>
+        <h4 id="custom-settings-files">
+          <strong>Custom Settings Files</strong>
+        </h4>
+        <ul>
+          <li>These Export and Load buttons allow user defined configurations to be saved for later or shared with others. The settings fields that will be saved/loaded are:
+<ul><li>Plot Style</li><li>Scale Factor</li><li>Radial Label Location</li><li>dB Scale Maximum</li><li>dB Scale Minimum</li><li>Y Minimum</li><li>Theta Label Step Size</li><li>Max Theta</li><li>Radial Label Values: Decreasing Order</li><li>Radial Label Value One Sided BW</li><li>Half Power Helper Line</li><li>Discard Redundant Mirrors</li><li>Legend Settings</li><li>Function Bank Line Types and Line Colors</li></ul></li>
+          <li>
+            <strong>Export</strong>: To save your current settings click the <strong>Export Settings</strong> button, and specify a File name. This will save your settings as an Excel file, which can be loaded in and parsed later. Be sure to name the file properly.</li>
+          <li>
+            <strong>Load</strong>: To load previously saved settings click the <strong>Load Settings</strong> button, and select the Excel file you would like to load. This will configure all settings to match those saved in the target file.</li>
+        </ul>
+      </li>
+    </ul>
+  </body>
+</html>