| Age | Commit message (Collapse) | Author | Lines |
|---|
|
The default 'paper.tex' starts by defining some macros and comments
describing them. Until now, the text was not too clear and could be
confusing for someone that is not at all familiar with Maneage.
With this commit, the comments have been edited to be more clear for a
first-time reader. For example they all start with FULL CAPS
summaries.
Two other small things were corrected in 'tex/src/preamble-necessary.tex':
- Until now 'project.tex' was included in this preamble. However, because
of its importance in Maneage, and prominent place in the demonstration
plot of the paper introducing Maneage, it is now included directly in
'paper.tex'. This also allows users to safely ignore/delete this
preamble file if their LaTeX style is different.
- I noticed that some macros for some astronomical software names from the
very first commits in Maneage were still present here! They are no
longer used, so they have been removed.
|
|
The text of the default paper hadn't been changed for a very long time! In
this time, three papers using Maneage have been published (which can be
very good as an example), Maneage also now has a webpage!
With these commit these examples and the webpage have been added and
generally it was also polished a little to hopefully be more useful.
|
|
Possible semantic conflicts (that may not show up as Git conflicts but may
cause a crash in your project after the merge):
1) The project title (and other basic metadata) should be set in
'reproduce/analysis/conf/metadata.conf'. Please include this file in
your merge (if it is ignored because of '.gitattributes'!).
2) Consider importing the changes in 'initialize.mk' and 'verify.mk' (if
you have added all analysis Makefiles to the '.gitattributes' file
(thus not merging any change in them with your branch). For example
with this command:
git diff master...maneage -- reproduce/analysis/make/initialize.mk
3) The old 'verify-txt-no-comments-leading-space' function has been
replaced by 'verify-txt-no-comments-no-space'. The new function will
also remove all white-space characters between the columns (not just
white space characters at the start of the line). Thus the resulting
check won't involve spacing between columns.
A common set of steps are always necessary to prepare a project for
publication. Until now, we would simply look at previous submissions and
try to follow them, but that was prone to errors and could cause
confusion. The internal infrastructure also didn't have some useful
features to make good publication possible. Now that the submission of a
paper fully devoted to the founding criteria of Maneage is complete
(arXiv:2006.03018), it was time to formalize the necessary steps for easier
submission of a project using Maneage and implement some low-level features
that can make things easier.
With this commit a first draft of the publication checklist has been added
to 'README-hacking.md', it was tested in the submission of arXiv:2006.03018
and zenodo.3872248. To help guide users on implementing the good practices
for output datasets, the outputs of the default project shown in the paper
now use the new features). After reading the checklist, please inspect
these.
Some other relevant changes in this commit:
- The publication involves a copy of the necessary software
tarballs. Hence a new target ('dist-software') was also added to
package all the project's software tarballs in one tarball for easy
distribution.
- A new 'dist-lzip' target has been defined for those who want to
distribute an Lzip-compressed tarball.
- The '\includetikz' LaTeX macro now has a second argument to allow
configuring the '\includegraphics' call when the plot should not be
built, but just imported.
|
|
In time, some of the copyright license description had been mistakenly
shortened to two paragraphs instead of the original three that is
recommended in the GPL. With this commit, they are corrected to be exactly
in the same three paragraph format suggested by GPL.
The following files also didn't have a copyright notice, so one was added
for them:
reproduce/software/make/README.md
reproduce/software/bibtex/healpix.tex
reproduce/analysis/config/delete-me-num.conf
reproduce/analysis/config/verify-outputs.conf
|
|
Until now, throughout Maneage we were using the old name of "Reproducible
Paper Template". But we have finally decided to use Maneage, so to avoid
confusion, the name has been corrected in `README-hacking.md' and also in
the copyright notices.
Note also that in `README-hacking.md', the main Maneage branch is now
called `maneage', and the main Git remote has been changed to
`https://gitlab.com/maneage/project' (this is a new GitLab Group that I
have setup for all Maneage-related projects). In this repository there is
only one `maneage' branch to avoid complications with the `master' branch
of the projects using Maneage later.
|
|
The subdirectories here (and the fact that they may be symbolic links) may
be confusing for some early project users, so a `README.md' file was added
there describing them and when they are links, when directories and when
some may not yet exist.
|
|
Until now, the only verification that the template provided was the
published PDF. Users had to manually compare the published and generated
PDFs (numbers, plots, tables) and see if they obtained the same
result. However, this type of manual verification is not good and is prone
to frustration and missing important differences.
With this commit, a new Makefile has been added in the analysis steps:
`verify.mk'. It provides facilities to easily verify the results that go
into the paper. For example tables that go into making the paper's plots,
or the LaTeX macros that blend into the text. See the updated parts in
`README-hacking.md` for a more complete explanation.
This completes task #15497.
|
|
Now that its 2020, its necessary to include this year in the copyright
statements.
|
|
Until now, we weren't explicitly asking for BibLaTeX to build the citations
with only initial of the author's given names. Therefore when one BibTeX
entry had a full given name and another had only initials, this would also
be reflected in the paper's bibliography.
With this commit, the `giveninits=true' option is given to BibLaTeX to
always only print the initial character of an author's given name.
|
|
In some cases, users of the template may not need the other template
headers, they may only want `preamble-biblatex.tex'. But `xcolor' needs to
be loaded before being able to load the various colors we use in the
references. So to be self-consistent, it is loaded.
Also, the default style was also printing the month of the publication
which is not common. So a line was added to clear the `month' field before
building the Bibliography.
|
|
Until now, the paper's title and author information were set it
`tex/src/preamble-header.tex'. But they are actually shown in the final PDF
paper and a much better place to keep them is the top-level `paper.tex'.
With this commit, the setting of the title and author names has been moved
to `paper.tex', just after importing all the preambles. However, the basic
package importation and low-level settings are still set in
`tex/src/preamble-header.tex', because they are relatively low-level.
This task was suggested by Deepak (Indian Institute of Astrophysics).
|
|
In the warnings output by LaTeX during the building of a project, I noticed
that `csquotes' is recommended for some features of BibLaTeX (a warning was
printed) so it is added with this commit.
|
|
Until now, the software building and analysis steps of the pipeline were
intertwined. However, these steps (of how to build a software, and how to
use it) are logically completely independent.
Therefore with this commit, the pipeline now has a new architecture
(particularly in the `reproduce' directory) to emphasize this distinction:
The `reproduce' directory now has the two `software' and `analysis'
subdirectories and the respective parts of the previous architecture have
been broken up between these two based on their function. There is also no
more `src' directory. The `config' directory for software and analysis is
now mixed with the language-specific directories.
Also, some of the software versions were also updated after some checks
with their webpages.
This new architecture will allow much more focused work on each part of the
pipeline (to install the software and to run them for an analysis).
|
|
All occurances of "pipeline" have been chanaged to "project" or "template"
withint the text (comments, READMEs, and comments) of the template. The
main template branch is now also named `template'.
This was all because `pipeline' is too generic and couldn't be
distinguished from the base, and customized project.
|
|
Until now we weren't including the citation for FFTW (one of the template's
optional packages). With this commit, it is added.
|
|
Until now, the files where the people were meant to change didn't have a
proper copyright notice (for example `Copyright (C) YOUR NAME.'). This was
wrong because the license does not convey copyright ownership. So the name
of the file's original author must always be included and when people
modify it (and add their own copyright-able modifications).
With this commit, the file's original author (and email) are added to the
copyright notice and when more than one person modified a file, both names
have their individual copyright notice.
Based on this, the description for adding a copyright notice in
`README-hacking.md' has also been modified.
|
|
Until now, there was a single `tex/src/references.tex' file that housed the
BibTex entries for everything (software and non-software).
Since we have started to include the BibTeX entry for more software, it
will be hard to manage the large (sometime unused) BibTeX entries of the
software in the middle of the non-software related citations in the text of
the paper.
Therefore, with this commit, a `tex/dependencies' directory has been made
which has a separate BibTeX entry file for each software that needs
one. After the software is built, this file is copied to the new
`.local/version-info/cite' directory. At the end, the configure script will
concatenate all the files in this directory into one file which will later
be used with `tex/src/references.tex' by BibLaTeX.
This greatly simplifies managing of citations. Allowing us to focus on the
software-building and paper-writing citations separately/cleanly (and thus
be more efficient in both).
|
|
Some recent corrections that were done by Raul are now merged into the
pipeline. There weren't any conflicts.
|
|
Until now, the Scipy citation was only one paper and not the correct one
(it was the online manual).
With this commit, Scipy is properly cited using the two papers. Also
some modifications in the `tex/src/references.tex' have been done
(remove last page number).
|
|
Until now, name and version of all Python packages were indicated in the
final paper, but not the main paper of them (if it exists).
With this commit, some Python packages (Cython, Matplotlib, Numpy and
Scipy) are now properly acknoledged by citating the source paper.
`mpi4py' is also cited although this package is not yet included into
the pipeline.
|
|
With this commit, we are applying the new style of citing software within
the build rule of Gnuastro.
|
|
After doing a systematic search for files without a copyright notice, a few
more were found that didn't have a notice. So a notice was added for them.
I used this Bash command to find the files:
for f in $(find ./ -type f); do \
if [[ $f != *.git* ]]; then \
n=$(grep -i copyright $f | wc -l); \
echo "$n $f"; \
fi; \
done | awk '$1==0'
|
|
In order to be more clear, a copyright statement was added to all the LaTeX
and README files.
|
|
Raul Infante-Sainz added the building of Python (along with the Numpy and
Astropy packages) into the pipeline. That work is now being merged into the
main pipeline branch.
There was only this small problem that needed to be fixed: the Python
tarball's name after unpacking is actually `Python-X.X.X' (with a captial
P), not `python-X.X.X'. This has been corrected with this merge.
|
|
Astropy was added and one very important thing is that we have to
use the pypi tarball (https://pypi.org/) (which is bootstrapped)
and not the github tarball.
|
|
In order to collaborate effectively in the project, even project members
that don't necessarily want (or have the capacity) to do the whole analysis
must be able to contribute to the project. Until now, the users of the
distributed tarball could only modify the text and not the figures (built
with PGFPlots) of the paper.
With this commit, the management of TeX source files in the pipeline was
slightly modified to allow this as cleanly as I could think of now! In
short, the hand-written TeX files are now kept in `tex/src' and for the
pipeline's generated TeX files (in particular the old `tex/pipeline.tex'),
we now have a `tex/pipeline' symbolic-link/directory that points to the
`tex' directory under the build directory.
When packaging the project, `tex/pipeline' will be a full directory with a
copy of all the necessary files. Therefore as far as LaTeX is concerned,
having a build-directory is no longer relevant. Many other small changes
were made to do this job cleanly which will just make this commit message
too long!
Also, the old `tarball' and `zip' targets are now `dist' and `dist-zip' (as
in the standard GNU Build system).
|
|
With this commit, it is now possible to package the project into a tarball
or zip file, ready to be distributed to collaborators who only want to
modify the final paper (and not do the analysis technicalities), or for
uploading to sites like arXiv, or online LaTeX sharing pages.
|
|
Until now, we were keeping the input file within the reproduction
pipeline's directories using the same name as the database/server. Now, we
are using a short/summarized filename convention for the input dataset.
|
|
In most analysis situations (except for simulations), an input dataset is
necessary, but that part of the pipeline was just left out and a general
`SURVEY' variable was set and never used. So with this commit, we actually
use a sample FITS file from the FITS standard webpage, show it (as well as
its histogram) and do some basic calculations on it.
This preparation of the input datasets is done in a generic way to enable
easy addition of more datasets if necessary.
|
|
Since the final product of the pipeline is a LaTeX-created PDF file, it was
necessary to also have LaTeX within the pipeline. With this commit, TeX
Live is also built as part of the configuration and all the necessary
packages to build the PDF are also installed and mentioned in the paper
along with their versions.
|
|
Some minor corrections have been made in the paper's text to make things
easier to read and be more formal.
|
|
All the used software are now acknowledged in the template paper along with
their versions. This section is also mentioned in the check list, so users
don't delete it by mistake.
|
|
Different implementations of AWK may use different random number
generators, so even setting the seed will not ensure a reproducible
result. Because of this, the random plot may be different when the
pipeline runs on different systems and this can confuse early users
(its contrary to the exact reproducibility that is the whole purpose
of this pipeline).
The plot is just a simple X^2 plot, showing the squared value of the X
axis on the Y axis. It is very simple, but atleast it will be
identical on all systems. Also, there may be too many complicated
things in the pipeline already for an early user, and its just a
demonstration, so the easier/simpler, the better.
|
|
The computer modern font that was designed by Donald Knuth and is the
default of LaTeX is indeed a very good, elegant and nice font in
print. However, most journals choose the roman fonts and thus the computer
modern font doesn't (subjectively) fit into the journal format nicely. So
the default font of this pipeline's paper now uses LaTeX's `newtx' package
for a roman style font.
Also, a set of preamble settings were added to allow headers in the pages
of the paper to make the result resemble more like a journal paper
(familiar to the eye), while also adding important information. A new
header was made for this job. This new header now also contains the title
and author settings (after all, these are also a type of header).
Finally, the LaTeX `authblk' package was used to organize authors and their
affiliations.
|
|
An abstract is also something most research reports will need, so a simple
macro was defined to make it easy (not too many code lines within the text
of the main body) to implement an abstract.
The title was also moved up a little to better use the extra white space at
the top of the page.
Finally, the `\highlightchanges' along with its explanation (both as
comments and within the text with examples) was added in `paper.tex' to
demonstrate how useful the `\new' and `\tonote' macros are.
|
|
Until now, we were using the `multicol' package which is mainly designed
for more than two columns. Instead, we are just passing a `twocolumn'
option to the article document class.
|
|
The comments in the preambles were made more clear and elaborate.
|
|
Making plots and including references are integral parts of a scientific
paper. Therefore to demonstrate how cleanly they can be used within the
pipeline, they are now used to produce the final PDF.
To use PGFPlots a random dataset is made (using AWK's random function) and
is plotted using PGFPlots. The minimum and maximum values of the dataset
are also included in the text to further show how such calculations can go
into the macros and text.
For the references, the NoiseChisel paper was added as a reference to cite
when using this pipeline along with the MUSE UDF paper I, which uses this
pipeline for two sections. Following this discussion, citation is also
discussed in `README.md` and the NoiseChisel paper is also added as a
published work with a reproduction pipeline.
|
|
Until now, the copyright statement was left empty for the users of the
pipeline to fill. However, the files have already been created and have an
author (or contributing authors) before the user starts using the
pipeline. So the original authors of the files are added along with the
year. The user can add their own name to the existing files under the
"Contributing author" when they start and they will be the "Original
author" of the new files they create.
Several changes were also made to the TeX management:
- LaTeX is run within a `reproduce/build/tex/build' directory now. Not in
the top reproduction pipeline directory. This helps keep all the
auxiliary TeX files and directories in that directory and keep the top
reproduction pipeline directory clean. After the final PDF is built, a
copy is put in the top reproduction pipeline directory for easy viewing.
- The PGFPlots preamble was also made more useful, allowing the name of
the `.tex' file to also be the name of the final plot that is
produced. This is a GREAT feature, because without it, the TiKZ
externalization would be based on order of the plots within the
paper. But now, order is irrelevant and we can even delete the TiKZ
files within the processing workhorse-Makefiles so the plots are
definitly rebuilt on the next run.
- The paper is now in a two-column format to be more similar to published
papers.
A tip on debugging Make was added to `README.md'.
|
|
The first commit didn't have an explanation on correcting the title of the
project in the final PDF or the top-level Makefile, so a pointer was added
to the list. Also, some extra dependencies were removed from `README' and
its paragraphs were scaled to the new width of 75 characters that is
defined in `.dir-locals.el' (for Emacs settings, taken from Gnuastro).
|
|
Let's start working on this pipeline independently with this first
commit. It is based on my previous experiences, but I had never made a
skeleton of a pipeline before, it was always within a working analysis.
But now that the pipeline has a separate repository for its self, we will
be able to work on it and use it as a base for future work and modify it to
make it even better. Hopefully in time (and with the help of others), it
will grow and become much more robust and useful.
|
