diff --git a/docs/Observer/Creating Proposals/adding-targets.md b/docs/Observer/Creating Proposals/adding-targets.md index 3477d84..6695049 100644 --- a/docs/Observer/Creating Proposals/adding-targets.md +++ b/docs/Observer/Creating Proposals/adding-targets.md @@ -1,46 +1,83 @@ +--- +title: Adding Targets +date: 2025-10-21 +description: > + _Guide to adding **Targets** to your proposal_ +categories: [Examples] +tags: [test, sample, docs] +--- -# Add a Target +Last updated: 2025-10-21 Polaris _beta_ version + +# Adding a Targets A fresh proposal will have no **Targets** added, and you will be presented with the following page: -![add a target](targets_none.png) +![add a target](polaris-targets-none.png) + +# Add a Single Target +To add a single **Target** click the _Add One Target +_ button, which will bring up the _New Target_ form. -To add a **Target** click the _Add +_ button, which will bring up the _New Target_ form. +!["new target form](polaris-simbad-search-target.png) -!["new target form](targets_new.png) +In the screenshot you will see we have found the _Crab Nebula_ using the **SIMBAD search** function. +This fills in the corresponding positional and coordinate system data for the named target, and displays +the target in the [Aladin Lite Sky Atlas](https://aladin.cds.unistra.fr/). -In the screenshot you will see we have added the [Aladin Lite Sky Atlas](https://aladin.cds.unistra.fr/), -and we have found the _Crab Nebula_ using the **Lookup** function. This fills in the corresponding -positional and coordinate system data for the named target, and displays the target in the Sky Atlas. Notice that the backend uses [Simbad](https://simbad.cds.unistra.fr/simbad/) to search for the named target, such that the name must exist in their databases to be successful; an appropriate error notification is displayed if the -named target cannot be found. +named target cannot be found. We have provided useful help, hints, and tips to aid in using the search +facility. Notice that the name displayed after selecting a search item is the _main-id_ found in the Simbad +database. In the screenshot shown the _main-id_ for the Crab Nebula is "M 1". -You may also simply click anywhere on the Sky Atlas and the corresponding positional details will be -updated in the RA and DEC fields (notice that these are currently displayed as degrees only, we have -development plans to add _HH:MM:SS_ format and to allow you to select between the units with which you -are most comfortable). +You may also double-click anywhere on the displayed Sky Atlas. This will centre the Atlas under the +position you just double-clicked and fill out the form with a "random" target name and the corresponding +positional details will be updated in the RA and DEC fields. These will be displayed as sexagesimal with +the equivalent degree value displayed under the field box. You can also manually fill in the fields, the Sky Atlas will automatically change the view to those -coordinates. Notice that in this alpha version of Polaris, you can have any coordinate system you like, -so long as it's _J2000_. +coordinates. Notice that in this beta version of Polaris, you can have any coordinate system you like, +so long as it's _J2000_ with an ICRS reference system. + +You can change the name of the target after you have looked it up and before you save it as a +**Target**. Be aware that each target must have a unique name within a proposal. To save, click the _Save_ +button. This will return you to the **Targets** page of your proposal +now displaying the **Target** you just saved, and any other targets you may have added. Clicking _Cancel_ +on the new target form will take you back to the targets list page without saving. + +![list of targets](polaris-target-list.png) + +You may _Delete_ this **Target** if you so wish, just remember that you need at least one target in order +to build an **Observation** for your proposal. For information, you will not be able to delete **Targets** +that currently belong to an **Observation** - the corresponding **Observation** must be deleted first. -You may also change the name of the target after you have looked it up and before you save it as a -**Target**. To save, click the _Save_ button. This will return you to the _Targets_ tab of your proposal -now displaying the **Target** you just saved, and any other targets you may have added. +## Adding Several Targets via File Upload -![list of targets](targets_some.png) +Instead of adding **Targets** one at a time, we have provided a means to add several **Targets** at once +via a file upload; click the _Upload List of Targets_ button. Compatible files are **VOTable xml** (obtained +from _Simbad_ or another service), **Astropy generated ecsv**, or manually created txt. We recommend using +either the VOTable xml or the Astropy generated ecsv but if you are a masochist read on. +The manually created txt file should have the following format: -Please notice that the _Reference System_ should read _ICRS_ but due to some bug that has yet to be -squished it reads _unknown_; did I mention this was the alpha version? +``` +#name,ra,dec,pmra,pmdec,plx,rv +alpha,12.987,34,42,69,,99 +beta,56,78,11,13,33,112 +gamma,90,-12,38,-34,-1,-86 +``` -You may _Delete_ this target if you so wish, just remember that you need at least one target in order -to build an **Observation** for your proposal. +where you are required to provide the columns 'name', 'ra', and 'dec' of the targets, the other +columns may be omitted with the caveat that if you provide one proper-motion ('pm') column, you must provide the +other. The names can only be ASCII characters and the other values are integer or decimal digits. All units are in degrees +or degrees per second for rates. The order of the columns is not important (to the code at least, +to your sanity maybe). Any optional data value i.e., 'pmra', 'pmdec', 'plx', 'rv', that isn't available but for which +you have a column should be left blank e.g., the target 'alpha' in the (made-up) list above has no parallax data. Again +we recommend using either one of the other two formats to add a list of targets. ## Next Step If you haven't already added a **Technical Goal** then please follow the guide [here](adding-technical-goals.md). If you have now added at least one **Target** and one **Technical Goal** to your proposal then please -follow the link to [**Building Observations**](build-observation.md). \ No newline at end of file +follow the link to [**Building an Observation**](build-observation.md). \ No newline at end of file diff --git a/docs/Observer/Creating Proposals/adding-technical-goals.md b/docs/Observer/Creating Proposals/adding-technical-goals.md index f39baef..784c454 100644 --- a/docs/Observer/Creating Proposals/adding-technical-goals.md +++ b/docs/Observer/Creating Proposals/adding-technical-goals.md @@ -1,44 +1,49 @@ --- title: Adding Technical Goals -date: 2024-03-04 +date: 2025-10-21 description: > _Guide to adding **Technical Goals** to your proposal_ categories: [Examples] tags: [test, sample, docs] --- +Last updated: 2025-10-21 Polaris _beta_ version + # Add a Technical Goal A fresh proposal will have no **Technical Goals** and you will be presented with the following page: -![no technical goals summary page](technical_goals_none.png) +![no technical goals summary page](polaris-tech-goals-none.png) To add a **Technical Goal** click the _Add +_ button, which will bring up the _New Technical Goal_ form. -![new technical goals form](technical_goals_new.png) +![new technical goals form](polaris-tech-goals-new.png) -In the screenshot you can see we have filled out the _Performance Parameters_ with some values and their -corresponding units; the values in the screenshot are contrived for this guide. The units are selected via a -drop-down menu. These values are what you would like the observation to achieve, and are not necessarily strict -requirements. Further explanation of each field can be found [here](???) (to-do). The _Performance Parameters_ -are the minimum amount of information required to _Save_ (screenshot reads _Submit_ because alpha version) a -**Technical Goal**. For now, we ignore the _Spectral Window_ aspect of a **Technical Goal**, to be revisited later. +The values can be freely entered but the units are selected via a drop-down menu. These values are what you would +like the observation to achieve, and are not necessarily strict requirements. The _Performance Parameters_ are the +minimum amount of information required to _Save_ a **Technical Goal**. For now, we ignore the _Spectral Window_ +aspect of a **Technical Goal**, to be revisited later. After clicking _Save_ you will be brought back to the technical goals summary page, which should now display your newly added **Technical Goal**. -![technical goals summary page](technical_goals_some.png) +![technical goals summary page](polaris-tech-goals-list.png) + +In the screenshot you can see we have filled out the _Performance Parameters_ with some values and their +corresponding units; the values in the screenshot are contrived for this guide. Unlike **Targets**, you can also _Edit_ and _Copy_ **Technical Goals** as well as _Delete_ them. This allows you to change the attributes of an existing **Technical Goal**, or quickly add other **Technical Goals** that may have -similar _Performance Parameters_ and/or _Spectral Windows_ without having to re-input all the data. +similar _Performance Parameters_ and/or _Spectral Windows_ without having to re-input all the data. If a +**Technical Goal** currently belongs to an **Observation** then it cannot be deleted, unless the corresponding +**Observation** is deleted first. However, the _Edit_ and _Copy_ functions are still available. ## Next Step If you haven't already added a **Target** then please follow the guide [here](adding-targets.md). If you have now added at least one **Target** and one **Technical Goal** to your proposal then please follow the -link to [**Building Observations**](build-observation.md). \ No newline at end of file +link to [**Building an Observation**](build-observation.md). \ No newline at end of file diff --git a/docs/Observer/Creating Proposals/build-observation.md b/docs/Observer/Creating Proposals/build-observation.md index 570e61b..b1dd173 100644 --- a/docs/Observer/Creating Proposals/build-observation.md +++ b/docs/Observer/Creating Proposals/build-observation.md @@ -1,34 +1,42 @@ - +--- +title: Build an Observation +date: 2025-10-21 +description: > + _Guide to building an **Observation** for your proposal_ +categories: [Examples] +tags: [test, sample, docs] +--- # Build an Observation After adding at least one **Target** and at least one **Technical Goal** you will see the following summary page for **Observations**, which will be empty. -![empty Observations summary page](observations_none.png) +![empty Observations summary page](polaris-observation-none.png) To build an **Observation** click the _Add +_ button, which will bring up the new observation form. -![new Observation form](observations_new.png) +![new Observation form](polaris-observation-create.png) -In this screenshot we have already selected our **Target**, the "crab", and our **Technical Goal**, and have -selected the _Observation Type_ as _Calibration_ and the _Calibration intended use_ as _Pointing_. Notice that -the _Observation Type_ is a choice between _Target_ and _Calibration_, and if you select _Target_ there is no -"intended use" field; the **Target** is the intention of the **Observation**. For a _Calibration_ **Observation** -there are several "intended use" options to pick from; see the [documentation](???) (to-do) for details. +In this screenshot we have yet to fill in the data. You must select the _Type_ of **Observation** either _Target_ +or _Calibration_. If selecting _Calibration_ you must also select the _Intended Use_ of the calibration. There +are several options here including _Pointing_, _Bandpass_, _Focus_, and _Delay_ amongst others. +The messages in red describe the necessary fields that are required to create an **Observation** after selecting +its type and intended use where appropriate. -Selecting the **Target**, **Technical Goal**, and _Observation Type_ is the minimum amount of information to _Save_ -an **Observation** to the database. However, for the **Proposal** to pass the server side validation before -submission, all **Observations** in the **Proposal** must have at least one **Timing Window**. +Each **Observation** must have at least one **Target** and multiple selections are allowed. **Observations** can +only have one **Technical Goal** selected, and you must provide at least one **Timing Window**. A **Timing Window** is a timing constraint on the **Observation**, and consists of _start_ and _end_ times that can be specified up to the minutes unit, an _avoid_ toggle switch that changes the meaning of the window, to be explained presently, and an optional note to provide additional information if required. Typically, a **Timing Window** will specify the range of times when the **Observation** should be performed i.e., the _avoid_ toggle is unset. However, with the _avoid_ toggle set the window then specifies the range of times when the -**Observation** should **_not_** be performed. +**Observation** should **_not_** be performed. (Notice that +the **Timing Window** must relate to the **Proposal Cycle** _session_ interval to which you will be submitting +the proposal - this validation check is done during the submission process.) You can add as many **Timing Windows** to an **Observation** as required by your needs. Please note that the _start_ time must be at an earlier time than the _end_ time, but that different **Timing Windows** may overlap. @@ -38,22 +46,22 @@ Notice that we assume all times are entered as UTC. With all that information entered, click _Save_ to save the **Observation** to your **Proposal**. This will bring you back to the _Observations_ summary page, that will now contain your newly built **Observation**. -![Observations summary page](observations_some.png) +![Observations summary page](polaris-observation-list.png) As with **Technical Goals** you may _Edit_ and _Copy_ **Observations** to avoid having to repeat data entry for **Observations** that have similar attributes. For example, using the same **Target** but for different types, _Target_ or _Calibration_, of **Observation** with perhaps the same **Technical Goal** and/or timing constraints. -With an **Observation** now built both the **Target** and the **Technical Goal** to which is refers have their -_Delete_ button disabled. This prevents you from deleting either of these things while they are actively pointed +With an **Observation** now built both the **Target** and the **Technical Goal** to which it refers have their +_Delete_ button disabled. This prevents you from deleting either of these things while they are actively referred to by an **Observation**. In order to re-enable the _Delete_ button on **Targets** and **Technical Goals** you -must first delete all **Observations** that refer to them. +must first delete all **Observations** that refer to them. + +## Next Steps -In this alpha version of Polaris, once you have an **Observation** with at least one **Timing Window** in your -**Proposal** it will pass server side validation checks, and you may submit it for review. In subsequent versions, -you will also have to provide both **Scientific** and **Technical Justifications** to pass validation checks, and -it is likely more things will be added to the validation check in the future. +If you have yet to fill out the Justifications for your proposal please follow the guide at +[**Justifications**](../Justifications/index.md) To see how to submit your proposal for review please follow the guide at [**Submitting Proposals**](../Submitting%20Proposals/index.md) \ No newline at end of file diff --git a/docs/Observer/Creating Proposals/index.md b/docs/Observer/Creating Proposals/index.md index 5c3cc2f..fb8869f 100644 --- a/docs/Observer/Creating Proposals/index.md +++ b/docs/Observer/Creating Proposals/index.md @@ -1,23 +1,47 @@ +## Notice about the Polaris version + +This documentation is for the _beta_ version of Polaris. + +Last updated **2025-10-21** + ## First, Login If you haven't registered with and logged-in to Polaris please do so [now](https://kilburn.jb.man.ac.uk/pst/gui/tool/). +In the following guide we are logged in as "John Flamsteed" as an obvious fake user. + +## **Create a new proposal** + +To create a new **Proposal** click on the _Create new proposal +_ button on your home page. This is highlighted +by the red circle in the screenshot below. + +![polaris home page, highlighting the create a new proposal button](polaris-home-page-fresh.png) + -## Click the **Create a new proposal** button +Please notice that this screenshot is in dark-mode. +You may select light-mode by clicking the toggle button in the very top right of the window, left of the +"user management" button. When in dark-mode the button will be a "sun", meaning go-to light-mode, and when +in light-mode it will be a "crescent-moon", meaning got-to dark-mode. The following screenshot shows what +light-mode looks like. -![polaris landing page, highlighting the create a new proposal button](proposal_create.png) +![polaris home page, showing light-mode](polaris-home-page-light.png) +Switch to which ever mode you want. The author of this guide prefers dark-mode so that is the mode the rest +of the screenshots will show. -This will bring up the new **Proposal** details form. +After clicking the _Create new proposal +_ button you will be taken to the new proposal form page. -## Fill in the proposal details form and click **Create** +## Fill in the proposal details form and click **Save** -![create proposal details](proposal_create_details.png) +![create proposal details](polaris-create-proposal.png) -The basic details of an **Observing Proposal** are the title, a brief summary, and the **Kind** of your proposal -either _STANDARD_, _SURVEY_, or _T.O.O._ (target-of-opportunity). These attributes can be changed after you create -the proposal. +The basic details of an **Observing Proposal** are the title, a brief Summary, and the "kind" of your proposal +either _STANDARD_, _SURVEY_, or _T.O.O._ (target-of-opportunity). The Summary is limited to 1000 characters. +These values can be edited after you create +the proposal. Please note that we have help buttons located on the top right of most pages - a blue question mark in +a hexagonal border - that will drop down some basic textual help for the current page. +If a page does not have this button the help will be located in a tab on the page somewhere. ## The Proposal Overview @@ -25,26 +49,47 @@ Now that you have a created a new proposal you can see its **Overview** by click menu for the relevant proposal in the navigation pane on the left, and clicking on the _Overview_ tab. -![the proposal overview](proposal_overview.png) +![the proposal overview](polaris-overview-fresh.png) In the screenshot example we have given our proposal the title _An awesome proposal title_, filled -in the summary with a very brief summary (literally), and assigned it a **Kind** of _STANDARD_. Notice +in the summary with a very brief summary, and assigned it a **Kind** of _STANDARD_. Notice that, as the creator of the new proposal, you will have been automatically assigned the **PI**, or -Principal Investigator, role for the proposal (in the example we used for the screenshots, the -username is also _PI_; nobody said we had to be inventive). +Principal Investigator role for the proposal. + +## Proposal Services + +You will notice three buttons at the top of the overview page, namely _Export Proposal_, _Clone Proposal_, and +_Delete Proposal_. + +_Export Proposal_ provides a downloadable zip file containing this proposal as JSON, any supporting +documents you may have uploaded, and a screenshot of this overview. The astute among you will have realised this +is the file you then upload when you click on the button _Import existing proposal_. The intention of this is to allow +you to transfer proposals between different instanced of the Polaris application. + +_Clone Proposal_ creates a deep copy of the current proposal as a new proposal i.e., everything is copied - +targets, technical goals, observations, justifications, supporting documents, ... + + +_Delete Proposal_ will permanently remove the proposal from the system. Notice that if the proposal has been submitted +to a **Proposal Cycle** the **Submitted Proposal**, which is a separate entity to the currently active proposal, is +_NOT_ removed from the cycle. +**Submitted Proposals** can be thought of as a "snapshot" of the proposal, frozen at the point of submission. We would +recommend that you don't delete proposals that are actively submitted to a cycle i.e., under review, but this is not +a restriction. ## Next Steps: adding Targets and Technical Goals If you now try to go to the _Observations_ tab you will be presented with the following page: -![trying to add observation before adding targets and technical goals](observations_missing_target_goal.png) +![trying to add observation before adding targets and technical goals](polaris-observations-missing-target-tech.png) In the Polaris app you must first add at least one observational **Target** and at least one **Technical Goal** before you can generate an **Observation** for your proposal. Notice that the yellow text in the screenshot is a link to take you to the corresponding page in the App. -For the next steps in this guide, please follow either the **Adding Targets** link or the **Adding Technical Goals** -link, the order here does not matter. The **Building Observations** page assumes you have added at least one target -and at least one technical goal to your proposal. +For the next steps in this guide, please go to either [**Adding Targets**](adding-targets.md) or +[**Adding Technical Goals**](adding-technical-goals.md), the order here does not matter. +The [**Building an Observation**](build-observation.md) guide assumes you have added at least one target and at least +one technical goal to your proposal. diff --git a/docs/Observer/Creating Proposals/observations_missing_target_goal.png b/docs/Observer/Creating Proposals/observations_missing_target_goal.png deleted file mode 100644 index ca4d22a..0000000 Binary files a/docs/Observer/Creating Proposals/observations_missing_target_goal.png and /dev/null differ diff --git a/docs/Observer/Creating Proposals/observations_new.png b/docs/Observer/Creating Proposals/observations_new.png deleted file mode 100644 index 765fb96..0000000 Binary files a/docs/Observer/Creating Proposals/observations_new.png and /dev/null differ diff --git a/docs/Observer/Creating Proposals/observations_none.png b/docs/Observer/Creating Proposals/observations_none.png deleted file mode 100644 index c5d36db..0000000 Binary files a/docs/Observer/Creating Proposals/observations_none.png and /dev/null differ diff --git a/docs/Observer/Creating Proposals/observations_some.png b/docs/Observer/Creating Proposals/observations_some.png deleted file mode 100644 index 590868c..0000000 Binary files a/docs/Observer/Creating Proposals/observations_some.png and /dev/null differ diff --git a/docs/Observer/Creating Proposals/polaris-create-proposal.png b/docs/Observer/Creating Proposals/polaris-create-proposal.png new file mode 100644 index 0000000..39039e6 Binary files /dev/null and b/docs/Observer/Creating Proposals/polaris-create-proposal.png differ diff --git a/docs/Observer/Creating Proposals/polaris-home-page-fresh.png b/docs/Observer/Creating Proposals/polaris-home-page-fresh.png new file mode 100644 index 0000000..cb2f515 Binary files /dev/null and b/docs/Observer/Creating Proposals/polaris-home-page-fresh.png differ diff --git a/docs/Observer/Creating Proposals/polaris-home-page-light.png b/docs/Observer/Creating Proposals/polaris-home-page-light.png new file mode 100644 index 0000000..67deda0 Binary files /dev/null and b/docs/Observer/Creating Proposals/polaris-home-page-light.png differ diff --git a/docs/Observer/Creating Proposals/polaris-observation-create.png b/docs/Observer/Creating Proposals/polaris-observation-create.png new file mode 100644 index 0000000..95b2d7f Binary files /dev/null and b/docs/Observer/Creating Proposals/polaris-observation-create.png differ diff --git a/docs/Observer/Creating Proposals/polaris-observation-list.png b/docs/Observer/Creating Proposals/polaris-observation-list.png new file mode 100644 index 0000000..cad0d1d Binary files /dev/null and b/docs/Observer/Creating Proposals/polaris-observation-list.png differ diff --git a/docs/Observer/Creating Proposals/polaris-observation-none.png b/docs/Observer/Creating Proposals/polaris-observation-none.png new file mode 100644 index 0000000..2e3d9e9 Binary files /dev/null and b/docs/Observer/Creating Proposals/polaris-observation-none.png differ diff --git a/docs/Observer/Creating Proposals/polaris-observations-missing-target-tech.png b/docs/Observer/Creating Proposals/polaris-observations-missing-target-tech.png new file mode 100644 index 0000000..8d8988a Binary files /dev/null and b/docs/Observer/Creating Proposals/polaris-observations-missing-target-tech.png differ diff --git a/docs/Observer/Creating Proposals/polaris-overview-fresh.png b/docs/Observer/Creating Proposals/polaris-overview-fresh.png new file mode 100644 index 0000000..791ef89 Binary files /dev/null and b/docs/Observer/Creating Proposals/polaris-overview-fresh.png differ diff --git a/docs/Observer/Creating Proposals/polaris-simbad-search-target.png b/docs/Observer/Creating Proposals/polaris-simbad-search-target.png new file mode 100644 index 0000000..438858b Binary files /dev/null and b/docs/Observer/Creating Proposals/polaris-simbad-search-target.png differ diff --git a/docs/Observer/Creating Proposals/polaris-target-list.png b/docs/Observer/Creating Proposals/polaris-target-list.png new file mode 100644 index 0000000..75d24ff Binary files /dev/null and b/docs/Observer/Creating Proposals/polaris-target-list.png differ diff --git a/docs/Observer/Creating Proposals/polaris-targets-none.png b/docs/Observer/Creating Proposals/polaris-targets-none.png new file mode 100644 index 0000000..0f79446 Binary files /dev/null and b/docs/Observer/Creating Proposals/polaris-targets-none.png differ diff --git a/docs/Observer/Creating Proposals/polaris-tech-goals-list.png b/docs/Observer/Creating Proposals/polaris-tech-goals-list.png new file mode 100644 index 0000000..877cd30 Binary files /dev/null and b/docs/Observer/Creating Proposals/polaris-tech-goals-list.png differ diff --git a/docs/Observer/Creating Proposals/polaris-tech-goals-new.png b/docs/Observer/Creating Proposals/polaris-tech-goals-new.png new file mode 100644 index 0000000..44f3df5 Binary files /dev/null and b/docs/Observer/Creating Proposals/polaris-tech-goals-new.png differ diff --git a/docs/Observer/Creating Proposals/polaris-tech-goals-none.png b/docs/Observer/Creating Proposals/polaris-tech-goals-none.png new file mode 100644 index 0000000..261cf11 Binary files /dev/null and b/docs/Observer/Creating Proposals/polaris-tech-goals-none.png differ diff --git a/docs/Observer/Creating Proposals/proposal_create.png b/docs/Observer/Creating Proposals/proposal_create.png deleted file mode 100644 index 4f3ebc4..0000000 Binary files a/docs/Observer/Creating Proposals/proposal_create.png and /dev/null differ diff --git a/docs/Observer/Creating Proposals/proposal_create_details.png b/docs/Observer/Creating Proposals/proposal_create_details.png deleted file mode 100644 index d26df21..0000000 Binary files a/docs/Observer/Creating Proposals/proposal_create_details.png and /dev/null differ diff --git a/docs/Observer/Creating Proposals/proposal_overview.png b/docs/Observer/Creating Proposals/proposal_overview.png deleted file mode 100644 index e174b30..0000000 Binary files a/docs/Observer/Creating Proposals/proposal_overview.png and /dev/null differ diff --git a/docs/Observer/Creating Proposals/proposal_overview_observation.png b/docs/Observer/Creating Proposals/proposal_overview_observation.png deleted file mode 100644 index 5945f7d..0000000 Binary files a/docs/Observer/Creating Proposals/proposal_overview_observation.png and /dev/null differ diff --git a/docs/Observer/Creating Proposals/targets_new.png b/docs/Observer/Creating Proposals/targets_new.png deleted file mode 100644 index 514db64..0000000 Binary files a/docs/Observer/Creating Proposals/targets_new.png and /dev/null differ diff --git a/docs/Observer/Creating Proposals/targets_none.png b/docs/Observer/Creating Proposals/targets_none.png deleted file mode 100644 index 4558403..0000000 Binary files a/docs/Observer/Creating Proposals/targets_none.png and /dev/null differ diff --git a/docs/Observer/Creating Proposals/targets_some.png b/docs/Observer/Creating Proposals/targets_some.png deleted file mode 100644 index 9c98e47..0000000 Binary files a/docs/Observer/Creating Proposals/targets_some.png and /dev/null differ diff --git a/docs/Observer/Creating Proposals/technical_goals_new.png b/docs/Observer/Creating Proposals/technical_goals_new.png deleted file mode 100644 index 1929a2c..0000000 Binary files a/docs/Observer/Creating Proposals/technical_goals_new.png and /dev/null differ diff --git a/docs/Observer/Creating Proposals/technical_goals_none.png b/docs/Observer/Creating Proposals/technical_goals_none.png deleted file mode 100644 index a4f631c..0000000 Binary files a/docs/Observer/Creating Proposals/technical_goals_none.png and /dev/null differ diff --git a/docs/Observer/Creating Proposals/technical_goals_some.png b/docs/Observer/Creating Proposals/technical_goals_some.png deleted file mode 100644 index 6d0e23d..0000000 Binary files a/docs/Observer/Creating Proposals/technical_goals_some.png and /dev/null differ diff --git a/docs/Observer/Justifications/index.md b/docs/Observer/Justifications/index.md new file mode 100644 index 0000000..5f02bba --- /dev/null +++ b/docs/Observer/Justifications/index.md @@ -0,0 +1,176 @@ +## 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](polaris-justifications.png) + +## 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](polaris-justifications-failure.png) + +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](polaris-justifications-success.png) + +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. \ No newline at end of file diff --git a/docs/Observer/Justifications/polaris-justifications-failure.png b/docs/Observer/Justifications/polaris-justifications-failure.png new file mode 100644 index 0000000..c689090 Binary files /dev/null and b/docs/Observer/Justifications/polaris-justifications-failure.png differ diff --git a/docs/Observer/Justifications/polaris-justifications-success.png b/docs/Observer/Justifications/polaris-justifications-success.png new file mode 100644 index 0000000..98d7dd8 Binary files /dev/null and b/docs/Observer/Justifications/polaris-justifications-success.png differ diff --git a/docs/Observer/Justifications/polaris-justifications.png b/docs/Observer/Justifications/polaris-justifications.png new file mode 100644 index 0000000..2f05f2b Binary files /dev/null and b/docs/Observer/Justifications/polaris-justifications.png differ diff --git a/docs/Observer/Submitting Proposals/index.md b/docs/Observer/Submitting Proposals/index.md index 152437d..db3c4c4 100644 --- a/docs/Observer/Submitting Proposals/index.md +++ b/docs/Observer/Submitting Proposals/index.md @@ -1,36 +1,93 @@ - -Please be aware that the submission functionality of Polaris is under active development such that this page -may very well be out-of-date. Please bear with us while we get around to updating this page. - -Last updated **2024-03-06** Polaris _alpha_ version. - - +Last updated **2025-10-21** Polaris _beta_ version. # Submit your Proposal -Once you are happy with the details of your **Proposal**, and it has passed the server side validation checks +Once you are happy with the details of your **Proposal**, and it has passed the server side validation checks you may submit it for review. +The proposal submission process consists of several steps. -![proposal submission ready](proposal_submission_ready.png) +## Step 1 - Select the **Proposal Cycle** +![proposal submission step 1](polaris-submit-step-1.png) -You will have to select the **Proposal Cycle** from the drop-down menu to which you wish to submit your **Proposal**. -Once selected the page will display the submission deadline for that cycle. + +Here you select the **Proposal Cycle** from the drop-down menu to which you wish to submit your **Proposal**. +Once selected click _Next step_ to continue to the next step. + +## Step 2 - Validation Check Server side validation checks currently include: -* the **Proposal** _Title_, _Summary_, and _Kind_ attributes are set (the App prevents you from leaving any of these blank) * at least one **Observation** added with at least one **Timing Window** * which requires at least one **Target** and at least one **Technical Goal** +* a successfully compiled Justification PDF + +As we develop the server side validation checks this list will grow. We expect this list to expand as we put +Polaris in to beta-testing. + +If a **Proposal** doesn't pass the validation checks then you will be presented with the following page for +_Step 2_ in the submission process, which lists the problems. + +![proposal submission not ready](polaris-submit-step-2-validation-fail.png) + + +Here we have created another proposal but haven't added any **Targets**, **Technical Goals**, or **Observations**. +Please notice that the messages are links that will take you to the relevant page in Polaris so you can address +the issues. In this case the _Next step_ button is disabled. + +A **Proposal** that does pass these validation checks will be shown the following page. + +![proposal submission ready](polaris-submit-step-2.png) + + +Again click _Next step_ to continue to step 3. + +## Step 3 - Select **Observing Modes** for your **Observations** + +![proposal submission select modes](polaris-submit-step-3.png) + + +Here you select the **Observing Modes** you want for your **Observations**. Notice that the selectable data here +depends on your choice of **Proposal Cycle**. For example, having chosen the eMerlin proposal cycle (generally +named "Cycle N", where N represents the cycle number) you can choose between _L-Band_, _C-Band_, and _K-Band_ +**Observing Modes**. You may either select a single **Observing Mode** for all the **Observations** in your +proposal, most conveniently done by selecting the mode in the _Observing Mode Details_ section and clicking +the _Set for all_ button, or select the mode for each observation separately. Once each of your **Observations** +has a mode you may proceed to step 4. + +The "eye" button in the _Observing Mode Details_ section will toggle a display of the details of the selected mode. +For example, the eMerlin modes show details of the receivers and the correlator involved, and will show which +of the telescopes will ideally be used for the observation. + +## Step 4 - Review selections before submitting + +![proposal submission review choices](polaris-submit-step-4.png) + + +This is your last chance to ensure all the details selected are correct for your proposal before you submit it +to the chosen **Proposal Cycle**. If you do need to change something then you may go _Back_ and make the desired +changes. + +Once you are happy with all the details you can click on the _Submit proposal_ button, and all being well, you +should be presented with the following screen. + +![proposal submission complete](polaris-sumbit-step-final.png) + + +You will also be sent a confirmation email outlining that you have just successfully submitted your proposal to +the cycle of choice. This email is sent to all investigators associated with the proposal. + +Clicking on _Done_ will take you back to the _Overview_ page for the proposal. + -As we develop the server side validation checks this list will grow. For example, we'd expect that a **Proposal** -must have a **Scientific Justification** and a **Technical Justification** to be valid for review. Indeed, we -expect this list to expand significantly as we put Polaris in to beta-testing. +## Withdrawing a Submitted Proposal -If a **Proposal** doesn't pass the validation checks then you will be presented with the following page for the -_Submit_ tab of your proposal, which lists the problems. +The Principal Investigator may withdraw a submitted proposal from a **Proposal Cycle** up to the submission +deadline for that cycle. The _Withdraw_ button is located on the user's homepage, one per cycle to which a proposal +has been submitted, shown in the screenshot below. -![proposal submission not ready](proposal_submission_not_ready.png) +![polaris homepage withdraw](polaris-home-page-withdraw.png) -Here we have created another proposal but haven't added any **Targets**, **Technical Goals**, or **Observations**. \ No newline at end of file +You may submit and withdraw a proposal to a particular cycle _ad nauseam_, but do try to not over do it, for your +own sake as much as anyone else's. diff --git a/docs/Observer/Submitting Proposals/polaris-home-page-withdraw.png b/docs/Observer/Submitting Proposals/polaris-home-page-withdraw.png new file mode 100644 index 0000000..04e8464 Binary files /dev/null and b/docs/Observer/Submitting Proposals/polaris-home-page-withdraw.png differ diff --git a/docs/Observer/Submitting Proposals/polaris-submit-step-1.png b/docs/Observer/Submitting Proposals/polaris-submit-step-1.png new file mode 100644 index 0000000..73dfdd5 Binary files /dev/null and b/docs/Observer/Submitting Proposals/polaris-submit-step-1.png differ diff --git a/docs/Observer/Submitting Proposals/polaris-submit-step-2-validation-fail.png b/docs/Observer/Submitting Proposals/polaris-submit-step-2-validation-fail.png new file mode 100644 index 0000000..f7bf671 Binary files /dev/null and b/docs/Observer/Submitting Proposals/polaris-submit-step-2-validation-fail.png differ diff --git a/docs/Observer/Submitting Proposals/polaris-submit-step-2.png b/docs/Observer/Submitting Proposals/polaris-submit-step-2.png new file mode 100644 index 0000000..0a275ed Binary files /dev/null and b/docs/Observer/Submitting Proposals/polaris-submit-step-2.png differ diff --git a/docs/Observer/Submitting Proposals/polaris-submit-step-3.png b/docs/Observer/Submitting Proposals/polaris-submit-step-3.png new file mode 100644 index 0000000..ad87762 Binary files /dev/null and b/docs/Observer/Submitting Proposals/polaris-submit-step-3.png differ diff --git a/docs/Observer/Submitting Proposals/polaris-submit-step-4.png b/docs/Observer/Submitting Proposals/polaris-submit-step-4.png new file mode 100644 index 0000000..d4c7e5e Binary files /dev/null and b/docs/Observer/Submitting Proposals/polaris-submit-step-4.png differ diff --git a/docs/Observer/Submitting Proposals/polaris-sumbit-step-final.png b/docs/Observer/Submitting Proposals/polaris-sumbit-step-final.png new file mode 100644 index 0000000..991d18e Binary files /dev/null and b/docs/Observer/Submitting Proposals/polaris-sumbit-step-final.png differ diff --git a/mkdocs.yml b/mkdocs.yml index f948816..80b25a6 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -7,10 +7,12 @@ nav: - Observer: - Getting Started: Observer/index.md - Creating Proposals: - - Starting : Observer/Creating Proposals/index.md + - First Steps : Observer/Creating Proposals/index.md - Adding Targets: Observer/Creating Proposals/adding-targets.md - Adding Technical Goals: Observer/Creating Proposals/adding-technical-goals.md - Building an Observation: Observer/Creating Proposals/build-observation.md + - Justifications: + - Creating and Compiling: Observer/Justifications/index.md - Submitting Proposals: - Submitting: Observer/Submitting Proposals/index.md - TAC: