diff options
| -rw-r--r-- | Makefile | 16 | ||||
| -rw-r--r-- | README.md | 122 | ||||
| -rw-r--r-- | paper.tex | 86 | ||||
| -rw-r--r-- | reproduce/config/pipeline/delete-me-num.mk | 2 | ||||
| -rw-r--r-- | reproduce/src/make/delete-me.mk | 73 | ||||
| -rw-r--r-- | reproduce/src/make/initialize.mk | 6 | ||||
| -rw-r--r-- | reproduce/src/make/paper.mk | 33 | ||||
| -rw-r--r-- | tex/delete-me.tex | 17 | ||||
| -rw-r--r-- | tex/preamble-biblatex.tex | 2 | ||||
| -rw-r--r-- | tex/preamble-pgfplots.tex | 4 | ||||
| -rw-r--r-- | tex/preamble-style.tex | 2 | ||||
| -rw-r--r-- | tex/references.tex | 45 |
12 files changed, 374 insertions, 34 deletions
@@ -61,10 +61,11 @@ all: reproduce/build paper.pdf # high-level processing Makefiles are included through the `foreach' loop # below by explicitly requesting them in a specific order here. include reproduce/config/pipeline/*.mk -include $(foreach f, initialize \ - download \ - paper, \ - reproduce/src/make/$(f).mk) +include $(foreach f, initialize \ + download \ + delete-me \ + paper \ + , reproduce/src/make/$(f).mk) @@ -88,9 +89,10 @@ include $(foreach f, initialize \ # Note that if you don't want the final PDF and just want the processing # and file outputs, you can remove the value of the `pdf-build-final' # variable in `reproduce/config/pdf-build.mk'. -tex/pipeline.tex: $(foreach f, initialize \ - download, \ - $(mtexdir)/$(f).tex) +tex/pipeline.tex: $(foreach f, initialize \ + download \ + delete-me \ + , $(mtexdir)/$(f).tex) # If no PDF is requested, then just exit here. ifeq ($(pdf-build-final),) @@ -26,7 +26,7 @@ perfect) language/framework for a research reproduction pipeline and how to master Make easily (and freely). An introduction is then given to the general architecture of the pipeline. It is followed by a checklist of steps that are necessary to start customizing this pipeline for your -research. The main body finishs with some tips and guidelines on how to +research. The main body finishes with some tips and guidelines on how to manage or extend the pipeline as your research grows based on our experiences with it so far. As discussed above, in the appendix, a short introduction on the necessity of reproducible science is given. Please @@ -35,6 +35,8 @@ them and make it even more easier to use and more robust/generic. + + Why Make? --------- @@ -90,6 +92,8 @@ GNU Make, please inform us to correct it. + + How can I learn Make? --------------------- @@ -125,6 +129,8 @@ Make manual there also. + + Published works using this pipeline ----------------------------------- @@ -133,20 +139,63 @@ published using the method of this pipeline. Note that this pipeline is evolving, so some small details may be different in them, but they can be used as a good working model to build your own. - - Section 7.3 of Bacon et al. (2017, A&A 608, A1): The version controlled - reproduction pipeline is available [on + - Section 7.3 of Bacon et + al. ([2017](http://adsabs.harvard.edu/abs/2017A%26A...608A...1B), A&A + 608, A1): The version controlled reproduction pipeline is available [on Gitlab](https://gitlab.com/makhlaghi/muse-udf-origin-only-hst-magnitudes) and a snapshot of the pipeline along with all the necessary input datasets and outputs is available in [zenodo.1164774](https://doi.org/10.5281/zenodo.1164774). - - Section 4 of Bacon et al. (2017, A&A, 608, A1): The version controlled - reproduction pipeline is available [on + - Section 4 of Bacon et + al. ([2017](http://adsabs.harvard.edu/abs/2017A%26A...608A...1B), A&A, + 608, A1): The version controlled reproduction pipeline is available [on Gitlab](https://gitlab.com/makhlaghi/muse-udf-photometry-astrometry) and a snapshot of the pipeline along with all the necessary input datasets is available in [zenodo.1163746](https://doi.org/10.5281/zenodo.1163746). + - Akhlaghi & Ichikawa + ([2015](http://adsabs.harvard.edu/abs/2015ApJS..220....1A), ApJS, 220, + 1): The version controlled reproduction pipeline is available [on + Gitlab](https://gitlab.com/makhlaghi/NoiseChisel-paper). This is the + very first (and much less mature) implementation of this pipeline: the + history of this template pipeline started more than two years after that + paper was published. It is a very rudimentary/initial implementation, + thus it is only included here for historical reasons. However, the + pipeline is complete and accurate and uploaded to arXiv along with the + paper. See the more recent implementations if you want to get ideas for + your version of this pipeline. + + + + + +Citation +-------- + +A paper will be published to fully describe this reproduction +pipeline. Until then, if this pipeline is useful in your work, please cite +the paper that implemented the first version of this pipeline: Akhlaghi & +Ichikawa ([2015](http://adsabs.harvard.edu/abs/2015ApJS..220....1A), ApJS, +220, 1). + +The experience gained with this template after several more implementations +will be used to make this pipeline robust enough for a complete and useful +paper to introduce to the community afterwards. + +Also, when your paper is published, don't forget to add a notice in your +own paper (in coordination with the publishing editor) that the paper is +fully reproducible and possibly add a sentence or paragraph in the end of +the paper shortly describing the concept. This will help spread the word +and encourage other scientists to also publish their reproduction +pipelines. + + + + + + @@ -214,7 +263,7 @@ Makefile uses the `foreach` function to read them in a specific order. The main body of this pipeline is thus going to be managed within the workhorse-Makefiles of `reproduce/src/make`. If you set clear-to-understand -names for thse workhorse-Makefiles and follow the convention of the top +names for these workhorse-Makefiles and follow the convention of the top Makefile that you only include one workhorse-Makefile per line, the `foreach` loop of the top Makefile that imports them will become very easy to read and understand by eye. This will let you know which step you are @@ -265,6 +314,8 @@ this is how a project is designed to grow in this framework. + + Summary ------- @@ -295,6 +346,11 @@ mind are listed below. + + + + + Checklist to customize the pipeline =================================== @@ -319,8 +375,8 @@ been explained here), please let us know to correct it. always remember to add a similar copyright statement at the top of the file. - - **Title**, **short description** and **author** of project: In this raw - skeleton, the title or short description of your project should be + - **Title**, **short description** and **author** in source files: In this + raw skeleton, the title or short description of your project should be added in the following two files: `Makefile` (the first line), and `tex/preamble-style.tex` (the last few lines, along with the names of you and your colleagues). In both cases, the texts you should replace @@ -349,7 +405,7 @@ been explained here), please let us know to correct it. - Delete the description about Gnuastro in `README`. - Delete marked part(s) in `configure`. - Delete marked parts in `reproduce/src/make/initialize.mk`. - - Delete `and Gnuastro \gnuastroversion` from `tex/preamble-style`. + - Delete `and Gnuastro \gnuastroversion` from `tex/preamble-style.tex`. - **Other dependencies**: If there are any more of the dependencies that you don't use (or others that you need), then remove (or add) them in @@ -358,7 +414,7 @@ been explained here), please let us know to correct it. where. Note that it is always good to have an option to download the necessary datasets in case the user doesn't have them. But in case your pipeline doesn't need any downloads, you can also remove the - sections of `configure' that are for `flock' and the downloader. + sections of `configure` that are for `flock` and the downloader. - **`README`**: Go through this top-level instruction file and make it fit to your pipeline: update the text and etc. Don't forget that your @@ -398,11 +454,28 @@ been explained here), please let us know to correct it. necessary for your research to the pipeline based on the example above. - - **Delete `README.md`**: This `README.md` is designed for this template, - not your reproduction pipeline. So to avoid later confusion, delete it - from your own repository. You may want to keep a copy outside for the - notes and discussions below until you are sufficiently familiar with - it and don't need it any more. + - **Paper title and authors**: The final paper's title, authors and other + information are defined in the last two sections of the + `tex/preamble-style.tex` file (section that are written in + ONLY-CAPITAL characters). Correct these for your project or use any + other LaTeX title and author management package that you prefer + instead. As you add more packages to the preambles, it is recommended + to follow this convention of having five empty lines between each group + of package importing and configuration along with comments for each + package. This will greatly help you in readability later. + + - **Delete dummy parts**: The template pipeline contains some parts that + are only for the initial/test run, not for any real analysis. The + respective files to remove and parts to fix are discussed here. + + - `paper.tex`: Delete the main body of text that is marked within + comments. + + - `Makefile`: Delete the two occurrences of `delete-me` in the + `foreach` loops. + + - Delete the following files: `README.md`, all `delete-me*` files (in + `reproduce/config/pipeline`, `reproduce/src/make`, and `tex`). - **Initiate a new Git repo**: You probably don't want to mix the history of this template reproduction pipeline with your own reproduction @@ -423,10 +496,17 @@ been explained here), please let us know to correct it. $ rm -rf .git # Completely remove this history. $ git init # Initiate a new history. $ git add --all # Stage everything that is here. - $ git commit # Make your first commit (mention the first output). + $ git commit # Your first commit (mention the first output). $ git tag -a v0 # Tag this as the zero-th version of your pipeline. ``` + - **Notice on reproducibility**: Add a notice somewhere prominent in the + first page within your paper, informing the reader that your research + is fully reproducible. For example in the end of the abstract, or + under the keywords with a title like "reproducible paper". This will + encourage them to publish their own works in this manner also and also + will help spread the word. + - **Start your exciting research**: You are now ready to add flesh and blood to this raw skeleton by further modifying and adding your exciting research steps. You can use the "published works" section in @@ -443,6 +523,11 @@ been explained here), please let us know to correct it. + + + + + Tips on expanding this template (designing your pipeline) ========================================================= @@ -637,6 +722,11 @@ us. In this way, we can add it here for the benefit of others. + + + + + Appendix: Necessity of exact reproduction in scientific research ================================================================ @@ -14,7 +14,7 @@ %% report, while keeping modularity in the preambles. \input{tex/pipeline.tex} \input{tex/preamble-style.tex} -%\input{tex/preamble-biblatex.tex} +\input{tex/preamble-biblatex.tex} \input{tex/preamble-pgfplots.tex} \input{tex/preamble-necessary.tex} @@ -32,6 +32,88 @@ \maketitle -Data were taken from \url{\websurvey}. + +%% Begin the multi-column environment. A `*' means that all extra empty +%% space is added in the last column. +\begin{multicols}{2} + + + +%% -------- Delete this --------- +\section{Congratulations!} +Congratulations on running the reproduction pipeline! You can now follow +the checklist in the \texttt{README.md} file to customize this pipeline to +your exciting research project. + +Just don't forget to \emph{never} use any numbers or fixed strings (for +example database urls like \url{\websurvey}) directly within your \LaTeX{} +source. Read them directly from your configuration files or outputs of the +programs as part of the reproduction pipeline and import them into \LaTeX{} +as macros through the \texttt{tex/pipeline.tex} file. See the several +examples within the pipeline for a demonstration. For some recent +real-world examples, the reproduction pipelines 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 +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. + +Just as a demonstration of creating plots within \LaTeX{} (using the +PGFPlots package), in Figure \ref{deleteme} we show a plot of +\deletemenum{} random points that were generated by this pipeline using the +text manipulation program {\small AWK} (which is not the best random number +generator, but just used here to generate some values). The minimum value +in this distribution is $\deletememin$ and $\deletememax$ is the maximum. + +The {\small PDF} file of Figure \ref{deleteme} is available in the +directory \texttt{\bdir/tex/build/tikz} and can be used in other contexts +(for example slides). If you want to directly use the PDF file in the +figure without having to let TiKZ decide if it should be remade or not, you +can also comment the \texttt{makepdf} macro at the top of this \LaTeX{} +source file. + +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 +reproduction pipeline. High-level language libraries like Matplotlib do +exist to also generate plots. However, bare in mind that they require many +dependencies (Python, Numpy and etc). Installing these dependencies from +source (after several years when the binaries are no longer available in +common repositories), is not easy and will harm the reproducibility of your +paper. + +\begin{Figure} + \includetikz{delete-me} + + \captionof{figure}{\label{deleteme} A random set of values plotted as a + demonstration of how to generate plots within LaTeX.} +\end{Figure} + +Furthermore, since PGFPlots is built by \LaTeX{} it respects all the +properties of your text (for example line width and fonts and etc), so 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}}. + + +\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 +reproduction pipeline, so until then, we would be grateful if you could +cite the first paper that used the first version of this pipeline: +\citet{ai15}. + +After publication, don't forget to upload all the necessary data, software +source code and the reproduction pipeline to a long-lasting host like +Zenodo (\url{https://zenodo.org/}). + +%% ------------------------------ + + + +\printbibliography +\end{multicols} \end{document} diff --git a/reproduce/config/pipeline/delete-me-num.mk b/reproduce/config/pipeline/delete-me-num.mk new file mode 100644 index 0000000..17f608c --- /dev/null +++ b/reproduce/config/pipeline/delete-me-num.mk @@ -0,0 +1,2 @@ +# Number of samples to create +delete-me-num = 50 diff --git a/reproduce/src/make/delete-me.mk b/reproduce/src/make/delete-me.mk new file mode 100644 index 0000000..a93c2d0 --- /dev/null +++ b/reproduce/src/make/delete-me.mk @@ -0,0 +1,73 @@ +# Dummy Makefile to create a random dataset for plotting. +# +# Original author: +# Mohammad Akhlaghi <mohammad@akhlaghi.org> +# Contributing author(s): +# Copyright (C) 2018, Your Name. +# +# This Makefile is free software: you can redistribute it and/or modify it +# under the terms of the GNU General Public License as published by the +# Free Software Foundation, either version 3 of the License, or (at your +# option) any later version. +# +# This Makefile is distributed in the hope that it will be useful, but +# WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General +# Public License for more details. +# +# A copy of the GNU General Public License is available at +# <http://www.gnu.org/licenses/>. + + + + + +# Dummy dataset +# ------------- +# +# We will use AWK's random number generator to generate a random dataset to +# be imported by PGFPlots for a plot in the paper. +dmdir = $(texdir)/delete-me +dm = $(dmdir)/data.txt +$(dmdir): | $(texdir); mkdir $@ +$(dm): $(pconfdir)/delete-me-num.mk | $(dmdir) + + # When the plotted values are re-made, it is necessary to also + # delete the TiKZ externalized files so the plot is also re-made. + rm -f $(tikzdir)/delete-me.pdf + + # Generate the table of random values. + awk 'BEGIN { for (i = 1; i <= $(delete-me-num); i++) \ + print i, rand(); }' > $@ + + + + + +# TeX macros +# ---------- +# +# This is how we write the necessary parameters in the final PDF. +# +# NOTE: In LaTeX you cannot use any non-alphabetic character in a variable +# name. +$(mtexdir)/delete-me.tex: $(dm) + + # Write the number of random values used. + echo "\newcommand{\deletemenum}{$(delete-me-num)}" > $@ + + # Note that since Make variables start with a `$(', if you want to + # use `$' within the shell (not Make), you have to quote any + # occurance of `$' with another `$'. That is why there are `$$' in + # the AWK command below. + # + # Here, we are first using AWK to find the minimum and maximum + # values, then using it again to read each separately to use in the + # macro definition. + mm=$$(awk 'BEGIN{min=99999; max=-min} \ + {if($$2>max) max=$$2; if($$2<min) min=$$2;} \ + END{print min, max}' $(dm)); \ + v=$$(echo "$$mm" | awk '{printf "%.3f", $$1}'); \ + echo "\newcommand{\deletememin}{$$v}" >> $@; \ + v=$$(echo "$$mm" | awk '{printf "%.3f", $$2}'); \ + echo "\newcommand{\deletememax}{$$v}" >> $@ diff --git a/reproduce/src/make/initialize.mk b/reproduce/src/make/initialize.mk index 70d77ed..4f134a9 100644 --- a/reproduce/src/make/initialize.mk +++ b/reproduce/src/make/initialize.mk @@ -37,6 +37,8 @@ texdir = $(BDIR)/tex srcdir = reproduce/src lockdir = $(BDIR)/locks +texbdir = $(texdir)/build +tikzdir = $(texbdir)/tikz mtexdir = $(texdir)/macros gconfdir = reproduce/config/gnuastro pconfdir = reproduce/config/pipeline @@ -100,10 +102,10 @@ $(pconfdir)/LOCAL.mk: # option: they add too many extra checks that make it hard to find what you # are looking for in this pipeline. .SUFFIXES: -$(mtexdir): | $(texdir); mkdir $@ +$(tikzdir): | $(texbdir); mkdir $@ $(BDIR): | $(pconfdir)/LOCAL.mk; mkdir $@ $(texdir) $(lockdir): | $(BDIR); mkdir $@ - +$(mtexdir) $(texbdir): | $(texdir); mkdir $@ diff --git a/reproduce/src/make/paper.mk b/reproduce/src/make/paper.mk index db20279..f3db1de 100644 --- a/reproduce/src/make/paper.mk +++ b/reproduce/src/make/paper.mk @@ -22,16 +22,39 @@ +# The bibliography +# ---------------- +# +# We need to run the `biber' program on the output of LaTeX to generate the +# necessary bibliography before making the final paper. +# +# NOTE: `tex/pipeline.tex' is an order-only-prerequisite for +# `paper.bbl'. This is because we need to run LaTeX in both the `paper.bbl' +# recipe and the `paper.pdf' recipe. But if `tex/references.tex' hasn't +# been modified, we don't want to re-build the bibliography, only the final +# PDF. +$(texbdir)/paper.bbl: tex/references.tex \ + | $(tikzdir) $(texbdir) tex/pipeline.tex + + # We'll run LaTeX first to generate the `.bcf' file (necessary for + # `biber') and then run `biber' to generate the `.bbl' file. + p=$$(pwd); \ + export TEXINPUTS=$$p:$$TEXINPUTS; \ + cd $(texbdir); \ + pdflatex -shell-escape -halt-on-error $$p/paper.tex; \ + biber paper + + + + + # The final paper # --------------- # # The commands to build the final report. We want the pipeline version to # be checked everytime the final PDF is to be built. -texbdir=$(texdir)/build -tikzdir=$(texbdir)/tikz -$(texbdir): | $(texdir); mkdir $@ -$(tikzdir): | $(texbdir); mkdir $@ -paper.pdf: tex/pipeline.tex paper.tex | $(tikzdir) $(texbdir) +paper.pdf: tex/pipeline.tex paper.tex $(texbdir)/paper.bbl \ + | $(tikzdir) $(texbdir) # Make the report. p=$$(pwd); \ diff --git a/tex/delete-me.tex b/tex/delete-me.tex new file mode 100644 index 0000000..495333a --- /dev/null +++ b/tex/delete-me.tex @@ -0,0 +1,17 @@ +%% PGFPlots code to plot a random set of numbers as demo + +\begin{tikzpicture} + + %% Settings of the plotted axis + \begin{axis}[ + width=\linewidth, + xlabel=Counter, + ylabel=Random value, + ] + + %% A particular plot. + \addplot+[scatter, only marks] + table {\bdir/tex/delete-me/data.txt}; + + \end{axis} +\end{tikzpicture} diff --git a/tex/preamble-biblatex.tex b/tex/preamble-biblatex.tex index 757f007..869d3d5 100644 --- a/tex/preamble-biblatex.tex +++ b/tex/preamble-biblatex.tex @@ -40,7 +40,7 @@ backend=biber,natbib]{biblatex} \DeclareFieldFormat[article]{pages}{#1} \DeclareFieldFormat{pages}{\mkfirstpage[{\mkpageprefix[bookpagination]}]{#1}} -\addbibresource{./tex/ref.tex} +\addbibresource{tex/references.tex} \renewbibmacro{in:}{} \renewcommand*{\bibfont}{\footnotesize} \DefineBibliographyStrings{english}{references = {References}} diff --git a/tex/preamble-pgfplots.tex b/tex/preamble-pgfplots.tex index c2a7f14..78937a7 100644 --- a/tex/preamble-pgfplots.tex +++ b/tex/preamble-pgfplots.tex @@ -37,8 +37,12 @@ %% figures. These numbers can be hard to manage and they will also depend %% on order in the final PDF, so it will be very buggy to manage them. \newcommand{\includetikz}[1]{% + \ifdefined\makepdf% \tikzsetnextfilename{#1}% \input{tex/#1.tex}% + \else + \includegraphics[width=\linewidth]{\bdir/tex/build/tikz/#1.pdf} + \fi } diff --git a/tex/preamble-style.tex b/tex/preamble-style.tex index d794ac1..228cd10 100644 --- a/tex/preamble-style.tex +++ b/tex/preamble-style.tex @@ -128,7 +128,7 @@ % Title, author, pipeline info and date as they appear on the output PDF. -\title{THE TITLE OF THIS PROJECT} +\title{THE TITLE OF YOUR PROJECT} \author{YOUR NAME, COLLEAGE1 NAME, ETC} \date{\small Reproduction pipeline \pipelineversion{} and Gnuastro \gnuastroversion\\on \today, \currenttime} diff --git a/tex/references.tex b/tex/references.tex new file mode 100644 index 0000000..b3998a2 --- /dev/null +++ b/tex/references.tex @@ -0,0 +1,45 @@ +@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{ai15, + author = {{Akhlaghi}, M. and {Ichikawa}, T.}, + title = "{Noise-based Detection and Segmentation of Nebulous Objects}", + journal = {ApJS}, +archivePrefix = "arXiv", + eprint = {1505.01664}, + primaryClass = "astro-ph.IM", + keywords = {galaxies: irregular, galaxies: photometry, galaxies: structure, methods: data analysis, techniques: image processing, techniques: photometric}, + year = 2015, + month = sep, + volume = 220, + eid = {1}, + pages = {1}, + doi = {10.1088/0067-0049/220/1/1}, + adsurl = {http://adsabs.harvard.edu/abs/2015ApJS..220....1A}, + adsnote = {Provided by the SAO/NASA Astrophysics Data System} +} |