diff options
| -rw-r--r-- | README | 107 | ||||
| -rw-r--r-- | README.md | 23 | ||||
| -rw-r--r-- | tex/preamble-style.tex | 16 |
3 files changed, 69 insertions, 77 deletions
@@ -1,7 +1,7 @@ Reproduction pipeline for XXXXX. -For a general introduction to reproducible science as done here, -please see the link below: +For a general introduction to reproducible science as done here, please see +the link below: http://akhlaghi.org/reproducible-science.html @@ -16,18 +16,18 @@ To reproduce the results, please take these steps in order: 2. Edit `reproduce/config/pipeline/DIRECTORIES.mk'. - This file keeps the important top-level directories for this - pipeline in your system. Open it with a text editor and give the - necessary locations. The comments in this file (lines starting with - a `#') should help in understanding the purpose of each directory. + This file keeps the important top-level directories for this pipeline in + your system. Open it with a text editor and give the necessary + locations. The comments in this file (lines starting with a `#') should + help in understanding the purpose of each directory. In short, if you don't have the input files on your system, this pipeline will download them in the specified directory. Also, the - intermediate/build directory may be relatively large (~1GB), so - please choose a build location with sufficient space. + intermediate/build directory may be relatively large (~1GB), so please + choose a build location with sufficient space. -3. Run the following command to reproduce everything on 8 threads. If - your CPU has a different number of threads, change the number. +3. Run the following command to reproduce everything on 8 threads. If your + CPU has a different number of threads, change the number. $ make -j8 @@ -36,8 +36,7 @@ To reproduce the results, please take these steps in order: Output ====== -The output of the pipeline is a PDF file, describing the published -paper. +The output of the pipeline is a PDF file, describing the published paper. @@ -45,18 +44,16 @@ Dependencies ============ To reproduce the results you need the following programs. Except for -Gnuastro, the version of the other programs will not make a -difference. +Gnuastro, the version of the other programs will not make a difference. Gnuastro Y.Y ------------ - Gnuastro is a large collection of programs for astronomical data - analysis on the command-line. This is an intermediate version of - Gnuastro (the tarball is not officially released on the Gnuastro - webpage). However, this pipeline will ONLY work with this version of - Gnuastro. For convenience, this tarball is available in the - following link: + Gnuastro is a large collection of programs for astronomical data analysis + on the command-line. This is an intermediate version of Gnuastro (the + tarball is not officially released on the Gnuastro webpage). However, + this pipeline will ONLY work with this version of Gnuastro. For + convenience, this tarball is available in the following link: https://zenodo.org/record/ZZZZZZ/files/gnuastro-Y.Y.tar.gz @@ -65,11 +62,10 @@ difference. https://www.gnu.org/software/gnuastro/manual/html_node/Quick-start.html - If you successfully downloaded the tarball from the link above, - please ignore the rest of this section on Gnuastro. If not, this - version of Gnuastro is always present in Gnuastro's version - controlled history and this reproduction pipeline contains the fix - to implement to it. + If you successfully downloaded the tarball from the link above, please + ignore the rest of this section on Gnuastro. If not, this version of + Gnuastro is always present in Gnuastro's version controlled history and + this reproduction pipeline contains the fix to implement to it. To build the above version of Gnuastro, please clone Gnuastro and checkout this version as shown in the following commands: @@ -77,47 +73,41 @@ difference. $ git clone http://git.sv.gnu.org/r/gnuastro.git $ git checkout Y.Y - Afterwords, you need to bootstrap Gnuastro as described in the - following link. + Afterwords, you need to bootstrap Gnuastro as described in the following + link. https://www.gnu.org/software/gnuastro/manual/html_node/Bootstrapping.html - You are now ready to configure, build and install Gnuastro as - described in the "Quick start" link above. + You are now ready to configure, build and install Gnuastro as described + in the "Quick start" link above. AWK --- - AWK is a program for working with text files. GNU AWK is the most - common implementation and it is commonly already installed on most - systems. + AWK is a program for working with text files. GNU AWK is the most common + implementation and it is commonly already installed on most systems. - GNU Make - -------- - - This reproduction pipeline uses some features that may not be - present in other implementations of Make. - flock ----- - This is a small program to manage file locks from the - command-line. It is available in most GNU/Linux distributions. + This is a small program to manage file locks from the command-line. It is + available in most GNU/Linux distributions. - If you can't find it in your package manager or on some Mac OS - systems, please put a copy of `reproduce/src/flock' file into your - search path (this script needs Perl, so have that installed is - well). To learn more about the search path and where to install this - file, please see the link below. Before running this pipeline you - should be able to run the `flock' command on your command-line. + If you can't find it in your package manager or on some Mac OS systems, + please put a copy of `reproduce/src/flock' file into your search path + (this script needs Perl, so have that installed is well). To learn more + about the search path and where to install this file, please see the link + below. Before running this pipeline you should be able to run the `flock' + command on your command-line. https://www.gnu.org/software/gnuastro/manual/html_node/Installation-directory.html + Wget or cURL ------------ @@ -125,29 +115,10 @@ difference. download the input files if you don't already have them. - Tar and Gzip - ------------ - - Tar is used for packaging multiple files into one and Gzip is used - for compression. They are both very common software in Unix-like - operating systems, so they are probably already available on your - system. - - - GNU Coreutils - ------------- - - Very basic command-line programs (for example `cp' or `mkdir'). They - may be implemented differently in non-GNU systems (for example Mac - OS). But have not actually been tested in Mac OS. Alternatively, - there are ways to install Coreutils on Mac OS (for example with - Homebrew), please do a search to find solutions. Please get in touch - with us if any errors occur due to such basic programs. - LaTeX ----- - LaTeX is used to build the final PDF of this pipeline. Some - important packages within LaTeX that this pipeline uses are: - `biblatex' and `pgfplots'. + LaTeX is used to build the final PDF of this pipeline. Some important + packages within LaTeX that this pipeline uses are: `biblatex' and + `pgfplots'. @@ -131,11 +131,13 @@ been explained here), please let us know to correct it. ```shell $ git clone https://gitlab.com/makhlaghi/reproduction-pipeline-template.git + $ mv reproduction-pipeline-template your-project-name + $ cd your-project-name ``` - **Copyright**, **name** and **date**: Go over the following files and correct the copyright, names and dates in their first few lines: - `README`, `Makefile` and `reproduce/src/make/*.mk`. When making new + `configure`, `Makefile` and `reproduce/src/make/*.mk`. When making new files, always remember to add a similar copyright statement at the top of the tile. @@ -177,6 +179,14 @@ been explained here), please let us know to correct it. $ git commit # Make your first commit (mention the first output) ``` + - **Title**, **Short description** of project: In this raw skeleton, the + title or short descripton 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 + are all in capital letters to make them easier to identify. + + - **`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 colleagues or anyone else, will first be drawn to read this file, so @@ -184,6 +194,7 @@ been explained here), please let us know to correct it. work. Therefore, also check and update `README` one last time when you are ready to publish your work (and its reproduction pipeline). + - **First input dataset**: The user manages the top-level directory of the input data through the variables set in `reproduce/config/pipeline/DIRECTORIES.mk.in` (the user actually edits @@ -291,6 +302,16 @@ way, we can add it here for others to also benefit. recipe or rule. As a general rule of thumb: first the comments, then the code. + - *File title*: In general, it is good practice to start all files with + a single line description of what that particular file does. If + further information about the totality of the file is necessary, add + it after a blank line. This will help a fast inspection where you + don't care about the details, but just want to remember/see what that + file is for. This information must ofcourse be commented (its for a + human), but this is kept separate from the general recommendation on + comments, because this is a comment for the whole file, not each step + within it. + - **Make programming**: Here are some experiences that we have come to learn over the years in using Make and are useful/handy in research diff --git a/tex/preamble-style.tex b/tex/preamble-style.tex index ae7ce92..d22354d 100644 --- a/tex/preamble-style.tex +++ b/tex/preamble-style.tex @@ -79,19 +79,19 @@ -% Basic Document information +% Basic Document information that goes into the PDF meta-data. \hypersetup { - pdfauthor={Mohammad Akhlaghi}, - pdfsubject={MUSE detected objects}, - pdftitle={Broadband HST photometry of MUSE detected objects}, - pdfkeywords={Mohammad, Akhlaghi, photometry, MUSE, HST} + pdfauthor={YOUR NAME}, + pdfsubject={A SHORT DESCRIPTION OF THE WORK}, + pdftitle={THE TITLE OF THIS PROJECT}, + pdfkeywords={SOME, KEYWORDS, FOR, THE, PDF} } -% Title -\title{A nice title for your research project} +% Title, author, pipeline info and date as they appear on the output PDF. +\title{THE TITLE OF THIS PROJECT} +\author{YOUR NAME, COLLEAGE1 NAME, ETC} \date{\small Reproduction pipeline \pipelineversion{} and Gnuastro \gnuastroversion\\on \today, \currenttime} -\author{Your name here.} |