diff options
| -rw-r--r-- | paper.tex | 28 |
1 files changed, 13 insertions, 15 deletions
@@ -496,33 +496,31 @@ The high-level connections of this project with previous projects are formalized \subsubsection{Values within text (\inlinecode{project.tex})} \label{sec:valuesintext} -Figures, plots, tables and narrative are not the only analysis products that are included in the paper/report. -In many cases, quantitative values from the analysis are also blended into the sentences of the report's narration. +Figures, plots, tables, datasets, and/or narrative are not the only outputs of a project. +In many cases, quantitative values from the analysis are also blended into the sentences of the report's narration, or published with the dataset in a database. An example is in the abstract of \citet[\href{https://doi.org/10.5281/zenodo.3408481}{zenodo.3408481}, written in Maneage]{akhlaghi19}: ``\emph{... detect the outer wings of M51 down to S/N of 0.25 ...}''. -The value `0.25', for the signal-to-noise ratio (S/N), depends on the analysis, and is an output of the analysis just like the paper's figures and plots. -Manually typing such numbers in the narrative can easiliy introduce errors and discourages testing in scientific papers. -Therefore, these values must \emph{also} be automatically generated. +The value `0.25', for the signal-to-noise ratio (S/N), also depends on the analysis, and is thus also an output. +Manually typing such numbers in the narrative is prone to errors and discourages experimentation. To automatically generate and blend them in the text, Maneage uses \LaTeX{} macros. For example, the \LaTeX{} source of the quote above is: ``\inlinecode{\small detect the outer wings of M51 down to S/N of \$\textbackslash{}demo\-sf\-optimized\-sn\$}''. The ma\-cro ``\inlinecode{\small\textbackslash{}demosfoptimizedsn}'' is automatically created during the project. It expands to the value ``\inlinecode{0.25}'' when the PDF output is built. All such values are referenced in \inlinecode{project.tex}. - -However, managing all the necessary \LaTeX{} macros in a single file would violate the modularity principle and would be frustrating and bug-prone. -Thus, Maneage adopts the convention that all subMakefiles \emph{must} contain a fixed target with the same unsuffixed filename, but with a \inlinecode{.tex} suffix to store calculated values generated by that subMakefile. -If this file does not need to report any values, it may be left empty. -In Figure \ref{fig:datalineage}, these macro files can be seen in every subMakefile, except for \inlinecode{paper.mk}. -These \LaTeX{} macro files form the core skeleton of a Maneage project: as shown in Figure \ref{fig:datalineage}, the outward arrows of all built files of any subMakefile ultimately lead to one of these \LaTeX{} macro files. +However, managing them in a single file would violate the modularity principle, be hard to parallelize, frustrating to manage, and bug-prone. +All subMakefiles thus contain a fixed target with the same name but a different suffix: \inlinecode{.tex} instead of \inlinecode{.mk}, hosting values generated in that subMakefile. +Figure \ref{fig:datalineage} shows them as built products of every subMakefile, except for \inlinecode{paper.mk}. +These \LaTeX{} macro files form the core skeleton of a Maneage project: as shown in Figure \ref{fig:datalineage}, the outward arrows of all built files in any subMakefile ultimately lead to one of these \LaTeX{} macro files. \subsubsection{Verification of outputs (\inlinecode{verify.mk})} \label{sec:outputverification} -Before the modular \LaTeX{} macro files of Section \ref{sec:valuesintext} are merged into the single \inlinecode{project.tex} file, they need to pass through the verification filter, which implements another core principle of Maneage (\ref{principle:verify}). -Confirming the checksum of the final PDF or of figures and datasets is not generally useful: many tools write the creation date into the produced files. -To avoid this, the raw data must be verified independent of metadata like dates. +Before the modular \LaTeX{} macro files described above are merged into the single \inlinecode{project.tex} file, they need to pass through the verification filter, which implements another core principle of Maneage, \ref{principle:verify}. +Confirming the checksum of the final PDF or of figures and datasets is not generally useful because many tools write the creation date into the files. +To avoid this, the raw data must be verified independent of metadata like date. Some standards include such date-independent verification features, for example, the \inlinecode{DATASUM} keyword in the FITS format \citep{pence10}. To facilitate output verification, Maneage has the \inlinecode{verify.mk} subMakefile that separates the analytical phase of the paper from the production of the report (see Figure \ref{fig:datalineage}). -This file implements some tests on pre-defined formats. Other formats can easily be added. +This file implements some tests on pre-defined formats. +Other formats can easily be added. \subsubsection{The analysis} \label{sec:analysis} |