From db2bd887f76e8860d728fd84a5eb84f3e41f640e Mon Sep 17 00:00:00 2001 From: Mohammad Akhlaghi Date: Wed, 10 Jun 2020 02:28:01 +0100 Subject: Updated text of default paper.tex, putting more recent examples The text of the default paper hadn't been changed for a very long time! In this time, three papers using Maneage have been published (which can be very good as an example), Maneage also now has a webpage! With these commit these examples and the webpage have been added and generally it was also polished a little to hopefully be more useful. --- paper.tex | 165 +++++++++++++++++++++++++++++++++----------------------------- 1 file changed, 87 insertions(+), 78 deletions(-) (limited to 'paper.tex') diff --git a/paper.tex b/paper.tex index 0993e73..f1ca48f 100644 --- a/paper.tex +++ b/paper.tex @@ -63,25 +63,32 @@ %% Project abstract and keywords. \includeabstract{ - You have completed the reproducible paper template and are ready to - configure and implement it for your own research. This template contains - almost all the elements that you will need in a research project - containing the downloading of raw data and necessary software, building - the software, and processing the data with the software in a - highly-controlled environment. It then allows including the results in - plots and producing the final report, including this abstract, figures - and bibliography. If you design your project with this template's - infra-structure in your work, don't forget to add a notice and clearly - let the readers know that your work is reproducible. If this template - proves useful in your research, please cite \citet{gnuastro}. + Welcome to Maneage (\emph{Man}aging data lin\emph{eage}) and reproducible + papers/projects, for a review of the basics of this system, please see + \citet{akhlaghi20}. You are now ready to configure Maneage and implement + your own research in this framework. Maneage contains almost all the + elements that you will need in a research project, and adding any missing + parts is very easy once you become familiar with it. For example it + already has steps to downloading of raw data and necessary software + (while verifying them with their checksums), building the software, and + processing the data with the software in a highly-controlled + environment. But Maneage is not just for the analysis of your project, + you will also write your paper in it (by replacing this text in + \texttt{paper.tex}): including this abstract, figures and + bibliography. If you design your project with Maneage's infra-structure, + don't forget to add a notice and clearly let the readers know that your + work is reproducible, we should spread the word and show the world how + useful reproducible research is for the sciences, also don't forget to + cite and acknowledge it so we can continue developing it. This PDF was + made with Maneage, commit \projectversion{}. \vspace{0.25cm} \textsl{Keywords}: Add some keywords for your research here. \textsl{Reproducible paper}: All quantitave results (numbers and plots) - in this paper are exactly reproducible with Maneage (version \projectversion{}, - \url{https://maneage.org}).} + in this paper are exactly reproducible with Maneage + (\url{https://maneage.org}). } %% To add the first page's headers. \thispagestyle{firststyle} @@ -93,23 +100,45 @@ %% Start of main body. \section{Congratulations!} Congratulations on running the raw template project! You can now follow the -checklist in the \texttt{README.md} file to customize this template to your -exciting research project. - -Just don't forget to \emph{never} use numbers or fixed strings (for example -database urls like \url{\wfpctwourl}) directly within your \LaTeX{} -source. Read them directly from your configuration files, or processing -outputs, and import them into \LaTeX{} as macros through the -\texttt{tex/build/macros/project.tex} file (created after running the -project). See the several existing examples within the template for a -demonstration. For some recent real-world examples, the reproducible -project sources for Sections 4 and 7.3 of \citet{bacon17} are available at -\href{https://doi.org/10.5281/zenodo.1164774}{zenodo.1164774}\footnote{\url{https://gitlab.com/makhlaghi/muse-udf-origin-only-hst-magnitudes}}, -or -\href{https://doi.org/10.5281/zenodo.1163746}{zenodo.1163746}\footnote{\url{https://gitlab.com/makhlaghi/muse-udf-photometry-astrometry}}. Working +``Customization checklist'' in the \texttt{README-hacking.md} file, +customize this template and start your exciting research project over +it. You can always merge Maneage back into your project to improve its +infra-structure and leaving your own project intact. If you haven't already +read \citet{akhlaghi20}, please do so before continuing, it isn't long +(just 7 pages). + +While you are writing your paper, just don't forget to \emph{not} use +numbers or fixed strings (for example database urls like \url{\wfpctwourl}) +directly within your \LaTeX{} source. Put them in configuration files and +after using them in the analysis, pass them into the \LaTeX{} source +through macros in the same subMakefile that used them. For some already +published examples, please see +\citet{akhlaghi20}\footnote{\url{https://gitlab.com/makhlaghi/maneage-paper}}, +\citet{infantesainz20}\footnote{\url{https://gitlab.com/infantesainz/sdss-extended-psfs-paper}} +and +\citet{akhlaghi19}\footnote{\url{https://gitlab.com/makhlaghi/iau-symposium-355}}. Working in this way, will let you focus clearly on your science and not have to worry about fixing this or that number/name in the text. +Once your project is ready for publication, there is also a ``Publication +checklist'' in \texttt{README-hacking.md} that will guide you in the steps +to do for making your project as FAIR as possible (Findable, Accessibile, +Interoperable, and Reusable). + +The default \LaTeX{} structure within Maneage also has two \LaTeX{} macros +for easy marking of text within your document as \emph{new} and +\emph{notes}. For example, \new{this text has been marked as \texttt{new}.} +\tonote{While this one is marked as \texttt{tonote}.} Please try commenting +the line that defines \texttt{highlightchanges} in \texttt{paper.tex} (by +adding a `\texttt{\%}' at the start of the line or simply deleting the +line). You will then notice that the line that was marked as \texttt{new} +will become black (totally blend in with the rest of the text) and the one +marked \texttt{tonote} will not be in the final PDF. You can thus use +\texttt{highlightchanges} to easily make copies of your research for +existing coauthors (who are just interested in the new parts or notes) and +new co-authors (who don't want to be distracted by these issues in their +first time reading). + Figure \ref{squared} shows a simple plot as a demonstration of creating plots within \LaTeX{} (using the {\small PGFP}lots package). The minimum value in this distribution is $\deletememin$, and $\deletememax$ is the @@ -134,50 +163,31 @@ at the top of this \LaTeX{} source file. Figure \ref{image-histogram} is another demonstration of showing images (datasets) using PGFPlots. It shows a small crop of an image from the -Wide-Field Planetary Camera 2, on board the Hubble Space Telescope from -1993 to 2009. This cropped image is one of the sample FITS files from the -FITS file standard -webpage\footnote{\url{https://fits.gsfc.nasa.gov/fits_samples.html}}. Just -as another basic reporting of measurements on this dataset within the paper -without using numbers in the \LaTeX{} source, the mean is -$\deletemewfpctwomean$ and the median is $\deletemewfpctwomedian$. The -skewness in the histogram of Figure \ref{image-histogram}(b) explains this -difference between the mean and median. The dataset was prepared for -demonstration here with Gnuastro's \textsf{Convert\-Type} program and the +Wide-Field Planetary Camera 2 (that was installed on the Hubble Space +Telescope from 1993 to 2009). As another more realistic demonstration of +reporting results with Maneage, here we report that the mean pixel value in +that image is $\deletemewfpctwomean$ and the median is +$\deletemewfpctwomedian$. The skewness in the histogram of Figure +\ref{image-histogram}(b) explains this difference between the mean and +median. The dataset is visualized here as a black and white image using the +\textsf{Convert\-Type} program of GNU Astronomy Utilities (Gnuastro). The histogram and basic statstics were generated with Gnuastro's \textsf{Statistics} program. {\small PGFP}lots\footnote{\url{https://ctan.org/pkg/pgfplots}} is a great tool to build the plots within \LaTeX{} and removes the necessity to add -further dependencies (to create the plots) to your project. There are -high-level language libraries like Matplotlib which also generate -plots. However, the problem is that they require many dependencies (Python, -Numpy and etc). Installing these dependencies from source, is not easy and -will harm the reproducibility of your paper. Note that after several years, -the binary files of these high-level libraries, that you easily install -today, will no longer be available in common repositories. Therefore -building the libraries from source is the only option to reproduce your -results. - -Furthermore, since {\small PGFP}lots is built by \LaTeX{} it respects all -the properties of your text (for example line width and fonts and -etc). Therefore the final plot blends in your paper much more nicely. It -also has a wonderful +further dependencies, just to create the plots. There are high-level +libraries like Matplotlib which also generate plots. However, the problem +is that they require \emph{many} dependencies, for example see Figure 1 of +\citet{alliez19}. Installing these dependencies from source, is not easy +and will harm the reproducibility of your paper in the future. + +Furthermore, since {\small PGFP}lots builds the plots within \LaTeX{}, it +respects all the properties of your text (for example line width and fonts +and etc). Therefore the final plot blends in your paper much more +nicely. It also has a wonderful manual\footnote{\url{http://mirrors.ctan.org/graphics/pgf/contrib/pgfplots/doc/pgfplots.pdf}}. -This template also defines two \LaTeX{} macros that allow you to mark text -within your document as \emph{new} and \emph{notes}. For example, \new{this - text has been marked as \texttt{new}.} \tonote{While this one is marked - as \texttt{tonote}.} If you comment the line (by adding a `\texttt{\%}' -at the start of the line or simply deleting the line) that defines -\texttt{highlightchanges}, then the one that was marked \texttt{new} will -become black (totally blend in with the rest of the text) and the one -marked \texttt{tonote} will not be in the final PDF. You can thus use -\texttt{highlightchanges} to easily make copies of your research for -existing coauthors (who are just interested in the new parts or notes) and -new co-authors (who don't want to be distracted by these issues in their -first time reading). - \begin{figure}[t] \includetikz{delete-me-image-histogram}{width=\linewidth} @@ -193,15 +203,15 @@ first time reading). \section{Notice and citations} To encourage other scientists to publish similarly reproducible papers, please add a notice close to the start of your paper or in the end of the -abstract clearly mentioning that your work is fully reproducible. - -For the time being, we haven't written a specific paper only for this -template. Until then, we would be grateful if you could cite the first -paper that used the early versions of this template: \citet{gnuastro}. - -After publication, don't forget to upload all the necessary data, software -source code and the project's source to a long-lasting host like Zenodo -(\url{https://zenodo.org}). +abstract clearly mentioning that your work is fully reproducible. One +convention we have adopted until now is to put the Git checkum of the +project as the last word of the abstract, for example see +\citet{akhlaghi19}, \citet{infantesainz20} and \citet{akhlaghi20} + +Finally, don't forget to cite \citet{akhlaghi20} and acknowledge the +funders mentioned below. Otherwise we won't be able to continue working on +Maneage. Also, just as another reminder, before publication, don't forget +to follow the ``Publication checklist'' of \texttt{README-hacking.md}. %% End of main body. @@ -210,11 +220,10 @@ source code and the project's source to a long-lasting host like Zenodo \section{Acknowledgements} \new{Please include the following two paragraphs in the Acknowledgement - section of your paper. This reproducible paper template was developed in - parallel with Gnuastro, so it benefited from the same grants. If you - don't use Gnuastro in your final/customized project, please remove it - from the paragraph below, only mentioning the reproducible paper - template.} + section of your paper. Maneage was developed in parallel with Gnuastro, + so it benefited from the same grants. If you don't use Gnuastro in your + final/customized project, please remove it from the paragraph below, only + mentioning the reproducible paper template.} This research was partly done using GNU Astronomy Utilities (Gnuastro, ascl.net/1801.009), and the reproducible paper template -- cgit v1.2.1