diff options
| -rw-r--r-- | .dir-locals.el | 20 | ||||
| -rw-r--r-- | .gitignore | 14 | ||||
| l--------- | .gnuastro | 1 | ||||
| -rw-r--r-- | Makefile | 110 | ||||
| -rw-r--r-- | README | 153 | ||||
| -rw-r--r-- | README.md | 400 | ||||
| -rwxr-xr-x | configure | 88 | ||||
| -rw-r--r-- | paper.tex | 19 | ||||
| -rw-r--r-- | reproduce/config/gnuastro/gnuastro.conf | 36 | ||||
| -rw-r--r-- | reproduce/config/pipeline/DIRECTORIES.mk.in | 50 | ||||
| -rw-r--r-- | reproduce/config/pipeline/filters.mk | 25 | ||||
| -rw-r--r-- | reproduce/config/pipeline/pdf.mk | 14 | ||||
| -rw-r--r-- | reproduce/config/pipeline/web.mk | 6 | ||||
| -rw-r--r-- | reproduce/src/make/download.mk | 68 | ||||
| -rw-r--r-- | reproduce/src/make/initialize.mk | 114 | ||||
| -rw-r--r-- | reproduce/src/make/paper.mk | 34 | ||||
| -rw-r--r-- | tex/preamble-biblatex.tex | 115 | ||||
| -rw-r--r-- | tex/preamble-necessary.tex | 68 | ||||
| -rw-r--r-- | tex/preamble-pgfplots.tex | 33 | ||||
| -rw-r--r-- | tex/preamble-style.tex | 97 |
20 files changed, 1465 insertions, 0 deletions
diff --git a/.dir-locals.el b/.dir-locals.el new file mode 100644 index 0000000..af98cc8 --- /dev/null +++ b/.dir-locals.el @@ -0,0 +1,20 @@ +;; This files contains Emacs Directory Local Variables. +;; +;; Emacs is an extensible, customizable, free/libre text editor. It +;; allows specification of certain settings that will be applied to +;; all files in current directory and its subdirectories. This is +;; useful in order to automatically enforce certain coding conventions +;; for all contributors of Gnuastro, like the maximum length of lines +;; or the number of spaces to be used for indentation. +;; +;; For more information see (info "(emacs) Directory Variables") + +((nil + (indent-tabs-mode . nil) ;; No tabs as indentation + (fill-column . 75)) ;; 75-character wide lines + (c-mode + (c-basic-offset . 2) ;; 2 spaces of indentation + (c-file-style . "gnu")) ;; GNU style for braces + (makefile-mode + (indent-tabs-mode . t)) ;; Real TABs are important in makefiles + ) diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..cb41e68 --- /dev/null +++ b/.gitignore @@ -0,0 +1,14 @@ +*~ +*.txt +*.aux +*.log +*.pdf +*.out +*.auxlock +config/mmap_* + +reproduce/build +reproduce/BDIR/ +tex/pipeline.tex +reproduce/SURVEY/ +reproduce/config/pipeline/DIRECTORIES.mk
\ No newline at end of file diff --git a/.gnuastro b/.gnuastro new file mode 120000 index 0000000..5ccb4fd --- /dev/null +++ b/.gnuastro @@ -0,0 +1 @@ +reproduce/config/gnuastro
\ No newline at end of file diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..357a2e0 --- /dev/null +++ b/Makefile @@ -0,0 +1,110 @@ +# A ONE-LINE DESCRIPTION OF THE WHOLE PIPELINE +# +# Original author: +# Your name <your@email.address> +# Contributing author(s): +# Copyright (C) YYYY, 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/>. + + + + + +# Ultimate target of this pipeline +# -------------------------------- +# +# The final paper (in PDF format) is the main target of this whole +# reproduction pipeline. So as defined in the Make paradigm, we are +# defining it as the first target. +# +# Note that if you don't have LaTeX to build the PDF or generally are just +# interested in the processing, you can avoid the skip to create the final +# PDF, see `reproduce/config/pipeline/pdf.mk'. +all: paper.pdf + + + + + +# Include specific Makefiles +# -------------------------- +# +# To keep things clean, managable and readable, each set of operations is +# (and must be) classified (modularized) by context into separate +# Makefiles: the more the better. They are included in this top-level +# Makefile through the command below. +# +# To further help in readability, it is best to avoid including Makefiles +# within any other Makefile. So in short, it is best that the `foreach' +# loop below contains all the `reproduce/src/make/*.mk' files. +# +# IMPORTANT NOTE: order matters in the inclusion of the processing +# Makefiles. As the pipeline grows, some Makefiles will probably define +# variables/dependencies that others need. Therefore unlike the +# `reproduce/config/pipeline/*.mk' Makefiles which only define low-level +# variables (not dependent on other variables and contain no rules), the +# 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) + + + + + +# LaTeX macros for paper +# ---------------------- +# +# The final report's PDF (final target of this reproduction pipeline) takes +# variable strings from the pipeline. Those variables are defined as LaTeX +# macros in `tex/pipeline.tex'. This file is thus the interface between the +# pipeline scripts and the final PDF. +# +# Each of the pipeline steps will save their macros into their own `.tex' +# file in the `$(mtexdir)' directory. Those individual macros are the +# pre-requisite to `tex/pipeline.txt'. `tex/pipeline.tex' is thus a +# high-level output and is defined in this top-most Makefile (and not +# `reproduce/src/make/paper.mk'). This enables a clear demonstration of the +# top-level dependencies clearly. +# +# The symbolic link to the build directory (`bdirsym') is also placed here +# as a dependency if the pipeline is to be created. It is very important +# that it be an "order-only prerequisite" (after a `|', otherwise, it will +# try to be remade on every call and `ln' will complain and abort). +# +# 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-compile' variable +# in `reproduce/config/pipeline/pdf.mk'. +tex/pipeline.tex: $(foreach f, initialize download, $(mtexdir)/$(f).tex) \ + | $(bdirsym) + + # If no PDF is requested, then just exit here. +ifeq ($(pdf-compile),) + @echo; + @echo "Everything is OK until this point, but not building PDF." + @echo "To do so, give a value to the 'pdf-compile' variable." + @echo; + @exit 1 +endif + + # Read all the separate files and put them into the final TeX + # macros file. Since `bdirsym' maybe empty, we can't use the + # `filter-out' function generically. We'll have to check `bdirsym' + # first. +ifeq ($(bdirsym),) + cat $^ > $@ +else + cat $(filter-out $(bdirsym),$^) > $@ +endif @@ -0,0 +1,153 @@ +Reproduction pipeline for XXXXX. + +For a general introduction to reproducible science as done here, +please see the link below: + + http://akhlaghi.org/reproducible-science.html + + + +Running the pipeline +==================== + +To reproduce the results, please take these steps in order: + +1. Make sure you have the dependencies (below). + +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. + + 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. + +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 + + + +Output +====== + +The output of the pipeline is a PDF file, describing the published +paper. + + + +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 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: + + https://zenodo.org/record/ZZZZZZ/files/gnuastro-Y.Y.tar.gz + + To uncompress, build and install the Gnuastro tarball, follow the + instructions in the link below. + + 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. + + To build the above version of Gnuastro, please clone Gnuastro and + checkout this version as shown in the following commands: + + $ 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. + + 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. + + + + 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. + + + 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. + + 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 + ------------ + + These programs (`wget' or `curl' on the command-line) are used to + 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'. diff --git a/README.md b/README.md new file mode 100644 index 0000000..1a52571 --- /dev/null +++ b/README.md @@ -0,0 +1,400 @@ +Introduction +============ + +This description is for *creators* of the reproduction pipeline. See +`README` on instructions for running it. + +This project contains a **fully working template** for a high-level +research reproduction pipeline as defined in the link below. If this page +is inaccessible at the time of reading, please see the end of this file +which contains a portion of the introduction in this webpage. + + http://akhlaghi.org/reproducible-science.html + +This template is created with the aim of supporting reproducible research +by making it easy to start a project in this framework. It is very easy to +customize this template pipeline for any particular research/job and expand +it as it starts and evolves. It can be run with no modification (as +described in `README`) as a demonstration and customized by editing the +existing rules and adding new rules as well as adding new Makefiles as the +research/project grows. + +This file will continue with a discussion of why Make is the perfect +language/framework for a research reproduction pipeline and how to master +Make easily. Afterwards, a checklist of actions that are necessary to +customize this pipeline for your research is provided. The main body of +this text will finish with some tips and guidelines on how to manage or +extend it as your research grows. Please share your thoughts and +suggestions on this pipeline so we can implement them and make it even more +easier to use and more robust. + + +Why Make? +--------- + +When batch processing is necessary (no manual intervention, as in a +reproduction pipeline), shell scripts are usually the first solution that +comes to mind. However, the problem with scripts for a scientific +reproduction pipeline is the complexity and non-linearity. A script will +start from the top/start every time it is run. So if you have gone through +90% of a research project and want to run the remaining 10% that you have +newly added, you have to run the whole script from the start again and wait +until you see the effects of the last few steps (for the possible errors, +or better solutions and etc). It is possible to manually ignore/comment +parts of a script to only do a special part, but such checks/comments will +only add to the complexity of the script and they is prone to very serious +bugs in the end (when trying to reproduce from scratch). Such bugs are very +hard to notice when adding the checks or commenting-code in a script. + +The Make paradigm, on the other hand, starts from the end: the final +target. It builds a dependency tree internally, and finds where it should +actually start each time it is run. Therefore, in the scenario above, a +researcher that has just added the final 10% of steps of her research to +her Makefile, will only have run those extra steps. As commonly happens in +a research context, due to its paradigm Make, it is also trivial to change +the processing of any intermediate (already written) rule/step in the +middle of an already written pipeline: the next time Make is run, only +rules affected by the changes/additions will be re-run. + +This greatly speeds up the processing (enabling creative changes), while +keeping all the dependencies clearly documented (as part of the Make +language), and most importantly, enabling full reproducibility from scratch +with no changes in the pipeline code that was working during the +research. Since the dependencies are also clearly demarcated, Make can +identify independent steps and run them in parallel (further speeding up +the process). Make was designed for this purpose and it is how huge +projects like all Unix-like operating systems (including GNU/Linux or Mac +OS operating systems) and their core components are built. Therefore, Make +is a highly mature paradigm/system with robust and highly efficient +implementations in various operating systems perfectly suited for a complex +non-linear research project. + +Make is a small language with the aim of defining "rules" containing +"targets", "prerequisites" and "recipes". It comes with some cool features +like functions or automatic-variables to greatly facilitate the management +of any of those constructs. For a more detailed (yet still general) +introduction see Wikipedia: + + https://en.wikipedia.org/wiki/Make_(software) + +Many implementations of Make exist and all should be usable with this +pipeline. This pipeline has been created and tested mainly with GNU Make +which is the most common implementation. But if you see parts specific to +GNU Make, please inform us to correct it. + + +How can I learn Make? +--------------------- + +The best place to learn Make from scratch is the GNU Make manual. It is an +excellent and non-technical (in its first chapters) book to help get +started. It is freely available and always up to date with the current +release. It also clearly explains which features are specific to GNU Make +and which are general in all implementations. So the first few chapters +regarding the generalities are useful for all implementations. + +The first link below has links to the GNU Make manual in various formats +and in the second, you can get it in PDF (which may be easier to read in +the first time). + + https://www.gnu.org/software/make/manual/ + + https://www.gnu.org/software/make/manual/make.pdf + +If you use GNU Make, you also have the whole GNU Make manual on the +command-line with the following command (you can come out of the "info" +environment by pressing `q`, if you don't know "Info", we strongly +recommend running "$ info info" to learn it easily, it greatly simplifies +your access to many manuals that are installed on your system). + +```shell + $ info make +``` + +If you use the Emacs text editor, you will find the Info version of the +Make manual there also. + + + + +Checklist to customize the pipeline +=================================== + +Take the following steps to fully customize this pipeline for your research +project. After finishing the list, be sure to run `./configure` and `make` +to see if everything works correctly before expanding it. If you notice +anything missing or any in-correct part (probably a change that has not +been explained here), please let us know to correct it. + + - **Get this repository** (if you don't already have it): Arguably the + easiest way to start is to clone this repository as shown below: + + ```shell + $ git clone https://gitlab.com/makhlaghi/reproduction-pipeline-template.git + ``` + + - **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 + files, always remember to add a similar copyright statement at the top + of the tile. + + - **Gnuastro**: GNU Astronomy Utilities (Gnuastro) is currently a + dependency of the pipeline and without it, the pipeline will complain + and abort. The main reason for this is to demonstrate how critically + important it is to version your software. If you don't want to install + Gnuastro please follow the instructions in the list below. If you do + have Gnuastro (or have installed it to check this pipeline), then + after an initial check, try un-commenting the `onlyversion` line and + running the pipeline to see the respective error. Such features in a + software makes it easy to design a robust pipeline like this. If you + have tried it and don't need Gnuastro in your pipeline, also follow + this list: + + - Delete the description about Gnuastro in `README`. + - Delete everything about Gnuastro in `reproduce/src/make/initialize.mk` + - Delete `and Gnuastro \gnuastrover` from `tex/preamble-style` + + - **Initiate a new Git repo**: You don't want to mix the history of this + template reproduction pipeline with your own reproduction + pipeline. You have already made some small changes in the previous + step, so let's re-initiate history before continuing. But before doing + that, keep the output of `git describe` in a place and write it in + your first commit message to document what point in this pipeline's + history you started from. Since the pipeline is highly integrated with + your particular research, it may not be easy to merge the changes + later. Having the commit in this history that you started from, will + allow you to check and manually apply any changes that don't interfere + with your implemented pipeline. After this step, you can commit your + changes into your newly initiated history as you like. + + ```shell + $ git describe # The point in this history you started from. + $ git clean -fxd # Remove any possibly created extra files. + $ 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) + ``` + + - **`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 + make it as easy as possible for them to understand your + 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 + a `DIRECTORIES.mk` file that is copied from the `.mk.in` file, but the + `.mk` file is not under version control). So open this file and + replace `SURVEY` with the name of your input survey or dataset (all in + capital letters), for example if you are working on data from the XDF + survey, replace `SURVEY` with `XDF`. But don't change the value, just + the name. Afterwards, change any occurrence of `SURVEY` in the whole + pipeline with the new name. You can find the occurrences with a simple + command like the ones shown below. We follow the Make convention here + that all `ONLY-CAPITAL` variables are those directly set by the user + and all `small-caps` variables are set by the pipeline designer. All + variables that also depend on this survey have a `survey` in their + name. Hence, also correct all these occurrences to your new name in + small-caps. Of course, ignore those occurrences that are irrelevant, + like those in this file. Note that in the raw version of this template + no target depends on these files, so they are ignored. Afterwards, set + the webpage and correct the filenames in + `reproduce/src/make/download.mk' if necessary. + + ```shell + $ grep -r SURVEY ./ + $ grep -r survey ./ + ``` + + - **Other input datasets**: Add any other input datasets that may be + necessary for your research to the pipeline based on the example + above. + + +Tips on using the pipeline +========================== + +The following is a list of points, tips, or recommendations that have been +learned after some experience with this pipeline. Please don't hesitate to +share any experience you gain after using this pipeline with us. In this +way, we can add it here for others to also benefit. + + - **Modularity**: Modularity is the key to easy and clean growth of a + project. So it is always best to break up a job into as many + sub-components as reasonable. Here are some tips to stay modular. + + - *Short recipes*: if you see the recipe of a rule becoming more than a + few lines, it probably a good sign that you should break up the job. + + - *Context-based (many) Makefiles*: This pipeline is designed to allow + the easy inclusion of many Makefiles (in `reproduce/src/make/*.mk`) + for maximal modularity. So keep the rules for closely related parts + of the processing in separate Makefiles. + + - *Clear file names*: Be very clear and descriptive with the naming of + the files and the variables because a few months after the processing + it will be very hard to remember what each one does. Also this helps + others (your collaborators or other people reading the pipeline after + it is published) to more easily understand your work and find their + way around. + + - *Standard naming*: As the project grows, following a good standard in + naming the files is very useful. Try best to use multiple word + filenames for anything that is non-trivial (separating the words with + a `-`). For example if you have a Makefile for creating a catalog and + another two for processing it under models A and B, you can name them + like this: `catalog-create.mk`, `catalog-modela.mk` and + `catalog-modelb.mk`. In this way, when listing the contents of + `reproduce/src/make` to see all the Makefiles, those related to the + catalog will all be close to each other and thus easily found. This + also helps in auto-completions by the shell or text editors like + Emacs. + + - *Source directories*: If you need to add scripts (shell, Python, AWK + or any other language), keep them in a separate directory under + `reproduce/src`, with the appropriate name. + + - *Configuration files*: If your research uses special programs as part + of the processing, put all their configuration files in a devoted + directory (with the program's name) within + `reproduce/config`. Similar to the `reproduce/config/gnuastro` + directory (which is put in the template as a demo in case you use GNU + Astronomy Utilities). It is much cleaner and readable (thus less + buggy) to avoid mixing the configuration files, even if there is no + technical necessity. + + + - **Contents**: It is good practice to follow the following + recommendations on the contents of your files, whether they are source + code for a program, Makefiles, scripts or configuration files + (copyrights aren't necessary for the latter). + + - *Copyright*: Always start a file containing programming constructs + with a copyright statement like the ones that this template starts + with (for example in the top level `Makefile`). + + - *Comments*: Comments are vital for readability (by yourself in two + months or others). Describe everything you can about why you are + doing something, how you are doing it, and what you expect the result + to be. Write the comments as if it was what you would say to describe + the variable, recipe or rule to a friend sitting beside you. When + writing the pipeline it is very tempting to just steam ahead, but be + patient and write comments before the rules or recipes. This will + also allow you to think more about what you should be doing. Also, in + several months when you come back to the code, you will appreciate + the effort of writing them. Just don't forget to also read and update + the comment first if you later want to make changes to the variable, + recipe or rule. As a general rule of thumb: first the comments, then + the code. + + + - **Make programming**: Here are some experiences that we have come to + learn over the years in using Make and are useful/handy in research + contexts. + + - *Automatic variables*: These are wonderful and very useful Make + constructs that greatly shrink the text, while help in read-ability, + robustness (less bugs in typos for example) and generalization. For + example even when a rule only has one target or one prerequisite, + always use `$@` instead of the target's name, `$<` instead of the + first prerequisite, `$^` instead of the full list of prerequisites + and etc. You can see the full list of automatic variables + [here](https://www.gnu.org/software/make/manual/html_node/Automatic-Variables.html). If + you use GNU Make, you can also see this page on your command-line: + + ```shell + $ info make "automatic variables + ``` + + - *Large files*: If you are dealing with very large files (thus having + multiple copies of them for intermediate steps is not possible), one + solution is the following strategy. Set a small plain text file as + the actual target and delete the large file when it is no longer + needed by the pipeline (in the last rule that needs it). Below is a + simple demonstration of doing this, where we use Gnuastro's + Arithmetic program to add all pixels of the input image with 2 and + create `large1.fits`. We then subtract 2 from `large1.fits` to create + `large2.fits` and delete `large1.fits` in the same rule (when its no + longer needed). We can later do the same with `large2.fits` when it + is no longer needed and so on. + ``` + large1.fits.txt: input.fits + astarithmetic $< 2 + --output=$(subst .txt,,$@) + echo "done" > $@ + large2.fits.txt: large1.fits.txt + astarithmetic $(subst .txt,,$<) 2 - --output=$(subst .txt,,$@) + rm $(subst .txt,,$<) + echo "done" > $@ + ``` + A more advanced Make programmer will use [Make's call + function](https://www.gnu.org/software/make/manual/html_node/Call-Function.html) + to define a wrapper in `reproduce/src/make/initialize.mk`. This + wrapper will replace `$(subst .txt,,XXXXX)`. Therefore, it will be + possible to greatly simplify this repetitive statement and make the + code even more readable throughout the whole pipeline. + + + - **Dependencies**: It is critically important to exactly document, keep + and check the versions of the programs you are using in the pipeline. + + - *Check versions*: In `reproduce/src/make/initialize.mk`, check the + versions of the programs you are using. + + - *Keep the source tarball of dependencies*: keep a tarball of the + necessary version of all your dependencies (and also a copy of the + higher-level libraries they depend on). Software evolves very fast + and only in a few years, a feature might be changed or removed from + the mainstream version or the software server might go down. To be + safe, keep a copy of the tarballs (they are hardly ever over a few + megabytes, very insignificant compared to the data). If you intend to + release the pipeline in a place like Zenodo, then you can create your + submission early (before public release) and upload/keep all the + necessary tarballs (and data) there. + + - *Keep your input data*: The input data is also critical to the + pipeline, so like the above for software, make sure you have a backup + of them + + + + + + + +Appendix: Introduction to this concept from link above +====================================================== + +In case [the link above](http://akhlaghi.org/reproducible-science.html) is +not accessible at the time of reading, here is a copy of the introduction +of that link, describing the necessity for a reproduction pipeline like +this (copied on February 7th, 2018): + +The most important element of a "scientific" statement/result is the fact +that others should be able to falsify it. The Tsunami of data that has +engulfed astronomers in the last two decades, combined with faster +processors and faster internet connections has made it much more easier to +obtain a result. However, these factors have also increased the complexity +of a scientific analysis, such that it is no longer possible to describe +all the steps of an analysis in the published paper. Citing this +difficulty, many authors suffice to describing the generalities of their +analysis in their papers. + +However, It is impossible to falsify (or even study) a result if you can't +exactly reproduce it. The complexity of modern science makes it vitally +important to exactly reproduce the final result. Because even a small +deviation can be due to many different parts of an analysis. Nature is +already a black box which we are trying so hard to comprehend. Not letting +other scientists see the exact steps taken to reach a result, or not +allowing them to modify it (do experiments on it) is a self-imposed black +box, which only exacerbates our ignorance. + +Other scientists should be able to reproduce, check and experiment on the +results of anything that is to carry the "scientific" label. Any result +that is not reproducible (due to incomplete information by the author) is +not scientific: the readers have to have faith in the subjective experience +of the authors in the very important choice of configuration values and +order of operations: this is contrary to the scientific spirit.
\ No newline at end of file diff --git a/configure b/configure new file mode 100755 index 0000000..be18c25 --- /dev/null +++ b/configure @@ -0,0 +1,88 @@ +#! /bin/sh +# +# Necessary preparations/configurations for the reproduction pipeline. +# +# Original author: +# Your name <your@email.address> +# Contributing author(s): +# Copyright (C) YYYY, Your Name. +# +# This script 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 script 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/>. + + + + + +# Location of the settings directory: +pdir=reproduce/config/pipeline + + +# Message to print for editing +function msg { + echo; echo "Top-level reproduction directories are set."; + echo "Please run the following command to start the pipeline:" + echo "(Replace '8' with the number of CPU threads available)" + echo; echo " make -j8" + echo; +} + + +# If `DIRECTORIES.mk' is already created, then ignore this step. +if [ -f $pdir/DIRECTORIES.mk ]; then + echo + echo "$pdir/DIRECTORIES.mk already exists." + echo "To change/correct the top-level directories, please remove/edit it manually." + echo +else + + # Copy the base file to the desired output file. + if cp $pdir/DIRECTORIES.mk.in $pdir/DIRECTORIES.mk; then + + # Tell the user to edit the directories. + while [ "$userread" != "y" -a "$userread" != "n" ] + do + echo "Top-level directories..." + echo + echo "These directories define the input(s) location and the" + echo "directory to host the intermediate/processing files." + echo + echo "To help in your ability to read and manage this pipeline," + echo "it is recommended (but not mandatory) to change them to" + echo "a directory outside this reproduction pipeline." + echo + echo "More descriptions are provided within the file that is" + echo "opened if you choose to edit the directories." + echo + read -p"Edit the default top-level directories (y/n)? " userread + done + + # Only continue if the user wants to edit the top level + # directories + if [ $userread = "y" ]; then + + # Open a text editor to set the given directories + if emacs $pdir/DIRECTORIES.mk; then msg + elif gedit $pdir/DIRECTORIES.mk; then msg + elif vi $pdir/DIRECTORIES.mk; then msg + else + echo + echo "No common text editor found on your system." + echo "Please set the values in '$pdir/DIRECTORIES.mk' manually." + echo + fi + fi + else + echo; echo "Couldn't create $pdir/DIRECTORIES.mk" + fi +fi diff --git a/paper.tex b/paper.tex new file mode 100644 index 0000000..8cf9cef --- /dev/null +++ b/paper.tex @@ -0,0 +1,19 @@ +\documentclass{article} + +%% Necessary LaTeX preambles to include for relevant functionality. We +%% don't want to start this file as fast as possible with the actual body +%% of the report, while keeping modularity in the preambles. +\input{tex/pipeline.tex} +\input{tex/preamble-style.tex} +%\input{tex/preamble-biblatex.tex} +%\input{tex/preamble-pgfplots.tex} +\input{tex/preamble-necessary.tex} + +%% Start writing. +\begin{document} + +\maketitle + +Data were taken from \url{\websurvey}. + +\end{document} diff --git a/reproduce/config/gnuastro/gnuastro.conf b/reproduce/config/gnuastro/gnuastro.conf new file mode 100644 index 0000000..49f9906 --- /dev/null +++ b/reproduce/config/gnuastro/gnuastro.conf @@ -0,0 +1,36 @@ +# Default values for the common options to all the programs in GNU +# Astronomy Utitlies. +# +# IMPORTANT NOTE FOR THE REPRODUCTION PIPELINE: The `lastconfig' +# option is very important here, because we don't want any of +# Gnuastro's programs to go into an un-controlled environment (user or +# system wide configuration files). Uncomment the `onlyversion' option +# when the paper/pipeline is ready to be published and set the value +# of X.X accordingly. +# +# The rest of this configuration file in this template reproduction +# pipeline is taken from the default Gnuastro configuration from its +# source (`bin/gnuastro.conf'). + +# Reproduction pipeline + lastconfig 1 +# onlyversion X.X + +# Input: + hdu 1 + ignorecase 1 + searchin name + +# Tessellation + tilesize 50,50 + numchannels 1,1 + remainderfrac 0.1 + workoverch 0 + interpnumngb 9 + interponlyblank 0 + +# Output: + tableformat fits-binary + +# Operating mode + minmapsize 1000000000
\ No newline at end of file diff --git a/reproduce/config/pipeline/DIRECTORIES.mk.in b/reproduce/config/pipeline/DIRECTORIES.mk.in new file mode 100644 index 0000000..9ebd67b --- /dev/null +++ b/reproduce/config/pipeline/DIRECTORIES.mk.in @@ -0,0 +1,50 @@ +# Top-level user specific directories. Note the points below: +# +# - The VALUES to these directories are initially JUST PLACE-HOLDERS! +# Please correct them based on your system. +# +# - The directories don't need to necessarily exist. If they do not exist, +# they will be created and the necessary data will be downloaded into +# them. Ofcourse provided that you have write permissions and an internet +# connection. +# +# - Do not use the tilde expansion `~' or variables for your home +# directory. Please use the full address, for example +# `/home/your-user-name'. +# +# - An ending forward-slash `/' is NOT necessary. In the pipeline, all +# these variables will be followed by a `/', so if you put a `/' at the +# end of the value here, you will see a `//' in the printed outputs +# during the processing. This has no technical problem, but can make +# reading the outputs harder and is thus not recommended. + + + + + +# Input data directories +# ---------------------- +# +# This is where the input data (with the same file-name standard as the +# online webpage) are stored. If this directory doesn't exist, or it +# doesn't contain the files (with the correct file-name formats), it will +# be created and the images will be downloaded. See +# `reproduce/config/pipeline/web.mk', for the URLs containing the expected +# inputs for each survey. +SURVEY = reproduce/SURVEY + + + + + +# Build directory +# --------------- +# +# This is where the intermediate outputs of each step are kept. +# +# Why a separate build directory? So the source and configuration files for +# this reproduction pipeline do not get crowded by all the +# intermediate/derivative files. Also to make synchronization and backups +# more easy: the contents of the build directory do not need to be backed +# up since they can be reproduced and they can be large. +BDIR = reproduce/BDIR diff --git a/reproduce/config/pipeline/filters.mk b/reproduce/config/pipeline/filters.mk new file mode 100644 index 0000000..6fa785d --- /dev/null +++ b/reproduce/config/pipeline/filters.mk @@ -0,0 +1,25 @@ +# `filters' are the possible different parts of the survey, for +# example filters in broad or narrow-band astronomical imaging +# datasets. Since a generic term for them (to apply other types of +# surveys/datasets) hasn't been considered yet, we'll stick with the +# `filters' name. But feel free to correct it (or propose a +# suggestion). +# +# If your dataset only has a single filter, or this concept is not +# defined for your type of input dataset, you can ignore this +# variable. +# +# The values can be any string to identify different parts of a survey +# separated by white space characters (for example `f125w f160w' or `J +# H' if you want to specify two filters). +# +# To be clean and also help in readability of the pipeline, it is good +# practice to define a separate `filter-XXXX' variable for each +# survey/dataset, even if they have overlapping filters. +# +# These `filters' are used in the initial downloading of the data and +# it is good practice (for avoiding bugs) to keep the same filter (and +# survey) names in the filenames of the intermediate/output files +# also. This will make sure that the raw input and intermediate/final +# output are exactly related. +filters-survey = a b c d e f g h i diff --git a/reproduce/config/pipeline/pdf.mk b/reproduce/config/pipeline/pdf.mk new file mode 100644 index 0000000..51ab933 --- /dev/null +++ b/reproduce/config/pipeline/pdf.mk @@ -0,0 +1,14 @@ +# Make the final PDF? +# ------------------- +# +# During the testing a pipeline, it is usually not necessary to build +# the PDF file (which makes a lot of output lines on the command-line +# and can make it hard to find the commands and possible errors (and +# their outputs). Also, in some cases, only the produced results may +# be of interest and not the final PDF, so LaTeX (and its necessary +# packages) may not be installed. +# +# If this variable is given any string, a PDF will be made with +# LaTeX. Otherwise, a notice will just printed that for now, no PDF +# will be created. +pdf-compile = yes diff --git a/reproduce/config/pipeline/web.mk b/reproduce/config/pipeline/web.mk new file mode 100644 index 0000000..f80b886 --- /dev/null +++ b/reproduce/config/pipeline/web.mk @@ -0,0 +1,6 @@ +# Web server(s) hosting the input data for this pipeline. +# +# This is the web page containing the files that must be located in the +# `SURVEY' directory of `reproduce/config/pipeline/DIRECTORIES.mk' on the +# local system. +web-survey = https://some.webpage.com/example/server diff --git a/reproduce/src/make/download.mk b/reproduce/src/make/download.mk new file mode 100644 index 0000000..244bd04 --- /dev/null +++ b/reproduce/src/make/download.mk @@ -0,0 +1,68 @@ +# Download all the necessary inputs if they are not already present. +# +# Since most systems only have one input/connection into the network, +# downloading is essentially a serial (not parallel) operation. so the +# recipes in this Makefile all use a single file lock to have one download +# script running at every instant. +# +# Original author: +# Your name <your@email.address> +# Contributing author(s): +# Copyright (C) YYYY, 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. See <http://www.gnu.org/licenses/>. + + + + + +# Identify the downloader tool +# ---------------------------- +# +# If cURL is already present, that will be used, otherwise, we'll use +# Wget. Since the options specifying the output filename are different +# between the two, we'll also specify the output option within the +# `downloader' variable. So it is important to first give the output +# filename after calling `downloader', then the web address. +downloader := $(shell if type curl > /dev/null; then downloader="curl -o"; \ + else downloader="wget -O"; \ + fi; echo "$$downloader"; ) + + + + + +# Download SURVEY data +# -------------------- +# +# Data from a survey (for example an imaging survey) usually have a special +# file-name format which should be set here in the `foreach' loop. Note +# that the `foreach' function needs the backslash (`\') at the end of the +# line when it is broken into multiple lines. +all-survey = $(foreach f, $(filters-survey), \ + $(SURVEY)/a-special-format-$(f).fits \ + $(SURVEY)/a-possibly-additional-$(f)-format.fits ) +$(SURVEY):; mkdir $@ +$(all-survey): $(SURVEY)/%: | $(SURVEY) $(lockdir) + flock $(lockdir)/download -c "$(downloader) $@ $(web-survey)/$*" + + + + + + +# Final TeX macro +# --------------- +# +# It is very important to mention the address where the data were +# downloaded in the final report. +$(mtexdir)/download.tex: $(pconfdir)/web.mk | $(mtexdir) + @echo "\\newcommand{\\websurvey}{$(web-survey)}" > $@ diff --git a/reproduce/src/make/initialize.mk b/reproduce/src/make/initialize.mk new file mode 100644 index 0000000..2da5e79 --- /dev/null +++ b/reproduce/src/make/initialize.mk @@ -0,0 +1,114 @@ +# Initialize the reproduction pipeline. +# +# Original author: +# Your name <your@email.address> +# Contributing author(s): +# Copyright (C) YYYY, 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/>. + + + + + +# High-level directory definitions +# -------------------------------- +# +# Basic directories that are used throughout the whole pipeline. +# +# Locks are used to make sure that an operation is done in series not in +# parallel (even if Make is run in parallel with the `-j' option). The most +# common case is downloads which are better done in series and not in +# parallel. Also, some programs may not be thread-safe, therefore it will +# be necessary to put a lock on them. This pipeline uses the `flock' +# program to achieve this. +texdir = $(BDIR)/tex +lockdir = $(BDIR)/locks +bdirsym = reproduce/build +mtexdir = $(texdir)/macros +pconfdir = reproduce/config/pipeline + + + + + +# Make the high-level level directories +# ------------------------------ +# +# These are just the top-level directories for all the separate steps. The +# directories (or possible sub-directories) for individual steps will be +# defined and added within their own Makefiles. +$(BDIR):; mkdir $@; +$(mtexdir): | $(texdir); mkdir $@ +$(texdir) $(lockdir): | $(BDIR); mkdir $@ + + + + + +# High-level Makefile management +# ------------------------------ +# +# About `.PHONY': these are targets that must be built even if a file with +# their name exists. Most don't correspond to a file, but those that do are +# included here ensure that the file is always built in every run: for +# example the pipeline versions may change within two separate runs, so we +# want it to be rebuilt every time. +.PHONY: all clean clean-mmap $(texdir)/versions.tex +clean-mmap:; rm -f reproduce/config/gnuastro/mmap* +clean: + rm -rf $(BDIR) $(bdirsym) *.pdf *.log *.out *.aux *.auxlock \ + reproduce/config/gnuastro/mmap* + + + + + +# Pipeline version +# ---------------- +# +# The pipeline's version is necessary for the analysis and must be +# calculated everytime the pipeline is run, so even though this file +# actually exists, it is also aded as a `.PHONY' target above. +$(mtexdir)/initialize.tex: | $(mtexdir) + + @v=$$(git describe --dirty --always); \ + echo "\newcommand{\pipelineversion}{$$v}" > $@ + + @v=$$(astnoisechisel --version | awk 'NR==1{print $$NF}'); \ + echo "\newcommand{\gnuastroversion}{$$v}" >> $@ + + echo "\newcommand{\bdir}{$(BDIR)}" >> $@ + + + + + +# Symbolic link to build directory +# -------------------------------- +# +# Besides $(BDIR), we are also making a symbolic link to it if $(bdirsym) +# is not empty. In case this symbolic link is not needed, simply remove its +# value from the definitions above. In that case, it will be read as a +# blank (non-existant). +# +# Note that $(BDIR) might not be an absolute path and this will complicate +# the symbolic link creation. To be generic, we'll first call `readlink' to +# make sure we have an absolute address, then we'll make a symbolic link to +# that. +ifneq ($(bdirsym),) +$(bdirsym): | $(BDIR) + absbdir=$$(readlink -f $(BDIR)); \ + ln -s $$absbdir $(bdirsym) +endif diff --git a/reproduce/src/make/paper.mk b/reproduce/src/make/paper.mk new file mode 100644 index 0000000..0725ec8 --- /dev/null +++ b/reproduce/src/make/paper.mk @@ -0,0 +1,34 @@ +# Build the final PDF paper/report. +# +# Original author: +# Your name <your@email.address> +# Contributing author(s): +# Copyright (C) YYYY, Your Name. +# +# This script 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 script 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/>. + + + + + +# 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. +paper.pdf: tex/pipeline.tex paper.tex + + # Make the report. + @pdflatex -shell-escape -halt-on-error paper.tex + @rm -f *.auxlock *.aux *.out *.log diff --git a/tex/preamble-biblatex.tex b/tex/preamble-biblatex.tex new file mode 100644 index 0000000..757f007 --- /dev/null +++ b/tex/preamble-biblatex.tex @@ -0,0 +1,115 @@ +%% Biblatex settings. +%% +%% Since the preamble settings necessary to make the bibliography with +%% Biblatex is a little long and unclean, and might be used in other places +%% separately later, it is easier to have it here as a separate file. +%% +%% USAGE: +%% +%% - `tex/ref.tex': the file containing Bibtex source of each +%% reference. The file suffix doesn't have to be `.bib', this naming +%% helps in clearly identifying the files and avoiding places that +%% complain about `.bib' files. + + + + + +%% To break up highlighted text (for example texttt when some it is on the +%% line break) and also to no underline emphasized words (like journal +%% titles in the references). +\usepackage[normalem]{ulem} + + + + + +% Basic BibLaTeX settings +\usepackage[ + doi=false, + url=false, + dashed=false, + eprint=false, + maxbibnames=4, + minbibnames=1, + hyperref=true, + maxcitenames=2, + mincitenames=1, + style=authoryear, + uniquelist=false, + backend=biber,natbib]{biblatex} +\DeclareFieldFormat[article]{pages}{#1} +\DeclareFieldFormat{pages}{\mkfirstpage[{\mkpageprefix[bookpagination]}]{#1}} +\addbibresource{./tex/ref.tex} +\renewbibmacro{in:}{} +\renewcommand*{\bibfont}{\footnotesize} +\DefineBibliographyStrings{english}{references = {References}} + +%% Include the adsurl field key into those that are recognized: +\DeclareSourcemap{ + \maps[datatype=bibtex]{ + \map{ + \step[fieldsource=adsurl,fieldtarget=iswc] + \step[fieldsource=gbkurl,fieldtarget=iswc] + } + } +} + +%% Set the color of the doi link to mymg (magenta) and the ads links +%% to mypurp (or purple): +\definecolor{mypurp}{cmyk}{0.75,1,0,0} +\newcommand{\doihref}[2]{\href{#1}{\color{magenta}{#2}}} +\newcommand{\adshref}[2]{\href{#1}{\color{mypurp}{#2}}} +\newcommand{\blackhref}[2]{\href{#1}{\color{black}{#2}}} + +%% Define a format for the printtext commands in +%% DeclareBibliographyDriver to make links for the doi, ads link and +%% arxiv link: +\DeclareFieldFormat{doilink}{ + \iffieldundef{doi}{#1}{\doihref{http://dx.doi.org/\thefield{doi}}{#1}}} +\DeclareFieldFormat{adslink}{ + \iffieldundef{iswc}{#1}{\adshref{\thefield{iswc}}{#1}}} +\DeclareFieldFormat{arxivlink}{ + \iffieldundef{eprint}{#1}{\href{http://arxiv.org/abs/\thefield{eprint}}{#1}}} + +\DeclareListFormat{doiforbook}{ + \iffieldundef{doi}{#1}{\doihref{http://dx.doi.org/\thefield{doi}}{#1}}} +\DeclareFieldFormat{googlebookslink}{ + \iffieldundef{iswc}{#1}{\adshref{\thefield{iswc}}{#1}}} + +%% Set the formatting to make the last three values into the +%% appropriate link. Note that the % signs are necessary. Without +%% them, the items will be indented. +\DeclareBibliographyDriver{article}{% + \usebibmacro{bibindex}% + \usebibmacro{begentry}% + \usebibmacro{author/translator+others}% + \newunit% + \ifdefined\makethesis\printtext{\usebibmacro{title}}\fi% + \newunit% + \printtext[doilink]{\usebibmacro{journal}}% + \addcomma% + \printtext[adslink]{\printfield{volume}}% + \addcomma% + \printtext[arxivlink]{\printfield{pages}}% + \addperiod% +} + +\DeclareBibliographyDriver{book}{% + \usebibmacro{bibindex}% + \usebibmacro{begentry}% + \usebibmacro{author/translator+others}% + \newunit% + \printtext{\usebibmacro{title}}% + \addperiod% + \addspace% + \printlist[doiforbook]{publisher}% + \addcomma% + \addspace% + \printfield[googlebookslink]{edition}% + \printtext{ ed.}% + \addperiod% +} + +%% In order to have et al. instead of et al.,: +\renewcommand*{\nameyeardelim}{\addspace} diff --git a/tex/preamble-necessary.tex b/tex/preamble-necessary.tex new file mode 100644 index 0000000..debcb4b --- /dev/null +++ b/tex/preamble-necessary.tex @@ -0,0 +1,68 @@ +%% Some (commonly) necessary LaTeX packages. +%% +%% These are a set of packages that are commonly necessary in most LaTeX +%% usages. However, if any are not needed in your work, you can remove them +%% from here. + + + + + +% Macros for to help in typing, remove them if you don't need them, but +% this can help as a demo on how you can simply writing of commonly used +% words that need special formatting (like software names). +\newcommand{\snsign}{{\small S}/{\small N}} +\newcommand{\originsoft}{\textsf{ORIGIN}} +\newcommand{\sextractor}{\textsf{SE\-xtractor}} +\newcommand{\noisechisel}{\textsf{Noise\-Chisel}} +\newcommand{\makecatalog}{\textsf{Make\-Catalog}} + + + + + +%% For highlighting updates. When this is set, text marked as \new +%% will be colored in dark green and text that is marked wtih \tonote +%% will be marked in dark red. +\ifdefined\highlightchanges +\newcommand{\new}[1]{\textcolor{green!60!black}{#1}} +\newcommand{\tonote}[1]{\textcolor{red!60!black}{[#1]}} +\else +\newcommand{\new}[1]{\textcolor{black}{#1}} +\newcommand{\tonote}[1]{{}} +\fi + + + + + +% Better than verbatim for displaying typed text. +\usepackage{alltt} + + + + + +% For arithmetic opertions within LaTeX +\usepackage[nomessages]{fp} + + + + + +%To add a code font to the text: +\usepackage{courier} + + + + + +%To add some enumerating styles +\usepackage{enumerate} + + + + + +%Including images if necessary +\usepackage{graphicx} diff --git a/tex/preamble-pgfplots.tex b/tex/preamble-pgfplots.tex new file mode 100644 index 0000000..13570e9 --- /dev/null +++ b/tex/preamble-pgfplots.tex @@ -0,0 +1,33 @@ +%% PGFPlots settings. +%% +%% PGFPlots is a package in (La)TeX for making plots internally. It fits +%% nicely with the purpose of a reproduction pipeline. But it isn't +%% mandatory. Therefore if needed, you can just uncomment the line that +%% includes this file in the top LaTeX source (`paper.tex'). + + + + + +% For a tikz environment: +\usepackage{tikz} +\usetikzlibrary{external} +\tikzexternalize + +\tikzsetexternalprefix{\bdir/tex/tikz/} + +%% Uncomment the following lines for EPS and PS images. Note that you +%% still have to use pdflatex and also add a `[dvips]' option to +%% graphicx. + +%\tikzset{external/system call={rm -f "\image".eps "\image".ps +%"\image".dvi; latex \tikzexternalcheckshellescape -halt-on-error +%-interaction=batchmode -jobname "\image" "\texsource"; +%dvips -o "\image".ps "\image".dvi; +%ps2eps "\image.ps"}} + +%For drawing plots: +\usepackage{pgfplots} +\pgfplotsset{compat=newest} +\usepgfplotslibrary{groupplots} +\pgfplotsset{axis line style={thick}, tick style={semithick}} diff --git a/tex/preamble-style.tex b/tex/preamble-style.tex new file mode 100644 index 0000000..ae7ce92 --- /dev/null +++ b/tex/preamble-style.tex @@ -0,0 +1,97 @@ +%% General paper's style settings. +%% +%% This preamble can be completely ignored when including this TeX file in +%% another style. This is done because this LaTeX build is meant to be an +%% initial/internal phase or part of a larger effort, so it has a basic +%% style defined here as a preamble. To ignore it, uncomment or delete the +%% respective line in `paper.tex'. + + + +%% Print size +\usepackage[a4paper, includeheadfoot, body={18.7cm, 24.5cm}]{geometry} + + + + +%% Set the distance between the columns if two columns: +\setlength{\columnsep}{0.75cm} + + + + + +% To allow figures to take up more space on the top of the page: +\renewcommand{\topfraction}{.99} +\renewcommand{\bottomfraction}{.7} +\renewcommand{\textfraction}{.05} +\renewcommand{\floatpagefraction}{.99} +\renewcommand{\dbltopfraction}{.99} +\renewcommand{\dblfloatpagefraction}{.99} +\setcounter{topnumber}{1} +\setcounter{bottomnumber}{0} +\setcounter{totalnumber}{2} +\setcounter{dbltopnumber}{1} + + + +%% Color related settings: +\usepackage{xcolor} +\color{black} % Text color +\definecolor{DarkBlue}{RGB}{0,0,90} + + +% figure and figure* ordering correction: +\usepackage{fixltx2e} + + + +%% For editing the caption appearence. The `setspace' package defines +%% the `stretch' variable. `abovecaptionskip' is the distance between +%% the figure and the caption. +\usepackage{setspace, caption} +\captionsetup{font=small, labelfont={color=DarkBlue,bf}, skip=1pt} +\captionsetup[figure]{font={stretch=1, small}} +\setlength{\abovecaptionskip}{3pt plus 1pt minus 1pt} + + + +%% To make the footnotes align: +\usepackage[hang]{footmisc} +\setlength\footnotemargin{10pt} + + + +%For including time in the title: +\usepackage{datetime} + + + +%To make links to webpages and include document information in the +%properties of the PDF +\usepackage[ + colorlinks, + urlcolor=blue, + citecolor=blue, + linkcolor=blue, + linktocpage]{hyperref} +\renewcommand\UrlFont{\rmfamily} + + + +% Basic Document information +\hypersetup +{ + pdfauthor={Mohammad Akhlaghi}, + pdfsubject={MUSE detected objects}, + pdftitle={Broadband HST photometry of MUSE detected objects}, + pdfkeywords={Mohammad, Akhlaghi, photometry, MUSE, HST} +} + + + +% Title +\title{A nice title for your research project} +\date{\small Reproduction pipeline \pipelineversion{} + and Gnuastro \gnuastroversion\\on \today, \currenttime} +\author{Your name here.} |