Skip to content

Filling out Justifications

In Polaris there are two Justification "flavours": Scientific and Technical.

Both Justifications are to be provided as LaTex text strings. That is, text decorated with the usual LaTex commands for figures, tables, and citations (or whatever else you wish to put in your document)

These texts will be inserted into the following "main.tex" file under the relevant section headings:

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% 
\documentclass[11pt,a4paper,twoside]{article}
%
\usepackage[textwidth=17.5cm,textheight=25cm,headheight=14pt]{geometry}
\usepackage{graphicx}
\usepackage{subfig}
\usepackage{wrapfig}
\usepackage{fancyhdr}
\usepackage[square,numbers,super]{natbib}

% latex working directory is created as a child of where the images are stored %
\graphicspath{{../}}

% condense the line separation between bibitems
\setlength{\bibsep}{1pt plus 0.3ex}

...

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\begin{document}
% Header file created on compilation
    \input{justificationsHeader}

% Justification files created on compilation
    \section*{Scientific Justification}
    \input{scientificJustification}

    \section*{Technical Justification}
    \input{technicalJustification}

    \bibliographystyle{polaris}
% Users are expected to provide a single bibliography file.
% It will be copied and renamed to "refs.bib" in the working directory
    {
        \footnotesize
        \bibliography{refs}
    }

\end{document}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
The ellipsis (...) in the file replaces a lengthy section where we define custom "insert figure" functions. These functions are described in detail in the Help tab found on the Justifications page in Polaris. Also see the Custom Insert Figure Functions section below.

The following screenshot shows the Justifications page in Polaris. Please notice that the two Justification text areas are found in separate tabs labelled Scientific Justification and Technical Justification, along with the Help tab.

polaris justifications page

Scientific Justification

The scientific justification should include all the physics reasons why you want to perform the observation(s) specified in this proposal. This will likely be the same regardless of the Proposal Cycle to which you will be submitting the proposal.

The scientific justification is limited to a maximum of 15000 characters.

Technical Justification

The technical justification should outline the reasons for your choice of observatory, and their capabilities to achieve the technical goals you've set. Choice of observatory is made when submitting the proposal, different Proposal Cycles are associated with different observatories. If you wish to submit this proposal to multiple observatories, you will likely need to edit the technical justification to tailor it to each observatory.

The technical justification is limited to a maximum of 5000 characters.

Resource Files

The Resource Files area is where you upload your image files to be inserted as figures into your Justifications, and a single bibliography file (*.bib) that you use for citations - to reference a citation you use the normal LaTex syntax i.e., ~\cite{referenceLabel}.

Please note that image formats are restricted to '.jpg', '.png', '.eps', and '.pdf', and be aware that uploading an image file with the same filename as an existing file will overwrite that file, and there will be no warning. You cannot have multiple bibliography files.

We are using our own bibliography style template that (generally) gives only the sufficient details of a reference to find the associated article.

Custom Insert Figure Functions

As we have limited the length of Justifications you may not want to waste precious characters on LaTex syntax, especially when it comes to inserting figures into your document. For that reason we have provided you with some custom functions to try to help reduce the number of characters required to insert figures. These are namely:

  • \onefigure[width]{filename}{caption}
  • \twofigures[width]{filename1}{filename2}{caption}
  • \threefigures[width]{filename1}{filename2}{filename3}{caption}
  • \fourfigures[width]{filename1}{filename2}{filename3}{filename4}{caption}
  • \textwrapfigure[width]{filename}{caption}{position}

The width parameter is optional but if provided should a decimal number between 0 and 1, defining the width of the figure in terms of the text-width. It defaults to 0.5 for the single figure cases, and is an even division of the total text-width for the multiple figure cases. If supplied, the width parameter for the multiple figure cases applies to each of the images in the figure, rather than the whole figure itself.

The filename parameter(s) should match the name of the image file(s) that you wish to insert. You may exclude the dot extension part of the filename, just remember that the filename string parameter is used in the figure label.

The caption parameter is the description of the figure you are inserting. Please note captions count towards the characters used so try to be concise.

To reference a figure in your text, use the following syntax: \ref{fig:filename}. Again remember that the 'filename' is literally that which you supplied in the insert figure command. For the multiple figure cases, the 'filename' should be the name of the first filename parameter. There is one, edge-case issue with this labelling strategy. If you have a single figure that uses an image file repeated as the first image in a multiple figure command, you'll get a naming conflict. The most straightforward way around this issue would be to exclude the dot extension for one of the filenames. If you're including the same image in more than two figures (though you'd better have a good reason for doing this) then you could upload the image with different filenames such that the figure labels will be different.

Notice that the two figure and three figure functions will place the images in a single row, whereas the four figure function will place the images in a two-by-two arrangement.The astute among you will have deduced then that the product of the width value with the number of figures must not exceed one, else the figures will overflow the text. In the case of the four-figure command due to the two-by-two arrangement, two times the width parameter must not exceed one. For the multiple figure functions, each image will be labelled '(a)' through to '(d)' where appropriate.

If the multiple figure-caption layout is not to your liking, or you have more than four images to place in a figure, then you can always create your own multiple figure as a single image file and use the "onefigure" command.

For the 'textwrapfigure' command an additional parameter specifies the position of the figure you want to text-wrap. Either 'l' or 'L' for the image on the left, or 'r' or 'R' for the image on the right. The uppercase version allows the image to float, whereas the lowercase version means exactly here. (Our command uses the 'wrapfigure' environment from the 'wrapfig' package).

Compiling your Justification

To compile your Justification document simply click the Compile to PDF button. We recommend keeping 'Warnings as errors' checked. After a short delay waiting for the compilation to complete on the server, a modal will open displaying the status of the compilation.

If you have compilation errors they will be listed in the Latex Status section of the modal. Typically, these will be caused by typos in the LaTex commands or missing resource files. To illustrate in the following screenshot we have tried to compile a document with an inserted a figure using an image file named 'missing' we have yet to upload to the server.

polaris Justification compilation failure

Please notice that if you do have compilation errors you may also have warnings with regard to references. This is because Latex generally has to make two parses of any source files, first to work out the document structure, the second to get cross-referenced labels and numbering correct. As user errors typically occur during the first parse, the second parse is not done hence the warnings about cross-references.

If your compilation was successful you will see the following output in the modal.

polaris Justification compilation success

It will give you a page count and a Download PDF button that when clicked downloads the compiled document. Another Download PDF button will also appear in the Justifications main page. Please be aware that the button on the Justifications main page, will download the latest successfully compiled document only.

For your information, you will see a CYCLE ID HERE placeholder in the header of the document. This is for the Time Allocation Committee (of a particular Proposal Cycle) use only, and is replaced with an actual value upon submission of the proposal to a cycle.