Cox Proportional Hazards: Edit documentation to maintain consistency

Author: Chuck Litzell

src/ports/postgres/modules/stats/cox_prop_hazards.sql_in

@@ -18,8 +18,8 @@ m4_include(`SQLCommon.m4')
 <div class="toc"><b>Contents</b>
 <ul>
 <li class="level1"><a href="#training">Training Function</a>
+<li class="level1"><a href="#cox_zph">PHA Test Function</a>
 <li class="level1"><a href="#examples">Examples</a></li>
-<li class="level1"><a href="#cox_zph">PHA test function</a>
 <li class="level1"><a href="#background">Technical Background</a></li>
 <li class="level1"><a href="#related">Related Topics</a></li>
 </ul>
@@ -38,22 +38,20 @@ the probability that death has happened before time t.
 
 Following is the syntax for the coxph_train() training function:
 <pre class="syntax">
-coxph_train(
-    source_table,
-    output_table,
-    dependent_variable,
-    independent_variable,
-    right_censoring_status,
-    strata,
-    optimizer_params
-)
+coxph_train( source_table, 
+             output_table, 
+             dependent_variable, 
+             independent_variable, 
+             right_censoring_status, 
+             strata, 
+             optimizer_params
+           )
 </pre>
-
 \b Arguments
 <dl class="arglist">
     <dt>source_table</dt>
     <dd>TEXT. The name of the table containing input data.</dd>
-    <dt>out_table</dt>
+    <dt>output_table</dt>
     <dd>TEXT. The name of the table where the output model is saved.
         The output is saved in the table named by the <em>output_table</em> argument. It has the following columns:
         <table class="output">
@@ -63,7 +61,7 @@ coxph_train(
             </tr>
             <tr>
                 <th>loglikelihood</th>
-                <td>FLOAT8. Log-likelihood value of the MLE estimate</td>
+                <td>FLOAT8. Log-likelihood value of the MLE estimate.</td>
             </tr>
             <tr>
                 <th>std_err</th>
@@ -79,29 +77,29 @@ coxph_train(
             </tr>
             <tr>
                 <th>hessian</th>
-                <td>The vectorized Hessian matrix computed using the final solution.</td>
+                <td>FLOAT8[]. The vectorized Hessian matrix computed using the final solution.</td>
             </tr>
             <tr>
                 <th>num_iterations</th>
-                <td>The number of iterations performed by the optimizer</td>
+                <td>INTEGER. The number of iterations performed by the optimizer.</td>
             </tr>
         </table>
     </dd>
-    <dd> Additionally, an output summary table is also generated that contains
-    a summary of the parameters used for building the cox model. It is stored
+    <dd> Additionally, a summary output table is generated that contains
+    a summary of the parameters used for building the Cox model. It is stored
     in a table named <em>output_table</em>_summary. It has the following columns:
     <table class="output">
         <tr>
             <th>source_table</th>
-            <td>Source table name</td>
+            <td>The source table name.</td>
         </tr>
         <tr>
             <th>dep_var</th>
-            <td>dependent variable name</td>
+            <td>The dependent variable name.</td>
         </tr>
         <tr>
             <th>ind_var</th>
-            <td>independent variable name</td>
+            <td>The independent variable name.</td>
         </tr>
         <tr>
             <th>right_censoring_status</th>
@@ -116,7 +114,7 @@ coxph_train(
 
     <dt>dependent_variable</dt>
     <dd>TEXT. A string containing the name of a column that contains
-        an array of numeric values, or a string expression in the format 'array[1, x1, x2, x3]',
+        an array of numeric values, or a string expression in the format 'ARRAY[1, x1, x2, x3]',
         where <em>x1</em>, <em>x2</em> and <em>x3</em> are column names. Dependent
         variables refer to the time of death. There is no need to pre-sort the data.</dd>
     <dt>independent_variable</dt>
@@ -128,78 +126,60 @@ coxph_train(
         expression (i.e., 'true', 'false', '0', '1') that applies to all observations,
         or a Boolean expression such as 'column_name < 10' that can be evaluated for each
         observation.</dd>
-    <dt>strata</dt>
-    <dd>VARCHAR, default: NULL, which does not do any stratifications. It should be a string that contains the column names separated by commas, which are the columns (strata ID variables) used to do stratification.</dd>
-    <dt>optimizer_params</dt>
+    <dt>strata (optional)</dt>
+    <dd>VARCHAR, default: NULL, which does not do any stratifications. A string of comma-separated column names that are the strata ID variables used to do stratification.</dd>
+    <dt>optimizer_params (optional)</dt>
     <dd>VARCHAR, default: NULL, which uses the default values of optimizer parameters: max_iter=20, optimizer='newton', tolerance=1e-4. It should be a string that contains pairs of 'key=value' separated by commas.</dd>
 </dl>
 
-@anchor notes
-@par Notes
-
-- All table names can be optionally schema qualified (current_schemas() would be
-used if a schema name is not provided) and all table and column names
-should follow case-sensitivity and quoting rules per the database.
-(For instance, 'mytable' and 'MyTable' both resolve to the same entity, i.e. 'mytable'.
-If mixed-case or multi-byte characters are desired for entity names then the
-string should be double-quoted; in this case the input would be '"MyTable"').
-
-- The cox_prop_hazards_regr() and cox_prop_hazards() functions have been
-deprecated; coxph_train() should be used instead.
-
 @anchor cox_zph
-@par Test the Proportional Hazards Assumption of a Cox Regression
+@par Proportional Hazards Assumption Test Function
 
-Proportional-Hazard models enable the comparison of various survival models.
+The cox_zph() function tests the proportional hazards assumption (PHA) of a Cox regression.
+
+Proportional-hazard models enable the comparison of various survival models.
 These PH models, however, assume that the hazard for a given individual is a
 fixed proportion of the hazard for any other individual, and the ratio of the
-hazards is constant across time. We currently don't provide performing any
-transformation of the time to compute the correlation.
+hazards is constant across time. MADlib does not currently have support for
+performing any transformation of the time to compute the correlation.
 
 The <em>cox_zph()</em> function is used to test this assumption by computing the correlation
 of the residual of the coxph_train model with time.
 
-To display a brief summary of the PH assumption test function, call the \ref cox_zph()
-function with no argument:
-@verbatim
-SELECT madlib.cox_zph();
-@endverbatim
-
 Following is the syntax for the cox_zph() function:
 <pre class="syntax">
-cox_zph(
-    cox_model_table,
-    output_table
-)
+cox_zph( cox_model_table, 
+         output_table 
+       )
 </pre>
-
 \b Arguments
 <dl class="arglist">
     <dt>cox_model_table</dt>
-    <dd>TEXT. The name of the table containing the Cox Proportional-Hazards model</dd>
+    <dd>TEXT. The name of the table containing the Cox Proportional-Hazards model.</dd>
 
     <dt>output_table</dt>
-    <dd>TEXT. The name of the table where the test statistics are saved</dd>
+    <dd>TEXT. The name of the table where the test statistics are saved. 
         The output table is named by the <em>output_table</em> argument and has
-        the following columns
+        the following columns:
         <table class="output">
             <tr>
                 <th>rho</th>
                 <td>FLOAT8[]. Vector of the correlation coefficients between
-                survival time and the scaled Schoenfeld residuals </td>
+                survival time and the scaled Schoenfeld residuals.</td>
             </tr>
             <tr>
                 <th>chi_square</th>
-                <td> FLOAT8[]. Chi-square test statistic for the correlation analysis</td>
+                <td> FLOAT8[]. Chi-square test statistic for the correlation analysis.</td>
             </tr>
             <tr>
                 <th>p_value</th>
-                <td>FLOAT8[]. Two-side p-value for the chi-square statistic</td>
+                <td>FLOAT8[]. Two-side p-value for the chi-square statistic.</td>
             </tr>
         </table>
+    </dd>
 </dl>
 
-Additionally, the residual values are outputed in table named as <em>output_table</em>_residual.
+Additionally, the residual values are outputted to the table named <em>output_table</em>_residual.
 The table contains the following columns:
         <table class="output">
             <tr>
@@ -213,19 +193,31 @@ The table contains the following columns:
             </tr>
             <tr>
                 <th>scaled_reisdual</th>
-                <td>Residual values scaled by the variance of the coefficients</td>
+                <td>Residual values scaled by the variance of the coefficients.</td>
             </tr>
         </table>
 
+@anchor notes
+@par Notes
+
+- Table names can be optionally schema qualified (current_schemas() is
+used if a schema name is not provided) and table and column names
+should follow case-sensitivity and quoting rules per the database.
+For instance, 'mytable' and 'MyTable' both resolve to the same entity&mdash;'mytable'.
+If mixed-case or multi-byte characters are desired for entity names then the
+string should be double-quoted; in this case the input would be '"MyTable"'.
+
+- The cox_prop_hazards_regr() and cox_prop_hazards() functions have been
+deprecated; coxph_train() should be used instead.
+
 @anchor examples
 @examp
 -# View online help for the proportional hazards training method.
 <pre class="example">
 SELECT madlib.coxph_train();
-SELECT madlib.coxph_train('usage');
 </pre>
 
--# Create an input data set:
+-# Create an input data set.
 <pre class="example">
 DROP TABLE IF EXISTS sample_data;
 CREATE TABLE sample_data (
@@ -262,16 +254,16 @@ COPY sample_data FROM STDIN DELIMITED BY '|';
  24 |   1 |    5 |         1 | t
 \.
 </pre>
--# Run the cox regression function:
+-# Run the Cox regression function.
 <pre class="example">
-SELECT madlib.coxph_train(
-    'sample_data',
-    'sample_cox',
-    'timedeath',
-    'ARRAY[grp,wbc]',
-    'status');
+SELECT madlib.coxph_train( 'sample_data', 
+                           'sample_cox', 
+                           'timedeath', 
+                           'ARRAY[grp,wbc]', 
+                           'status'
+                         );
 </pre>
--# View the results of the regression:
+-# View the results of the regression.
 <pre class="example">
 \\x on
 SELECT * FROM sample_cox;
@@ -284,20 +276,19 @@ std_err  | {0.677308807341768,0.387308633304678}
 z_stats  | {3.75676700265663,4.31653830257251}
 p_values | {0.000172122613528057,1.58495189046891e-05}
 </pre>
--# View online help for function to test Proportional Hazards assumption
+-# View online help for the function to test Proportional Hazards Assumption.
 <pre class="example">
-SELECT madlid.cox_zph();
-SELECT madlib.cox_zph('usage');
+SELECT madlib.cox_zph();
 </pre>
 
 -# Run the test for Proportional Hazards assumption to obtain correlation between
 residuals and time.
 <pre class="example">
-SELECT madlid.cox_zph(
-    'sample_cox',
-    'sample_zph_output');
+SELECT madlib.cox_zph( 'sample_cox', 
+                       'sample_zph_output'
+                     ); 
 </pre>
--# View results of the PHA test
+-# View results of the PHA test.
 <pre class="example">
 SELECT * FROM sample_zph_output;
 </pre>
@@ -310,22 +301,6 @@ p_value    | {0.991991010621734,0.878854560410758}
 </pre>
 
 
-@anchor seealso
-@sa File cox_prop_hazards.sql_in documenting the functions
-
-@anchor notes
-@note
-
-- Table names can be optionally schema qualified (current_schemas() is
-searched if a schema name is not provided) and table and column names
-should follow case-sensitivity and quoting rules per the database.
-(For instance, 'mytable' and 'MyTable' both resolve to the same entity, i.e. 'mytable'.
-If mixed-case or multi-byte characters are desired for entity names then the
-string should be double-quoted; in this case the input would be '"MyTable"'.
-
-- The cox_prop_hazards_regr() function has been deprecated, and
-cox_prop_hazards() should be used instead.
-
 @anchor background
 @par Technical Background