Update documentation

XMMGOF · Aug 28, 2024 · 7013bce · 7013bce
1 parent 1503785
commit 7013bce
Showing 1 changed file with 40 additions and 24 deletions.
diff --git a/documentation/using_pysas.ipynb b/documentation/using_pysas.ipynb
@@ -118,7 +118,7 @@
     "w('startsas', inargs).run()\n",
     "```\n",
     "\n",
-    "inserting the desired obsID. This will download the ODF files for the Obs ID using the Python module Astroquery. The task `startsas` will also run the tasks `cifbuild` and `odfingest`. \n",
+    "The user must insert the desired obsID. This will download the ODF files for the Obs ID using the Python module astroquery. The task `startsas` will also run the tasks `cifbuild` and `odfingest`. \n",
     "\n",
     "[More details can be found in the SAS Startup Thread in Python on the main XMM website](https://www.cosmos.esa.int/web/xmm-newton/sas-thread-startup-in-python)."
    ]
@@ -150,6 +150,38 @@
     "If the ODF files have previously been downloaded and are in the default data directory, then upon creating the ODF object (i.e. \"odf = pysas.odfcontrol.ODFobject(obsid)\") pySAS will automatically find and link all important summary and calibration files, and also all previously generated event lists made by `epproc`, `emproc`, and `rgsproc`."
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "b63654d2-2d75-4d76-a5bd-89c9ffc36d78",
+   "metadata": {},
+   "source": [
+    "### Downloading Proprietary Data using the Standard Version of pySAS\n",
+    "\n",
+    "**The standard version of pySAS cannot download proprietary data!!**\n",
+    "\n",
+    "### Downloading Proprietary Data using the Development Version of pySAS\n",
+    "\n",
+    "Proprietary data can be downloaded from both the XSA and the HEASARC. How each handles proprietary data is slightly different. For the XSA proprietary data requires your Cosmos username and password. To download proprietary data from the XSA using pySAS the user creates a ODF object like normal,\n",
+    "\n",
+    "```python\n",
+    "obsid = '##########'\n",
+    "odf = pysas.odfcontrol.ODFobject(obsid)\n",
+    "```\n",
+    "Then when you run either `basic_setup` or `calibrate_odf` just indicate that the Obs ID is proprietary.\n",
+    "\n",
+    "```python\n",
+    "odf.basic_setup(proprietary=True)\n",
+    "```\n",
+    "\n",
+    "The data request is made using astroquery and astroquery will ask for the user's Cosmos username and password. The [ESA module for astroquery](https://github.com/astropy/astroquery/blob/main/astroquery/esa/xmm_newton/core.py) allows many more inputs for specifying exactly what XMM data to download. All of those inputs can be passed in as additional arguments to `basic_setup` or `calibrate_odf`. Those inputs will be passed on to astroquery.\n",
+    "\n",
+    "Proprietary data from the HEASARC comes encrypted. Anyone can download it, but you need an encryption key to unpack the data. The encryption key is a alphanumeric string with 30 characters. You provide the encryption key to either `basic_setup` or `calibrate_odf` and pySAS will handle the rest.\n",
+    "\n",
+    "```python\n",
+    "odf.basic_setup(repo='heasarc',encryption_key='XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')\n",
+    "```"
+   ]
+  },
   {
    "cell_type": "markdown",
    "id": "26356ba3-cf33-4523-b3a2-939b91badd6f",
@@ -310,14 +342,14 @@
     "The development version of pySAS allows inputs to be passed in as a Python dictionary. For example, the same list of input arguments shown above could be written like this:\n",
     "\n",
     "```python\n",
-    "inargs = {'table' : 'event_list.fits', \n",
-    "          'withfilteredset' : 'yes', \n",
-    "          'expression' : \"'(PATTERN <= 12)&&(PI in [200:4000])&&#XMMEA_EM'\", \n",
-    "          'filteredset' : 'filtered_event_list.fits', \n",
-    "          'filtertype' : 'expression', \n",
+    "inargs = {'table'            : 'event_list.fits', \n",
+    "          'withfilteredset'  : 'yes', \n",
+    "          'expression'       : \"'(PATTERN <= 12)&&(PI in [200:4000])&&#XMMEA_EM'\", \n",
+    "          'filteredset'      : 'filtered_event_list.fits', \n",
+    "          'filtertype'       : 'expression', \n",
     "          'keepfilteroutput' : 'yes', \n",
-    "          'updateexposure' : 'yes', \n",
-    "          'filterexposure' : 'yes'}\n",
+    "          'updateexposure'   : 'yes', \n",
+    "          'filterexposure'   : 'yes'}\n",
     "\n",
     "w('evselect', inargs).run()\n",
     "```\n",
@@ -359,22 +391,6 @@
     "    <b>Note:</b> At the moment it is <b>NOT</b> recommended to use the dict returned by get_input_params as the input for calling a SAS task (i.e. w('evselect', inargs).run()). Currently the way pySAS checks the validity of the inputs may cause unexpected fatal results when <b>all</b> default parameters are passed in. This is a rather complicated problem and we are working on it.\n",
     "</div>"
    ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "5a8dd9f1-6ad7-42e1-b9d6-f9db27e91feb",
-   "metadata": {},
-   "outputs": [],
-   "source": []
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "51f35976-c76b-428c-ad81-4c878f1e5e95",
-   "metadata": {},
-   "outputs": [],
-   "source": []
   }
  ],
  "metadata": {