aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--paper.tex165
-rw-r--r--tex/src/references.tex100
2 files changed, 165 insertions, 100 deletions
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
diff --git a/tex/src/references.tex b/tex/src/references.tex
index 02a7d50..2610874 100644
--- a/tex/src/references.tex
+++ b/tex/src/references.tex
@@ -8,26 +8,82 @@
%% notice and this notice are preserved. This file is offered as-is,
%% without any warranty.
-@ARTICLE{bacon17,
- author = {{Bacon}, R. and {Conseil}, S. and {Mary}, D. and {Brinchmann}, J. and
- {Shepherd}, M. and {Akhlaghi}, M. and {Weilbacher}, P.~M. and
- {Piqueras}, L. and {Wisotzki}, L. and {Lagattuta}, D. and {Epinat}, B. and
- {Guerou}, A. and {Inami}, H. and {Cantalupo}, S. and {Courbot}, J.~B. and
- {Contini}, T. and {Richard}, J. and {Maseda}, M. and {Bouwens}, R. and
- {Bouch{\'e}}, N. and {Kollatschny}, W. and {Schaye}, J. and
- {Marino}, R.~A. and {Pello}, R. and {Herenz}, C. and {Guiderdoni}, B. and
- {Carollo}, M.},
- title = "{The MUSE Hubble Ultra Deep Field Survey. I. Survey description, data reduction, and source detection}",
- journal = {A\&A},
-archivePrefix = "arXiv",
- eprint = {1710.03002},
- keywords = {galaxies: distances and redshifts, galaxies: high-redshift, cosmology: observations, methods: data analysis, techniques: imaging spectroscopy, galaxies: formation},
- year = 2017,
- month = nov,
- volume = 608,
- eid = {A1},
- pages = {A1},
- doi = {10.1051/0004-6361/201730833},
- adsurl = {http://adsabs.harvard.edu/abs/2017A\%26A...608A...1B},
- adsnote = {Provided by the SAO/NASA Astrophysics Data System}
+@ARTICLE{akhlaghi20,
+ author = {{Akhlaghi}, Mohammad and {Infante-Sainz}, Ra{\'u}l and
+ {Roukema}, Boudewijn F. and {Valls-Gabaud}, David and
+ {Baena-Gall{\'e}}, Roberto},
+ title = "{Towards Long-term and Archivable Reproducibility}",
+ journal = {arXiv e-prints},
+ year = 2020,
+ month = jun,
+ eid = {arXiv:2006.03018},
+ pages = {arXiv:2006.03018},
+archivePrefix = {arXiv},
+ eprint = {2006.03018},
+ primaryClass = {cs.DL},
+ adsurl = {https://ui.adsabs.harvard.edu/abs/2020arXiv200603018A},
+ adsnote = {Provided by the SAO/NASA Astrophysics Data System}
+}
+
+
+
+
+
+@ARTICLE{alliez19,
+ author = {{Alliez}, Pierre and {Di Cosmo}, Roberto and {Guedj}, Benjamin and
+ {Girault}, Alain and {Hacid}, Mohand-Said and {Legrand}, Arnaud and
+ {Rougier}, Nicolas P.},
+ title = "{Attributing and Referencing (Research) Software: Best Practices and Outlook from Inria}",
+ journal = {CiSE},
+ volume = {22},
+ year = "2020",
+ month = "Jan",
+ pages = {39-52},
+archivePrefix = {arXiv},
+ eprint = {1905.11123},
+ primaryClass = {cs.DL},
+ doi = {10.1109/MCSE.2019.2949413},
+ adsurl = {https://ui.adsabs.harvard.edu/abs/2019arXiv190511123A},
+ adsnote = {Provided by the SAO/NASA Astrophysics Data System}
+}
+
+
+
+
+
+@ARTICLE{infantesainz20,
+ author = {{Infante-Sainz}, Ra{\'u}l and {Trujillo}, Ignacio and
+ {Rom{\'a}n}, Javier},
+ title = "{The Sloan Digital Sky Survey extended point spread functions}",
+ journal = {MNRAS},
+ year = 2020,
+ month = feb,
+ volume = {491},
+ number = {4},
+ pages = {5317-5329},
+ doi = {10.1093/mnras/stz3111},
+archivePrefix = {arXiv},
+ eprint = {1911.01430},
+ primaryClass = {astro-ph.IM},
+ adsurl = {https://ui.adsabs.harvard.edu/abs/2020MNRAS.491.5317I},
+ adsnote = {Provided by the SAO/NASA Astrophysics Data System}
+}
+
+
+
+
+
+@ARTICLE{akhlaghi19,
+ author = {{Akhlaghi}, Mohammad},
+ title = "{Carving out the low surface brightness universe with NoiseChisel}",
+ journal = {IAU Symposium 335},
+ year = 2019,
+ month = sep,
+ eid = {arXiv:1909.11230},
+ pages = {arXiv:1909.11230},
+archivePrefix = {arXiv},
+ eprint = {1909.11230},
+ primaryClass = {astro-ph.IM},
+ adsurl = {https://ui.adsabs.harvard.edu/abs/2019arXiv190911230A},
+ adsnote = {Provided by the SAO/NASA Astrophysics Data System}
}