Merge pull request #737 from rzellem/develop

v0.46.0: Updated install instructions; more robust install scripts; bugfix for AAVSO upload file

Documentation/English/EXOTIC Installation Instructions for Windows 10.md

@@ -0,0 +1,93 @@
+# EXOTIC Installation Instructions for Windows 10
+
+## Running EXOTIC
+There are two ways you can run EXOTIC: firstly through a web browser interface with a so-called Python Notebook running in Google Colab or in a Jupyter Notebook running locally on your own personal computer. 
+
+Alternatively, you can install both Python and the EXOTIC program to your own computer and run them there. The program uses a combination of a graphical front-end to enter values and a command line window where you can view progress as the program runs.
+
+Read the details of these two approaches below and select the best option for you:
+
+### Google Colab
+
+Google Colab is a free facility (available to anyone with a Google account) where you may write and run Python programs within your web browser without installing anything on your local machine. Running EXOTIC in the Google Colab is the better option for all users who are seeking a more user-friendly and interactive experience. It is especially useful for new EXOTIC users, students and those analysing data via remote observatories. 
+
+To use Google Colab to run EXOTIC follow the links on the home page of the [EXOTIC Project on GitHub](https://github.com/rzellem/EXOTIC).
+
+Once you are happy running running EXOTIC with the Colab and you want to run your own Python Notebook, please visit the instructions [‘How-to-Run-EXOTIC-with-the-Python-Notebook](https://github.com/rzellem/EXOTIC/raw/main/Documentation/English/How-to-Run-EXOTIC-with-the-Python-Notebook.pdf)’ in the [Documentation folder](https://github.com/rzellem/EXOTIC/tree/main/Documentation) on GitHub.
+
+*Note: in order to be able to click on the links and select text in this PDF document, you must download it from GitHub. The GitHub preview simply shows you an image of the document, which does not allow for those functions.*
+
+### GUI Version of EXOTIC for Windows
+
+Early versions of EXOTIC had to be run wholly on the "command line" whereby responses to the prompts from the program had to be typed in line by line as the program ran each step. EXOTIC itself still runs in a command line window but you can now enter your choices for the various program options via a series of pop up screens before commencing the data-reduction run.
+
+## Installing EXOTIC for Windows
+
+1. #### Install Python for Windows 10 
+
+If you do not already have a copy of the latest version of Python software on your computer, then you will need to install it before you can run EXOTIC. Even if you have an older copy of Python then do install another copy to get the latest release, which is needed to run EXOTIC.
+
+Go to the [Python Releases for Windows](https://www.python.org/downloads/windows/) page on the Python website, where you will find the download files for Windows. Look at the list of "Stable Releases" and take the link to the most recent release of Python towards the top of that list. At the time of writing this was Python 3.9.5 - but it may be a later release for you. 
+
+If you have a modern computer (i.e. one running the 64-bit version of Windows) then choose the "Windows Installer (64-bit )" link, otherwise if you are using an older machine you can use the "Windows Installer (32-bit )" version.
+
+Right click to download and save the EXE file to your computer and double click it to start the installation process. 
+
+- Choose the "Modify" option on the "Modify Setup" screen that pops up first. 
+- On the next "Optional Features" screen, make sure that the boxes for "pip" and for "py launcher" are ticked then click "Next". 
+- On the "Advanced Options" screen make sure that the boxes "Associate files with Python", "Create shortcuts for installed applications" and "Add Python to environment variables" are all ticked before clicking "Install". 
+- Do not change the default install location or you may run into problems later on when using EXOTIC.
+
+*Note: You can install Python direct from the Microsoft store, where you will find a recent copy of Python but we advise against this approach. Although this will install the program like any other windows software, it will not be installed in a similar way to the Python installed on other systems that do not run Windows. EXOTIC runs on many platforms, including Linux as well as Windows, and expects to find a similar set up on all of them to run without problems.*
+
+2. #### Downloading EXOTIC and supporting files
+
+Go to the home page of the [EXOTIC project](https://pypi.org/project/exotic/) at the Python Package Index (PyPI). This site hosts many major Python projects for a variety of computer platforms, including both Linux and Windows machines. Here you will find links to all aspects of the EXOTIC project including the documentation and the software itself. Follow the "Homepage" link in the left hand margin that will take you to the [EXOTIC home page on GitHub](https://github.com/rzellem/EXOTIC), where the software for the project is developed. 
+
+Click the "Releases" link in the right hand margin of the EXOTIC home page on GitHub. On the next page you will find a series of releases of EXOTIC, each with a header outlining the key change for that version. The most recent version of EXOTIC (labelled "Latest release" in the left hand margin) is shown at the top. Go to the "Assets" section to get a copy of the latest release and right click the "Source code (zip)" link to download the compressed file. This file will be named "EXOTIC" followed by the release number e.g. "EXOTIC-0.45.3.zip". Save the file to the usual folder on your computer where your browser stores downloaded  files. 
+
+Go to that downloads folder and right click the zip file that you have just saved and choose the "Extract All..." option. In the window that pops up, choose where to install the EXOTIC files, make sure the "Show extracted files when complete" box is ticked and click "Extract". After extraction, a new window will open up showing the folder where the files are located, named after the version of the EXOTIC program (e.g. EXOTIC-0.45.3). 
+
+3. #### Installing EXOTIC
+
+In the file manager window that has just appeared, open the EXOTIC program folder to find the batch file named "run_exotic_windows.bat". You may find that there is just another folder named after the EXOTIC version inside the first folder, in which case open this as well. Having found it, double click the batch file to start the installation process.
+
+You may see a warning window popping up from Microsoft Defender reading: 
+
+###### *Windows Protected your PC* 
+
+*Microsoft Defender SmartScreen prevented an unrecognised app from starting. Running this app might put your PC at risk.*
+
+*Application: run_exotic_windows.bat* 
+*Publisher:  Unknown publisher* 
+
+If so you need not worry, this is just a precaution from Microsoft when it does not know the details of the origin of software, so on this occasion you can safely ignore the message and click "Run anyway"
+
+A Windows command line window with a black background will then open up, showing you the progress of the installation for each of the files required to run EXOTIC. This process may take some time and you will see many lines of yellow and white text scroll by until the whole installation is finished. Do not worry when the process pauses on a line starting with "Building wheel for ...", since each of these steps will take some time. 
+
+The final stage, beginning "Installing collected packages:..." followed by a long list of packages, will take several minutes to run and the screen will not change at all during this time - please be patient and just wait for the installation to complete on its own.
+
+When the script completes, a new command line window in black appears that will show the progress of the data-reduction once EXOTIC is running. In front of this you will see the EXOTIC GUI window showing "Welcome to EXOTIC!" plus the version of EXOTIC you are running and other details. This GUI window is used to enter the values required to define how the data-reduction run will be performed.
+
+You can move each window around separately to see what is happening in each of them.
+
+## Running EXOTIC next time
+
+To run the EXOTIC program in the future, simply click locate and run the "run_exotic_windows.bat" file again. This will firstly check whether any EXOTIC files need updating and update them automatically if there has been another release of the software. In this case you will see the same installation process as outlined above, though it will run very much faster, as most files will not have changed between releases. 
+
+After the installation of any new or updated EXOTIC components has completed (or is skipped through if nothing has changed) the program will run as before...
+
+## Install DS9 (Astronomical Image Viewing Software)
+
+After installing EXOTIC itself, you may wish to install the SAOImageDS9 (Astronomical Image Viewing Software) to view the “.FITS” images you obtain during observations. For more information on SAOImageDS9, check out the [User Guide](http://ds9.si.edu/doc/user/index.html)
+
+
+- Follow [SAOImageDS9 download link](https://sites.google.com/cfa.harvard.edu/saoimageds9/download)
+- Click on "***Windows***" then select "***Windows 64 bit***".
+- Run the Windows installer in the usual way once the file has been downloaded.
+- Follow the instructions in the installer to complete the installation.
+
+## Further Help and Support
+
+If you have any questions or comments, please feel free to reach out to us on Slack or email at [[email protected]]([email protected])
+

Documentation/README.md

@@ -1,3 +1,11 @@
+- [Installation and Running](#installation-and-running)
+- [Requirements](#requirements)
+- [Sample Data and Outputs](#sample-data-and-outputs)
+- [How to Run EXOTIC with the Sample Data Locally on your Computer](#how-to-run-exotic-with-the-sample-data-locally-on-your-computer)
+- [If you run into any issues with EXOTIC](#if-you-run-into-any-issues-with-exotic)
+- [Initializaton File](#initializaton-file)
+
+
 ## Installation and Running
 
 EXOTIC can run on a Windows, Macintosh, or Linux/Unix computer. You can also use EXOTIC via the free Google Colab, which features cloud computing, many helpful plotting functions, and a simplified installation. However, if you are a user with many images or large images, we recommend running EXOTIC locally on your own computer.
@@ -42,7 +50,7 @@ FITS files with a modern header including parameters for UT time, exposure time,
 ## Sample Data and Outputs
 We provide a [sample dataset](https://github.com/rzellem/EXOTIC_sampledata) consisting of 142 `fits` files taken by a 6” telescope of the exoplanet HAT-P-32 b (V-mag = 11.44) observed on December 20, 2017. The telescope used to collect this dataset is part of the [MicroObservatory Robotic Telescope Network](http://microobservatory.org) operated by the Harvard-Smithsonian Center for Astrophysics.
 
-[Sample Data](https://github.com/rzellem/EXOTIC_sampledata)
+[Sample Data](https://github.com/rzellem/EXOTIC_sampledata/releases/)
 
 A lightcurve from the sample dataset is shown below:
 
@@ -62,8 +70,88 @@ FINAL PLANETARY PARAMETERS
 The scatter in the residuals of the lightcurve fit is: 0.5414 %
 
 *********************************************************
+
 ```
 
+## How to Run EXOTIC with the Sample Data Locally on your Computer
+1. Download the [Sample Data](https://github.com/rzellem/EXOTIC_sampledata/releases/) and unzip the file.
+
+2. Launch EXOTIC by double-clicking on the appropriate installer for your operating system:
+      - Windows: run_exotic_windows.bat
+      - Macintosh: run_exotic_macintosh.command
+      - Linux: run_exotic_linux.sh
+
+3. A new loading screen will pop up where you will see many required packages being automatically installed and updated. If this is your first time running the code, this can take up to a few minutes, depending on your internet connection.
+
+![EXOTIC Loading Screen](https://github.com/rzellem/EXOTIC/blob/develop/Documentation/Images/exotic_loading.png)
+
+4. After EXOTIC finishes loading, you will see a welcome screen. Click Next to proceed.
+
+  ![EXOTIC Welcome Screen](https://github.com/rzellem/EXOTIC/blob/develop/Documentation/Images/exotic_welcome.png)
+
+5. Select how you want to use EXOTIC - either in "Real Time Reduction" (for quickly analyzing your data while simulatenously observing) or in "Complete Reduction" (for analyzing your data after an observing run). Since we already have our sample data on our computer harddrive, we will select "Complete Reduction" and click Next.
+
+![EXOTIC Reduction Mode](https://github.com/rzellem/EXOTIC/blob/develop/Documentation/Images/exotic_redmode.png)
+
+6. Select how you want to run EXOTIC: either by starting with raw image files (typically in FITS format or similar) or by starting with pre-reduced data (i.e., data already reduced with other software). Since we want to fully analyze our sample data, which are image files, we will select "Analyze your image files" and click Next.
+
+![EXOTIC Ru Mode](https://github.com/rzellem/EXOTIC/blob/develop/Documentation/Images/exotic_runmode.png)
+
+7. Select how you would like to enter information about your observing run (e.g., location, sky conditions, position of the target and comparison star(s) on the detector, etc.). For our sample data run, select "Manually".
+
+![EXOTIC Input Observation Information](https://github.com/rzellem/EXOTIC/blob/develop/Documentation/Images/exotic_inputobsinfo.png)
+
+8. Now enter the information about your observing run.
+    - Folder with your FITS files - the folder that contains your image files from your observation run; typically, this is a file called "Downloads"
+    - Folder to save EXOTIC output - select where you want EXOTIC to write your output, such as final lightcurves and the file you can upload directly to the AAVSO Exoplanet Database
+    - Please enter your calibration file information - enter the location of your flats, darks, and biases
+        - NOTE: these three calibrations should be in DIFFERENT/SEPARATE folders and should *not* be in the same folder as your observation data
+        - If you do not have any of these calibrations, enter `null`
+    - AAVSO Observer Code - if you do not have one, leave as N/A
+    - Secondary Observer Codes - the AAVSO observer codes of anyone who helped out with your observations; if you do not have one, leave as N/A
+    - Observation date - the date of your observation in DAY-MONTH-YEAR format
+    - Obs. Latitude - the latitude of your observations, where North is denoted with a + and South is denoted with a -
+    - Obs. Longitude - the longitude of your observations, where East is denoted with a + and West is denoted with a -
+    - Obs. Elevation - the elevation of your observations in meters; note: if you do not know your elevation, leave this value as 0 and EXOTIC will look it up for you!
+    - Camera Type - the type of camera you are using (typically, CCD, DSLR, or CMOS)
+    - Pixel Binning - the binning of your pixels; if you do not bin your pixels, then please enter 1x1
+    - Pixel Scale - how large each pixel is in units of arcseconds per pixel; if you do not know your pixel scale, please enter null and EXOTIC will calculate it for you
+    - Filter - select the filter that you used for your observations; if you used a custom filter, please select "N/A" and EXOTIC will ask you for your filter specifics later; if you did not use a filter, please select either select "N/A" and then you will be prompted for wavelength information later or select the filter that most closely corresponds to your camera
+    - Observing Notes - enter notes about your observing run, such as weather conditions
+    - Plate solve my images - select if you want EXOTIC to calibrate the right ascenscion and declination of your pixels in your image via Astrometry.net; it is recommended that this option is selected
+    - Align my images - select this option for EXOTIC to align all of your images to provide better tracking of your stars in your images; it is recommended that this option is selected
+    - Target Star X & Y Pixel Position - the pixel location of your target exoplanet host star in [x-position, y-position] format
+    - Comparison Star(s) X & Y Pixel Position - the pixel location of your comparision star(s) in [x-position, y-position] format; it is recommended that you input at least 2 comparision stars and EXOTIC will automatically select the "best" comparision by the one that produces the least amount of scatter in your data
+    - *NOTE:* In the screenshot below, Rob has already entered all of the information for you for the sample data (with the exception that you'll need to point to the correct directory for your FITS files and your EXOTIC Output)
+
+    ![EXOTIC Input Observation Information](https://github.com/rzellem/EXOTIC/blob/develop/Documentation/Images/exotic_inputobs.png)
+
+9. Select how you want to enter your planetary system parameters. For first-time users, it is recommended that you enter these "Manually". Advanced users might want to simply adopt all planetary parameters from the NASA Exoplanet Archive. If you have already input your parameters in a pre-existing initialization file, then please select the last option.
+
+![EXOTIC Input Planetary Parameters](https://github.com/rzellem/EXOTIC/blob/develop/Documentation/Images/exotic_inputplanetparams.png)
+
+10. Enter the planetary parameters for your exoplanetary system. You can find this information on a variety of resources, but we recommend you look up your planet on the [NASA Exoplanet Archive](https://exoplanetarchive.ipac.caltech.edu). Note to users who are reducing the sample HAT-P-32b dataset- Rob has already filled out the system parameters for HAT-P-32b.
+
+![EXOTIC Input Planetary Parameters](https://github.com/rzellem/EXOTIC/blob/develop/Documentation/Images/exotic_planetparams.png)
+
+11. EXOTIC will now create an initialization file for you. This file essentially saves all of the answers to the questions and prompts you just filled out- that way, you can just bypass all of these questions the next time you reduce these observations by simply loading in this initialization file. Please select the location on your harddrive where you want to save this file. It will be then named as `inits_MM_DD_YYYY__HH_MM_SS.json` where MM-DD-YYYY is the month, day, and year and HH_MM_SS is the current time.
+
+![EXOTIC Save Initialization File](https://github.com/rzellem/EXOTIC/blob/develop/Documentation/Images/exotic_saveinits.png)
+
+12. Congratulations! EXOTIC has successfully saved your initialization file! Click "Run EXOTIC" to launch EXOTIC and start analyzing the sample data!
+
+![EXOTIC Initialization File Saved](https://github.com/rzellem/EXOTIC/blob/develop/Documentation/Images/exotic_initssaved.png)
+
+13. EXOTIC is now running!
+
+![EXOTIC is now Running! Saved](https://github.com/rzellem/EXOTIC/blob/develop/Documentation/Images/exotic_running.png)
+
+## If you run into any issues with EXOTIC
+- Please send a message on our Slack Workspace on the #data-reduction channel to get help from the Exoplanet Watch Community. You can sign up for your own free Slack account by clicking on [this link](https://join.slack.com/t/uol-ets/shared_invite/zt-mvb4ljbo-LRBgpk3uMmUokbs4ge2JlA).
+
+- Alternatively, you can email the Exoplanet Watch team directly at [email protected].
+
+
 ## Initializaton File
 
 Get EXOTIC up and running faster with a json file. Please see the included file ([inits.json](inits.json)) meant for the [sample data](https://github.com/rzellem/EXOTIC_sampledata). The initialization file has the following fields: