{"id":22215704,"url":"https://github.com/jobovy/apogee","last_synced_at":"2025-10-02T18:31:35.920Z","repository":{"id":11805027,"uuid":"14352237","full_name":"jobovy/apogee","owner":"jobovy","description":"Tools for dealing with APOGEE data","archived":false,"fork":false,"pushed_at":"2025-01-08T16:23:56.000Z","size":5949,"stargazers_count":42,"open_issues_count":1,"forks_count":25,"subscribers_count":10,"default_branch":"main","last_synced_at":"2025-01-08T17:41:16.982Z","etag":null,"topics":["astronomy","astrophysics","data","data-analysis","python","spectroscopy"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jobovy.png","metadata":{"files":{"readme":"README.rst","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2013-11-13T03:03:50.000Z","updated_at":"2025-01-08T16:24:00.000Z","dependencies_parsed_at":"2023-01-11T20:17:07.058Z","dependency_job_id":"e94cea21-2c07-43cf-8f4e-34a033d0ef2a","html_url":"https://github.com/jobovy/apogee","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jobovy%2Fapogee","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jobovy%2Fapogee/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jobovy%2Fapogee/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jobovy%2Fapogee/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jobovy","download_url":"https://codeload.github.com/jobovy/apogee/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":235033799,"owners_count":18925499,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["astronomy","astrophysics","data","data-analysis","python","spectroscopy"],"created_at":"2024-12-02T21:42:30.299Z","updated_at":"2025-10-02T18:31:35.154Z","avatar_url":"https://github.com/jobovy.png","language":"Python","funding_links":[],"categories":["Uncategorized"],"sub_categories":["Uncategorized"],"readme":"apogee\n-------\n\nTools for dealing with `SDSS-III \u003chttp://sdss3.org/\u003e`__ `APOGEE\n\u003chttp://www.sdss3.org/surveys/apogee.php\u003e`__ and `SDSS-IV\n\u003chttp://sdss.org/\u003e`__ `APOGEE-2\n\u003chttp://www.sdss.org/surveys/apogee-2/\u003e`__ data.\n\n**PLEASE NOTE THAT THIS REPOSITORY IS NO LONGER ACTIVELY MAINTAINED AS OF 01/01/2025**\n\n.. contents::\n\nAUTHOR\n======\n\nMain author: Jo Bovy - bovy at astro dot utoronto dot ca\n\nSubstantial contributions from\n\n* Ted Mackereth (`@jmackereth \u003chttps://github.com/jmackereth\u003e`__)\n* Natalie Price-Jones (`@npricejones \u003chttps://github.com/npricejones\u003e`__)\n* Meredith Rawls (`@mrawls \u003chttps://github.com/mrawls\u003e`__)\n\nCITING THIS CODE\n=================\n\nPlease cite `Bovy (2016) \u003chttp://arxiv.org/abs/1510.06745\u003e`__ when\nusing this code. Appendix C of this paper has a brief overview of the\ncode. When using the selection function, please cite `Bovy et\nal. (2014) \u003chttp://adsabs.harvard.edu/abs/2014ApJ...790..127B\u003e`__ and\nwhen using the DR14 selection function please cite `Mackereth \u0026 Bovy\n(2020) \u003chttps://ui.adsabs.harvard.edu/abs/2019arXiv191003590M\u003e`__ as\nwell. When using the effective selection function, please cite `Bovy\net al. (2016a) \u003chttp://arxiv.org/abs/1509.06751\u003e`__ and/or `Bovy et\nal. (2016b) \u003chttp://arxiv.org/abs/1509.05796\u003e`__.\n\nINSTALLATION\n============\n\nStandard python setup.py build/install\n\nEither\n\n``sudo python setup.py install``\n\nor \n\n``python setup.py install --prefix=/some/directory/``\n\n\nInstalling FERRE\n^^^^^^^^^^^^^^^^^\n\nThe installation can also automatically install Carlos Allende Prieto's `FERRE \u003chttp://leda.as.utexas.edu/ferre/\u003e`__ code. To do this do\n\n``python setup.py install --install-ferre``\n\nOn a Mac, you might have issues with OpenMP, which can be disabled\nusing ``--ferre-noopenmp``. The installation will also automatically\nchange FERRE's default filename-length from 120 to 180, to deal with\nthe long filenames for the model libraries on the SDSS SAS (which is\nmirrored locally to use this code). If you want to use a different\nfilename-length you can specify, for example, ``--ferre-flen 200`` for\na length of 200 characters.\n\nIf you have already installed FERRE yourself, you should alias the\nFERRE binary to ``ferre`` and FERRE's ascii2bin to ``ascii2bin`` to\nuse FERRE within this package.\n\nInstalling MOOG and Turbospectrum\n^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n\nThis package can also use `MOOG\n\u003chttp://www.as.utexas.edu/~chris/moog.html\u003e`__ and `Turbospectrum\n\u003chttp://www.pages-perso-bertrand-plez.univ-montp2.fr/\u003e`__. They are,\nhowever, not installed by this package's installer. You can install\nMOOG from the source given on the MOOG `website\n\u003chttp://www.as.utexas.edu/~chris/moog.html\u003e`__, or you can use\n`@andycasey \u003chttps://github.com/andycasey\u003e`__'s `MOOG installer\n\u003chttps://github.com/andycasey/moog\u003e`__ (updated to the July 2014\nrelease of MOOG in the `batch.2014jul\n\u003chttps://github.com/andycasey/moog/tree/batch.2014jul\u003e`__ branch). You\ncan install this by cloning the ``moog`` repository, checking out the ``batch.2014jul`` branch, and running the installation::\n\n    git clone https://github.com/andycasey/moog.git\n    cd moog\n    git checkout batch.2014jul\n    python setup.py install\n\nSee the `MOOG installer \u003chttps://github.com/andycasey/moog\u003e`__ webpage\nfor more info on the installation and its issues.\n\nTurbospectrum v15.1 can be downloaded from Betrand Plez' `website\n\u003chttp://www.pages-perso-bertrand-plez.univ-montp2.fr/\u003e`__. To use\nTurbospectrum with the ``apogee`` package, please define an\nenvironment variable $TURBODATA that points to Turbospectrum's DATA\ndirectory and make sure that the *babsma_lu* and *bsyn_lu* commands\nare directly callable (by, for example, copying them to\n/usr/local/bin). Here is an example installation::\n\n\t\t wget http://www.pages-perso-bertrand-plez.univ-montp2.fr/DATA/Turbospectrum-v15.1.tar.gz\n\t\t tar xvzf Turbospectrum-v15.1.tar.gz \u0026\u0026 cd EXPORT-15.1/exec-gf-v15.1\n\t\t make\n\t\t sudo cp babsma_lu /usr/local/bin \u0026\u0026 sudo chmod u+x /usr/local/bin/babsma_lu\n\t\t sudo cp bsyn_lu /usr/local/bin \u0026\u0026 sudo chmod u+x /usr/local/bin/bsyn_lu\n\t\t cd ../ \u0026\u0026 export TURBODATA=$PWD/DATA\n\nDEPENDENCIES AND PYTHON VERSIONS\n=================================\n\nThis package requires the Python packages `NumPy\n\u003chttp://numpy.scipy.org/\u003e`__, `Scipy \u003chttp://www.scipy.org/\u003e`__,\n`Matplotlib \u003chttp://matplotlib.sourceforge.net/\u003e`__, `tqdm\n\u003chttp://github.com/tqdm/tqdm\u003e`__, `astropy\n\u003chttps://github.com/astropy/astropy\u003e`__, `esutil\n\u003chttp://code.google.com/p/esutil/\u003e`__, `galpy\n\u003chttp://github.com/jobovy/galpy\u003e`__, `isodist\n\u003chttp://github.com/jobovy/isodist\u003e`__, and `periodictable\n\u003chttps://pypi.python.org/pypi/periodictable\u003e`__. Because `esutil\n\u003chttp://code.google.com/p/esutil/\u003e`__ does not currently support\npython 3, it is not listed as a dependency in the ``setup.py`` file\nand must be installed separately; if ``esutil`` is not installed, some\nfunctionality in ``apogee.tools.read`` is lost for which warnings are\nissued. With standard installation, astropy is used to read FITS files. Installing `fitsio \u003chttp://github.com/esheldon/fitsio\u003e`__ will cause those routines to take precedence over `astropy\n\u003chttp://docs.astropy.org/en/stable/io/fits/index.html\u003e`__.\n\nThe ``apogee`` package should work both in python 2 and 3 (thanks to\n`@mrawls \u003chttps://github.com/mrawls\u003e`__ for adding python 3\ncompatibility). Please open an `issue\n\u003chttps://github.com/jobovy/apogee/issues\u003e`__ if you find a part of the\ncode that does not support python 3.\n\nTo use the download functionalities (see below), you also need to have\n``wget`` installed on your system.\n\nDATA FILES AND ENVIRONMENT VARIABLES\n=====================================\n\nThis code depends on a number of data files and environment\nvariables. The environment variables are (**WARNING: THESE HAVE\nRECENTLY CHANGED TO BE MORE CONSISTENT WITH SDSS' OWN ENVIRONMENT\nVARIABLES**)\n\n* **SDSS_LOCAL_SAS_MIRROR**: top-level directory that will be used to (selectively) mirror the SDSS SAS\n* **RESULTS_VERS**: APOGEE reduction version (e.g., v304 for DR10, v402 for DR11, v603 for DR12, l30e.2 for DR13, l31c.2 for DR14, l33 for DR16, dr17 for DR17); note that you can set and change the DR on the fly using the function ``change_dr`` in ``apogee.tools.path`` (also available in ``apogee.tools.read`` for convenience).\n* **APOGEE_APOKASC_REDUX**: APOKASC catalog version (e.g., v6.2a); note that this does not load the public catalog and is only for internal SDSS use.\n\nIn order to use this code, you will need to set these environment variables\non your machine with commands like `export SDSS_LOCAL_SAS_MIRROR=\"/desired/path/to/SDSS/data\"`\nwhich can be saved in `~/.bashrc` or a similar file.\n\n**NEW**: Data files mirror the SDSS SAS as much as possible\n(previously, many data files lived in the $SDSS_LOCAL_SAS_MIRROR\ndirectory, then known as the $APOGEE_DATA directory). Some files still\nlive directly under the $SDSS_LOCAL_SAS_MIRROR directory (for example,\nAPOKASC_Catalog.APOGEE_$APOKASC_REDUX.fits). Files related to the\nspectra and the target selection live in sub-directories\n**drXX/**. These sub-directories mirror the directory structure of\nspectra- and targeting-related files on the SDSS-III `SAS\n\u003chttp://data.sdss3.org/sas/dr12/apogee\u003e`__:\n\n* **$SDSS_LOCAL_SAS_MIRROR/dr12/apogee/target/**\n\nwith sub-directories in that last *target/* directory\n\n* **apogee_DR12**\n\nThese directories contain the apogeeDesign_DR12.fits,\napogeeField_DR12.fits, apogeePlate_DR12.fits, and\napogeeObject_DR12-FIELDNAME.fits files (for DR10/DR11 there are\nsimilar directories).\n\nFor the target selection code to work, the allStar-$RESULTS_VERS.fits,\nallVisit-$RESULTS_VERS.fits files need to be present, as well as the\ntargeting files in the *drXX/* directories. The observation log\nobs-summary-year1+2.csv (for DR11) or obs-summary-year1+2+3.csv (for\nDR12) also needs to be present. These are available `here\n\u003chttps://zenodo.org/record/17300\u003e`__ and they will be automagically\ndownloaded by the code when they are needed.\n\nFiles of individual spectra live in directories that mirror the SAS as\nwell:\n\n* **$SDSS_LOCAL_SAS_MIRROR/dr12/apogee/spectra/**\n\nRoutines in the *apogee.tools.path* module keep track of all of the\npaths to the different files. A typical tree looks something like::\n\n      $SDSS_LOCAL_SAS_MIRROR/\n\tdr12/\n\t\tapogee/\n\t\t\tspectro/\n\t\t\t\tredux/r5/stars/\n\t\t\t\t\tapo25m/\n\t\t\t\t\t\t4102/\n\t\t\t\t\t\t\tapStar-r5-2M21353892+4229507.fits\n\t\t\t\t\t\t\t...\n\t\t\t\t\t\t...\n\t\t\t\t\tapo1m/\n\t\t\t\t\t\thip/\n\t\t\t\t\t\t\tapStar-r5-2M00003088+5933348.fits\n\t\t\t\t\t\t\t...\n\t\t\t\t\t\t...\n\t\t\t\t\tl25_6d/v603/\n\t\t\t\t\t\tallStar-v603.fits\n\t\t\t\t\t\tallVisit-v603.fits\n\t\t\t\t\t\t4102/\n\t\t\t\t\t\t\taspcapStar-r5-v603-2M21353892+4229507.fits\n\t\t\t\t\t\t\t...\n\t\t\t\t\t\t...\n\t\t\ttarget/\n\t\t\t\tapogee_DR12/\n\t\t\t\t\tapogeeDesign.fits\n\t\t\t\t\tapogeeField.fits\n\t\t\t\t\tapogeeObject_000+02.fits\n\t\t\t\t\t...\n\t\t\t\t\tapogeePlate.fits\n\t\t\tvac/\n\t\t\t\tapogee-rc/cat/\n\t\t\t\t\tapogee-rc-DR12.fits\n\t\t\t\t\t...\n\tdr10/\n\t   *similar to dr12/*\n\n**The apogee package will automatically attempt to download most of\nthe data files, so provided you have setup SDSS_LOCAL_SAS_MIRROR and\nRESULTS_VERS, you will not have to download data files yourself to get\nstarted.** If you have access to proprietary data, you have to setup a\n.netrc file with the correct login credentials (see `here\n\u003chttps://trac.sdss3.org/wiki/Software/NetRc\u003e`__). Please let me know\nif there are files that you would like to have added to the automatic\ndownloading.\n\nBASIC USE\n==========\n\nFile reading\n^^^^^^^^^^^^^\n\nThe most basic capability of the code is to read various data produces\nand apply cuts (in *apogee.tools.read*). For example::\n\n   import apogee.tools.read as apread\n   allStar= apread.allStar(rmcommissioning=True,main=False,ak=True, akvers='targ',adddist=False)\n\nwill read the allStar file corresponding to the $RESULTS_VERS version,\nremove stars only observed on commissioning plates\n(*rmcommissioning=True*), only keep stars with a valid extinction\nestimate (*ak=True*), and use the original extinction estimate used to\ndefine the targeting sample (*akvers='targ'*). The output\nnumpy.recarray has additional tags containing the extinction-corrected\n*J*, *H*, and *K*\\ :sub:`s` magnitudes.\n\nThe *allStar* read function also has an option *rmdups=True* (default:\nFalse) that removes a small number of duplicates in the allStar file\n(these are mainly commissioning stars re-observed during the main\nsurvey and a few stars in overlapping fields). The first time this\noption is used the read function may take about 10 minutes to remove\nall duplicates, but the duplicate-free file is then cached for\nre-use. Use as::\n\n\tallStar= apread.allStar(rmcommissioning=True,rmdups=True)\n\nIf you are using DR14 and want to use the (less noisy) parameters and\nabundances derived using the `astroNN\n\u003chttps://github.com/henrysky/astroNN_spectra_paper_figures\u003e`__ method\nof `Leung \u0026 Bovy (2019a) \u003chttps://arxiv.org/abs/1808.04428\u003e`__, the\ndistances to APOGEE stars determined using a neural-network approach\ntrained on Gaia by Leung \u0026 Bovy (2019b; in prep.), and the ages from\n`Mackereth, Bovy, Leung, et al. (2019)\n\u003chttp://arxiv.org/abs/1901.04502\u003e`__ do::\n\n   allStar= apread.allStar(use_astroNN=True)\n\nwhich can also be combined with any other ``allStar`` option. The\n``astroNN`` results are swapped in for the regular ASPCAP results, so\nswitching between the two is as simple as changing the read of the\nfile. The recommended distances are ``weighted_dist`` (pc) and the\nages are ``astroNN_age``.  You can load only the astroNN abundances,\nonly the distances, or only the ages using ``use_astroNN_abundances``,\n``use_astroNN_distances``, and ``use_astroNN_ages``, respectively.\n\nWe can read the red-clump catalog from `Bovy et al. (2014) \u003chttp://adsabs.harvard.edu/abs/2014ApJ...790..127B\u003e`__  using (any of its releases)::\n\n   aporc= apread.rcsample()\n\nThis can also take the ``use_astroNN=True`` option to swap in the astroNN parameters and abundances.\n\nWe can also read spectra as follows::\n\n   spec, hdr= apread.apStar(4102,'2M21353892+4229507',ext=1)\n\nwhere the first argument is the location ID and the second argument is\nthe APOGEE ID. This reads the first extension of the `apStar\n\u003chttp://data.sdss3.org/datamodel/files/APOGEE_REDUX/APRED_VERS/APSTAR_VERS/TELESCOPE/LOCATION_ID/apStar.html\u003e`_\nfile; the header is also returned (set ``header=False`` to not read\nthe header). Similarly, we can read pseudo-continuum-normalized\nspectra as::\n\n\tspec, hdr= apread.aspcapStar(4102,'2M21382701+4221097',ext=1)\n\nFor objects observed with the NMSU 1m telescope (those with\n``TELESCOPE`` tag set to ``apo1m``), we need to specify the ``FIELD``\nrather than the location ID. That is, do for example::\n\n       spec, hdr= apread.apStar('hip','2M00003088+5933348',ext=1)\n\nand::\n\n\tspec, hdr= apread.aspcapStar('hip','2M00003088+5933348',ext=1)\n\nThe ``FIELD`` can be directly fed from the allStar entry (whitespace\nwill be automatically removed).\n\nSpectra will also be automatically downloaded if they are not\navailable locally. Module **apogee.tools.read** also contains routines\nto read the various targeting-related files (see above). These are\n*not* automatically downloaded at this point. \n\nYou can set and change the DR on the fly using the function\n``change_dr`` in ``apogee.tools.path``. Many (but not all) functions\nallow a ``dr=`` keyword that allows one to specify the data release,\nbut using ``change_dr`` allows you to change the data release without\nhaving to specify it for every function (and also allows you to change\nit for functions that do not support the ``dr=`` keyword).\n\nWe can also read individual apVisit files, provided the plate ID, MJD, and fiber are known.\nOtherwise, it functions similarly to how you would read in an apStar file. If you are interested\nin a particular target and don't know the plate ID, MJD, and fiber *a priori*, the `SDSS Science\nArchive Server (SAS) \u003chttps://dr14.sdss.org/infrared/spectrum/search\u003e`__\nfor your DR of choice can be of great use. At present, up to DR14 is supported.\n\nNote that apVisit data is **not** on the standard apogee wavelength grid, and `ext=4` must be used to\nretrieve the wavelength data that corresponds with the fluxes. An example::\n\n    import apogee.tools.read as apread\n    plateId = 7439\n    mjd = 56763\n    fiberId = 207\n    spec = apread.apVisit(plateId, mjd, fiberId, ext=1)\n    specerr = apread.apVisit(plateId, mjd, fiberId, ext=2)\n    wave = apread.apVisit(plateId, mjd, fiberId, ext=4)\n    header = apread.apVisit(plateId, mjd, fiberId, ext=0, header=True)\n    \nNote that you may access either data **OR** header information with a single call\nto `apread.apVisit`. Take care when specifying which FITS extension you want.\n\nIf you wish to continuum normalize an apVisit spectrum, you can! The procedure is slightly different\nfrom normalizing a series of apStar spectra (see the section on \"The APOGEE LSF and continuum normalization\"\nbelow if you are working with apStar files). Most notably, `continuum.fitApvisit` takes only one spectrum\nat a time::\n\n    from apogee.spec import continuum\n    cont = continuum.fitApvisit(spec, specerr, wave)\n    specnorm = spec/cont\n\nUse regular matplotlib commands to view the result rather than the specialized plotting tools in this \nmodule, because the latter is built with an underlying assumption of the standard apStar wavelength grid.\nFor example::\n\n    import matplotlib.pyplot as plt\n    plt.plot(wave, spec)\n    plt.plot(wave, cont, lw=2, color='r')\n    plt.show()\n    plt.plot(wave, specnorm)\n    plt.show()\n\n\nBitmasks\n^^^^^^^^^\n\nThe module **apogee.tools.bitmask** has some tools for dealing with APOGEE\nbitmasks. In particular, it has methods to turn a numerical bit value\ninto the string name of the bit::\n\n     from apogee.tools import bitmask\n     bitmask.apogee_target1_string(11)\n     'APOGEE_SHORT'\n     bitmask.apogee_target2_string(9)\n     'APOGEE_TELLURIC'\n\nOr we can find the numerical bit value for a given string name::\n\n   bitmask.apogee_target1_int('APOGEE_SHORT')\n   11\n   bitmask.apogee_target2_int('APOGEE_TELLURIC')\n   9\n\nThere are also tools to figure out which bits are set for a given\nbitmask from the catalog and to test whether a given bit is set::\n\n\tbitmask.bits_set(-2147481584)\n\t[4, 11, 31]\n\tbitmask.bit_set(1,-2147481584)\n\tFalse\n\tbitmask.bit_set(bitmask.apogee_target2_int('APOGEE_TELLURIC'),-2147481584)\n\nThe final command run on an array of bitmasks will return a boolean\nindex array of entries for which this bit is set. For example, to get\nthe tellucircs in the allStar file do::\n\n    telluricsIndx= bitmask.bit_set(bitmask.apogee_target2_int('APOGEE_TELLURIC'),allStar['APOGEE_TARGET2'])\n\nor shorter::\n\n    telluricsIndx= bitmask.bit_set(9,allStar['APOGEE_TARGET2'])\n\n\nIf you want a quick reminder of what the various bits are, just\ndisplay the bitmask dictionaries::\n\n   bitmask.APOGEE_TARGET1\n   {0: 'APOGEE_FAINT',\n    1: 'APOGEE_MEDIUM',\n    2: 'APOGEE_BRIGHT',\n    3: 'APOGEE_IRAC_DERED',\n    ...}\n   bitmask.APOGEE_TARGET2\n   {1: 'APOGEE_FLUX_STANDARD',\n    2: 'APOGEE_STANDARD_STAR',\n    3: 'APOGEE_RV_STANDARD',\n    ...}\n\n\nPlotting\n^^^^^^^^\n\nThe ``apogee`` module also contains some functionality to plot the\nAPOGEE spectra in ``apogee.spec.plot``. For example, to make a nice\nplot of the pseudo-continuum-normalized aspcapStar spectrum of entry\n3512 in the subsample of S/N \u003e 200 stars in the DR12 red-clump\ncatalog, do::\n\n   import apogee.tools.read as apread\n   import apogee.spec.plot as splot\n   data= apread.rcsample()\n   indx= data['SNR'] \u003e 200.\n   data= data[indx]\n   splot.waveregions(data[3512]['LOCATION_ID'],data[3512]['APOGEE_ID'],ext=1,\n                     labelID=data[3512]['APOGEE_ID'],\n\t\t     labelTeff=data[3512]['TEFF'],\n\t\t     labellogg=data[3512]['LOGG'],\n\t\t     labelmetals=data[3512]['METALS'],\n\t\t     labelafe=data[3512]['ALPHAFE'])\n\nwhich gives\n\n.. image:: _readme_files/_aspcapPlot_example.png \n\t\t\n``apogee.spec.plot.waveregions`` can plot arbitrary combinations of\nwavelength regions specified using (``startlams=``, ``endlams=``) or\n(``startindxs=``, ``endindxs=``) to either specify starting/ending\nwavelengths or indices into the wavelength array. The default displays\na selection of regions chosen to have every element included in the\nstandard APOGEE abundance analysis. If ``labelLines=True`` (the\ndefault), strong, clean lines from `Smith et al. (2013)\n\u003chttp://adsabs.harvard.edu/abs/2013ApJ...765...16S\u003e`__ are labeled. We\ncan also overlay the best-fit model spectrum::\n\n   splot.waveregions(data[3512]['LOCATION_ID'],data[3512]['APOGEE_ID'],'r-',\n                     ext=3,overplot=True,\n                     labelID=data[3512]['APOGEE_ID'],\n\t\t     labelTeff=data[3512]['TEFF'],\n\t\t     labellogg=data[3512]['LOGG'],\n\t\t     labelmetals=data[3512]['METALS'],\n\t\t     labelafe=data[3512]['ALPHAFE'])\n\nwhich gives\n\n.. image:: _readme_files/_aspcapPlotwModel_example.png \n\t\t\nBy plotting the error array (``ext=2``) you can see that the regions\nwith a large discrepancy between the model and the data are regions\nwith large errors (due to sky lines).\n\nThe same ``apogee.spec.plot.waveregions`` can also plot the\nnon-continuum-normalized spectrum (``apStar`` in APOGEE parlance)::\n\n   splot.waveregions(data[3512]['LOCATION_ID'],data[3512]['APOGEE_ID'],ext=1,\n\t\t     apStar=True,labelID=data[3512]['APOGEE_ID'],\n\t\t     labelTeff=data[3512]['TEFF'],\n\t\t     labellogg=data[3512]['LOGG'],\n\t\t     labelmetals=data[3512]['METALS'],\n\t\t     labelafe=data[3512]['ALPHAFE'])\n\nwhich gives\n\n.. image:: _readme_files/_apStarPlot_example.png \n\nTo plot a whole detector, use ``apogee.spec.plot.detector`` in the\nsame way, but specify the detector (``'blue'``, ``'green'``, or\n``'red'``) as an additional argument. For example::\n   \n   splot.detector(data[3512]['LOCATION_ID'],data[3512]['APOGEE_ID'],\n                  'blue',ext=1,labelLines=False,\n                  labelID=data[3512]['APOGEE_ID'],\n                  labelTeff=data[3512]['TEFF'],\n                  labellogg=data[3512]['LOGG'],\n                  labelmetals=data[3512]['METALS'],\n                  labelafe=data[3512]['ALPHAFE'])\n\nwhich gives\n\n.. image:: _readme_files/_detectorPlot_example.png \n\nWe haven't labeled the lines here, because there are so\nmany. Similarly, the green and red detector are given by::\n\n   splot.detector(data[3512]['LOCATION_ID'],data[3512]['APOGEE_ID'],\n                  'green',ext=1,labelLines=False,\n                  labelID=data[3512]['APOGEE_ID'])\n\n.. image:: _readme_files/_detectorGreenPlot_example.png \n\nand::\n\n   splot.detector(data[3512]['LOCATION_ID'],data[3512]['APOGEE_ID'],\n                  'red',ext=1,labelLines=False,\n                  labelID=data[3512]['APOGEE_ID'])\n\n.. image:: _readme_files/_detectorRedPlot_example.png \n\nIf you want even more detail, check out ``apogee.spec.plot.highres``,\nwhich returns an iterator over a 12-panel plot of the spectrum,\nallowing much detail to be seen in the spectrum. With\n``apogee.spec.plot.highres2pdf`` you can save these 12 panels to a 12\npage PDF file.\n\nIt is also possible to plot the parts of a spectrum corresponding to\nthe abundance windows used by APOGEE's abundance determination. For\nexample, to plot the spectrum and the best fit for the window for Si\ndo::\n\n\t splot.windows(data[3512]['LOCATION_ID'],data[3512]['APOGEE_ID'],'Si')\n\t splot.windows(data[3512]['LOCATION_ID'],data[3512]['APOGEE_ID'],'Si',ext=3,overplot=True)\n\n.. |Angstrom| unicode:: U+212B .. Angstrom sign\n\nwhich gives (each ``x`` tick mark is 2 |Angstrom|)\n\n.. image:: _readme_files/_windowsPlot_example_Si.png\n\n``C``, ``N``, ``O``, and ``Fe`` have so many windows that a single plot\nbecomes overcrowded, so for those elements you have the option to plot\nthe first half or the second half of the windows by giving the element\nas ``C1`` or ``C2``, respectively::\n\n   splot.windows(data[3512]['LOCATION_ID'],data[3512]['APOGEE_ID'],'Fe1')\n   splot.windows(data[3512]['LOCATION_ID'],data[3512]['APOGEE_ID'],'Fe1',ext=3,overplot=True)\n\n.. image:: _readme_files/_windowsPlot_example_Fe1.png\n\n``apogee.spec.plot.windows`` also has the option to overplot the weights of the windows. For example::\n\n     splot.windows(data[3512]['LOCATION_ID'],data[3512]['APOGEE_ID'],'Al',plot_weights=True)\n\n.. image:: _readme_files/_windowsPlot_example_Al.png\n\nThe module ``apogee.spec.window`` has various utilities to deal with\nthe windows.\n\t\t\nANALYZING SPECTRA\n==================\n\nGenerating model spectra\n^^^^^^^^^^^^^^^^^^^^^^^^^\n\n``apogee.modelspec`` contains various ways to generate model spectra\nfor APOGEE spectra. The easiest way is to use grids generated for\nAPOGEE data analysis and use FERRE (see above) to interpolate on these\ngrids. Using MOOG or Turbospectrum allows for more flexibility, but\nthis functionality is currently under development.\n\nUsing APOGEE model grids (using FERRE)\n+++++++++++++++++++++++++++++++++++++++\n\nTo use the APOGEE model grids for interpolation, you first need to\ndownload the grids. This can be done using::\n\n\t from apogee.tools import download\n\t download.ferreModelLibrary(lib='GK',pca=True,sixd=True,unf=False,dr=None,convertToBin=True)\n\nThis command downloads the main 6D, PCA-compressed 'GK' library used\nfor cooler stars (use ``lib='F'`` for hotter grids). ``unf=False``\nmeans that the ascii version of the library is downloaded and\n``convertToBin=True`` converts this ascii library to a binary format\n(there is a .unf file available for download, but because the binary\nformat is not machine independent, it is recommended to convert to\nbinary locally). **Because the model libraries are quite large, these\nare not downloaded automatically, so you need to run this command to\ndownload the library**. Currently only DR12 grids are supported.\n\nWith this library, you can generate model spectra using (see below for\nan alternative method)::\n\n     from apogee.modelspec import ferre\n     mspec= ferre.interpolate(4750.,2.5,-0.1,0.1,0.,0.)\n\nwhich returns a model spectrum on the apStar wavelength grid for\n``Teff=4750``, ``logg=2.5``, ``metals=-0.1``, ``alphafe=0.1``,\n``nfe=0.0``, and ``cfe=0.0`` (in that order). You could plot this, for\nexample, with the ``apogee.spec.plot.waveregions`` command above.\n\nProviding an array for each of the 6 (or 7 if you use a library that\nvaries the microturbulence) input parameters returns a set of\nspectra. For example::\n\n\t teffs= [4500.,4750.]\n\t s= numpy.ones(2)\n\t mspec= ferre.interpolate(teffs,2.5*s,-0.1*s,0.1*s,0.*s,0.*s)\n\t mspec.shape\n\t (2, 8575)\n\nAsking for tens of spectra simultaneously is more efficient, because\nyou only need to run the FERRE setup once (but it becomes inefficient\nfor many hundreds...).\n\nAn alternative method for generating interpolated spectra from the\ngrids is to use an ``Interpolator`` instance, which keeps FERRE\nrunning in the background and is thus more efficient at interpolating\nindividual spectra. These are set up as::\n\n      ip= ferre.Interpolator(lib='GK')\n\nand can then be used as::\n\n    mspec= ip(4750.,2.5,-0.1,0.1,0.,0.)\n\nTo properly clean up, the instance should be closed before exiting::\n\n   ip.close()\n\n``ferre.Interpolator`` instances can also be used as a *context\nmanager*, which automatically takes care of the necessary clean-up in\ncase of an Exception::\n\n     with ferre.Interpolator(lib='GK') as ip:\n     \t  mspec= ip(4750.,2.5,-0.1,0.1,0.,0.)\n\nThe APOGEE LSF and continuum normalization\n+++++++++++++++++++++++++++++++++++++++++++\n\nThe grids that are interpolated above are already convolved with the\nAPOGEE LSF and are continuum normalized using the standard\nAPOGEE/ASPCAP approach. When generating model spectra with other\nsoftware tools (like MOOG below) one needs to convolve the model\nspectra with the APOGEE LSF and apply continuum normalization. This\nsection briefly describes the tools available in this package for\ndoing this.\n\nTools for handling the APOGEE LSF are in the ``apogee.spec.lsf``\nmodule. The most important functions here are ``lsf.eval`` and\n``lsf.convolve``. ``lsf.eval`` evaluates the LSF for a given fiber (or\nan average of several fibers) on a grid of pixel offsets (in units of\nthe apStar logarithmic wavlength grid). These pixel offsets need to\nhave a spacing ``1/integer`` and the LSF will be evaluated on the\napStar wavelength grid subdivided by the same amount (so if\n``integer=3``, the ouput will be on the apStar wavelength grid in\npixel,pixel+1/3,pixel+2/3, pixel+1, etc.). This allows the convolution\nto be performed efficiently.\n\n``lsf.convolve`` convolves with both the APOGEE LSF and the\nmacroturbulence and outputs the spectrum on the standard apStar\nlogarithmically-spaced wavelength grid. The macroturbulence can either\nbe modeled as a Gaussian smoothing with a given FWHM or the proper\nmacroturbulence convolution kernel can be pre-computed using\n``apogee.modelspec.vmacro`` in the same way as the ``lsf.eval``\nfunction above. The convolutions are implemented efficiently as a\nsparse-matrix multiplication. The LSF obtained from ``lsf.eval`` and\nthe macroturbulence kernel from ``apogee.modelspec.vmacro`` can be\nreturned in this sparse format by specifying ``sparse=True`` or you\ncan yourself compute the sparse representation by running\n``lsf.sparsify``. If for some reason you do not wish to convolve with\nthe APOGEE LSF, you can compute a dummy LSF using ``lsf.dummy`` that\nis just a delta function and this can be passed to ``lsf.convolve``\n(useful for only convolving with macroturbulence).\n\nThe average DR12 LSFs for 6 fibers (the standard LSF for ASPCAP\nanalysis) or for all fibers is pre-computed and stored online at `this\nURL \u003chttp://dx.doi.org/10.5281/zenodo.16147\u003e`__. They can be\ndownloaded and loaded using ``lsf._load_precomp``. Various of the\nspectral analysis functions described below automatically download and\nload these LSFs.\n\nAn example of the LSF and macroturbulence functions is displayed\nbelow: this shows the average LSF of all APOGEE fibers, the proper\nmacroturbulence kernel, and a Gaussian macroturbulence kernel (which\nis used in the standard APOGEE analysis):\n\n.. image:: _readme_files/lsf_vmacro_example.png\n\n``apogee.spec.lsf`` also contains functions to deal with the raw\nLSF. This includes the ``wavelength-\u003epixel`` and ``pixel-\u003ewavelength``\nsolution, unpacking the parameters of the LSF, and evaluating the raw\nLSF using the LSF parameters.\n\nTools for working with the continuum normalization are included in\n``apogee.spec.continuum``. The main routine that is useful is\n``continuum.fit`` which fits the continuum to a set of spectra and\ntheir uncertainties using one of two methods (specified using the\n``type=`` keyword) and returns the continuum for each spectrum. \n\nThe first method is ``type='aspcap'``, which is also the default. This\nis an implementation of the default APOGEE/ASPCAP\ncontinuum-normalization in data releases \u003c 14 (see Garcia Perez et\nal. 2015), which iteratively searches for the upper envelope of the\nspectrum. An example of this procedure is the following::\n\n\taspec= apread.apStar(4159,'2M07000348+0319407',ext=1,header=False)[1]\n\taspecerr= apread.apStar(4159,'2M07000348+0319407',ext=2,header=False)[1]\n\t# Input needs to be (nspec,nwave)\n\taspec= numpy.reshape(aspec,(1,len(aspec)))\n\taspecerr= numpy.reshape(aspecerr,(1,len(aspecerr)))\n\t# Fit the continuum\n\tfrom apogee.spec import continuum\n\tcont= continuum.fit(aspec,aspecerr,type='aspcap')\n\nWe can then compare this to the official continuum-normalized spectrum\nin ``aspcapStar``::\n\n\tcspec= apread.aspcapStar(4159,'2M07000348+0319407',ext=1,header=False)\n\timport apogee.spec.plot as splot\n\tsplot.waveregions(aspec[0]/cont[0])\n\tsplot.waveregions(cspec,overplot=True)\n\t\n.. image:: _readme_files/_continuum_aspcap_example.png\n\nwhich demonstrates very good agreement.\n\nIn DR14, ASPCAP changed its pseudo-continuum normalization from an iterative search to a simple fourth-order polynomial fit. This can be done using the code above by specifying ``niter=0`` in the call to ``continuum.fit``.\n\nThe second method is ``type='cannon'``, which is an implementation of\na Cannon-style continuum-normalization (see `Ness et al. 2015\n\u003chttp://arxiv.org/abs/1501.07604\u003e`__; see below). This method uses a\npre-determined set of continuum pixels, which can be specified through\n``cont_pixels=``. A default set of pixels is included in the code;\nthere is also a function ``continuum.pixels_cannon`` that can\ndetermine the continuum pixels. For the same star as analyzed with the\nASPCAP continuum normalization above we find::\n\n       cont_cannon= continuum.fit(aspec,aspecerr,type='cannon')\n       splot.waveregions(aspec[0]/cont_cannon[0])\n       splot.waveregions(cspec,overplot=True)\n\nwhich gives\n\n.. image:: _readme_files/_continuum_cannon_example.png\n\nIn the wavelength region shown, the two methods agree nicely (but they\ndo not over the full wavelength range).\n\nWorking with model atmospheres\n+++++++++++++++++++++++++++++++\n\nGenerating synthetic spectra as discussed below for MOOG requires\nhaving a model atmosphere. `Meszaros et\nal. \u003chttp://adsabs.harvard.edu/abs/2012AJ....144..120M\u003e`__ have\ncomputed a grid of ATLAS9 model atmospheres varying effective\ntemperature, surface gravity, overall metallicity, and the relative\nenhancement of carbon and alpha elements. ``apogee`` has tools to work\nwith these in the ``apogee.modelatm`` module. This grid can be\ndownloaded on `this website\n\u003chttp://www.iac.es/proyecto/ATLAS-APOGEE/\u003e`__; APOGEE collaborators\ncan also use the ``apogee.tools.download.modelAtmosphere`` function to\ndownload these. Currently, the atmospheres must be put into a\n``apogeework/apogee/spectro/redux/speclib/kurucz_filled`` subdirectory\nof the overall ``$SDSS_LOCAL_SAS_MIRROR`` data directory (see above); the\n``download.modelAtmosphere`` function automatically puts the model\natmospheres in the correct location. The functions in\n``apogee.modelatm`` will also automatically download the necessary\natmospheres, so no setup should be required for collaboration members.\n\nATLAS9 model-atmosphere functionality is included in\n``apogee.modelatm.atlas9``. The main use of this module is that it\ncontains a class ``Atlas9Atmosphere``; instances of this class are\nindividual atmospheres and the instance allows one to inspect its\nstructure as a function of optical depth and to write the model\natmosphere to a file (useful for using the atmosphere with MOOG\nbelow).\n\nFor example, to load a grid point do::\n\n    from apogee.modelatm import atlas9\n    atm= atlas9.Atlas9Atmosphere(teff=4750.,logg=2.5,metals=-0.25,am=0.25,cm=0.25)\n\nOne can then look at, for example, the thermal structure::\n\n    atm.plot('T')\n\n.. image:: _readme_files/_atlas9_thermal.png\n\nor the gas pressure::\n\n   atm.plot('P')\n\n.. image:: _readme_files/_atlas9_gaspressure.png\n\nThe ``apogee.modelatm.atlas9`` module also contains a rudimentary\nmodel-atmosphere interpolator. This uses linear interpolation within\nthe hypercube of nearby grid points and means that one can load\nnon-grid-point atmospheres in the same way as above::\n\n    atm_ng= atlas9.Atlas9Atmosphere(teff=4850.,logg=2.65,metals=-0.3,am=0.15,cm=0.05)\n\nComparing this to the grid-point atmosphere above::\n\n\t  atm.plot('T')\n\t  atm_ng.plot('T',overplot=True)\n\n.. image:: _readme_files/_atlas9_thermal_ng.png\n\t  \nand::\n\n\tatm.plot('P')\n\tatm_ng.plot('P',overplot=True)\n\n.. image:: _readme_files/_atlas9_gaspressure_ng.png\n\nAll model atmospheres can be written to a file in KURUCZ format using ``writeto``, for example::\n\n    atm_ng.writeto('test.mod')\n\nOnly essential parts of the atmosphere are written out here, so don't\nbe alarmed that the top lines of the file don't match the model\natmosphere.\n\nUsing MOOG\n+++++++++++\n\nSynthetic spectra using `MOOG\n\u003chttp://www.as.utexas.edu/~chris/moog.html\u003e`__ can be generated using\nfunctions in the ``apogee.modelspec.moog`` module. The main functions\nin this module are ``moog.synth`` and ``moog.windows``, which provide\nhigh-level interfaces to MOOG. They both synthesize an arbitrary\nnumber of spectra for arbitrary combinations of abundances of\nindividual elements, convolve with the APOGEE LSF and macroturbulence,\nput the synthetic spectrum on the apStar logarithmic wavelength scale,\nand perform continuum-normalization (see above). The use of\n``moog.synth`` is to generate synthetic spectra over the full APOGEE\nwavelength range, ``moog.windows`` can be used to only vary the\nspectrum within certain windows (although full APOGEE wavelength\nspectra are returned also for ``moog.windows``; see below). There is\nalso a lower-level interface to MOOG, ``moog.moogsynth``, which allows\nmore direct access to MOOG's ``synth`` and ``doflux`` drivers, and\n``moog.weedout``, which allows MOOG's ``weedout`` driver to be\nrun. These are not further discussed here.\n\nThe inputs to ``moog.synth`` and ``moog.windows`` are by and large the\nsame. Both take an arbitrary number of lists as their first inputs,\nwhich specify the element to vary and the abundance relative to the\ndefault abundance in the provided model atmosphere. For example, to\nvary the iron abundance by -0.25 and 0.25 dex, the input would be\n[26,-0.25,0.25]; to also vary the titanium abundance one would also\nprovide a list [22,-0.3] (lists do not all have to have the same\nlength; they are zero-padded). \n\nThe model atmosphere can be provided in a variety of ways. The first\nis to give a model-atmosphere instance as discussed above as the\nkeyword ``modelatm=`` (this keyword can also be the name of file\nholding the model atmosphere). Alternatively, the stellar parameters\nof the atmosphere can be provided (``teff=``, ``logg=``, ``metals=``,\n``cm=``, and ``am=``; they can also be provided as an ``fparam=``\narray similar to the arrays coming out of ASPCAP [see below]). One\nalso has to specify the microturbulence (``vmicro=``, or as part of\n``fparam=``).\n\nTo perform the synthesis we need a line list. This can be passed as\nthe ``linelist=`` keyword. This can be set to a filename or just to\nthe name of an APOGEE line list for APOGEE collaborators (linelists\ncan be downloaded using ``apogee.tools.download.linelist``; make sure\nto also download the ``stronglines.vac`` linelist). Isotopic ratios\ncan be set to either ``isotopes='solar'`` or ``isotopes='arcturus'``\nfor typical dwarf or giant isotope ratios. The method for downloading\nMOOG linelists currently implemented here is only accessible to APOGEE\ncollaboration members, although the DR12 linelist is publicly\navailable; it has to be obtained independently from this code. A\nTurbospectrum version of the (corrected) DR12 linelist *can* be\nautomatically downloaded by the code (see below).\n\nThe LSF can be given as the ``lsf=`` keyword. This can be set to the\noutput of ``apogee.spec.lsf.eval`` (best if it's a sparse version of\nthis output; see above), in which case you also have to specify the\npixel offsets at which the LSF is calculated as ``xlsf=`` or\n``dxlsf``. Alternatively, you can just say ``lsf='all'`` or\n``lsf='combo'`` to use an average LSF of all fibers or a combination\nof 6 fibers (see the section on the LSF above).\n\nMacroturbulence can be set using the ``vmacro=`` keyword. This can be\na number for a Gaussian macroturbulence, or it can be set to the\noutput of ``apogee.modelspec.vmacro`` for a more realistic treatment\nof macroturbulence (again, see the LSF section above).\n\nContinuum normalization can be done in one of three ways:\n``cont='aspcap'`` (the default) which is an implementation of the\nstandard continuum normalization performed by ASPCAP;\n``cont='cannon'`` for the Cannon-style normalization described above;\nor ``cont='true'`` for using the true continuum.\n\nPutting all of this together, we can generate the synthetic spectra\nfor the two abundances given above and for the atmosphere above as\nfollows (we repeat the setup of the model atmosphere and explicitly\nset many of the parameters to their default values)::\n\n\timport apogee.modelspec.moog\n\tfrom apogee.modelatm import atlas9\n\tatm= atlas9.Atlas9Atmosphere(teff=4750.,logg=2.5,metals=-0.25,am=0.25,cm=0.25)\n\t# The following takes a while ...\n\tsynspec= apogee.modelspec.moog.synth([26,-0.25,0.25],[22,-0.3],modelatm=atm,\\\n\t\t linelist='moog.201312161124.vac',lsf='all',cont='aspcap',vmacro=6.,isotopes='solar')\n\t\nand we can plot these::\n\n    import apogee.spec.plot as splot\n    splot.waveregions(synspec[0])\n    splot.waveregions(synspec[1],overplot=True)\n\n.. image:: _readme_files/_synth_moog_example.png\n\n``apogee.moog.windows`` can generate synthetic spectra for which only\na set of windows are varied. Typical use of this function is with the\n``apogee.spec.window`` functions that specify the windows for\ndifferent element species. However, arbitrary windows can be specified\nusing the ``startindxs`` and ``endindxs`` or ``startlams`` and\n``endlams`` arguments (similar to ``apogee.spec.plot.waveregions``);\nthey need to be given before any abundance changes. For example, to\nvary the aluminum abundance for the off-grid model atmosphere above in\nthe APOGEE aluminum windows do::\n\n\t  abu= [13,-1.,-0.75,-0.5,-0.25,0.,0.25,0.5,0.75,1.]\n\t  synspec= apogee.modelspec.moog.windows('Al',abu,modelatm=atm_ng,\\\n\t  \t   linelist='moog.201312161124.vac')\n\nand we can plot the aluminum windows::\n\n    splot.windows(synspec[0],'Al')\n    for ii in range(1,len(abu)-1): splot.windows(synspec[ii],'Al',overplot=True)\n\n.. image:: _readme_files/_windows_al_moog_example.png\n\nThe ``moog.windows`` synthesis is performed by first synthesizing a\nsingle full APOGEE wavelength spectrum to use as a baseline and then\ngenerating multiple synthetic spectra in the requested windows for\nwhich the baseline is used outside of the window. For most elements of\ninterest this is very fast, because their lines only span a narrow\nwavelength range: some quick testing seems to indicate that as long as\nthe total wavelength region spanned by an element's windows is less\nthan about 80 Angstrom, using the ``windows`` function is faster than\nsynthesizing the whole spectrum. The wavelength region spanned by an\nelement's windows can be computed with\n``apogee.spec.window.total_dlambda``. The baseline can be pre-computed\nusing ``moog.moogsynth``, such that it can be re-used when varying\ndifferent elements. One has to generate the baseline continuum, the\ncontinuum normalized spectrum, and the wavelength grid on which the\nsynthesis is computed. For example::\n\n\t  # For the low-level moogsynth interface, we need to specify the atmosphere as a file\n\t  atm_ng.writeto('tmp.mod') \n\t  baseline= apogee.modelspec.moog.moogsynth(modelatm='tmp.mod',\\\n\t  \t    linelist='moog.201312161124.vac')[1] \n\t  mwav, cflux= apogee.modelspec.moog.moogsynth(doflux=True,\\\n\t  \tmodelatm='tmp.mod',linelist='moog.201312161124.vac')\n\t  \nthen we can repeat the calculation above as::\n\n     \t  synspec= apogee.modelspec.moog.windows('Al',abu,\\\n\t              baseline=baseline,mwav=mwav,cflux=cflux,\\\n\t\t      modelatm=atm_ng,linelist='moog.201312161124.vac')\n\nThis is clearly very fast once we have the baseline.\n\nUsing Turbospectrum\n++++++++++++++++++++\n\nA similar interface as described in detail above for MOOG exists for\n`Turbospectrum\n\u003chttp://www.pages-perso-bertrand-plez.univ-montp2.fr/\u003e`__ in\n``apogee.modelspec.turbospec``. The high-level interfaces\n``turbospec.synth`` and ``turbospec.windows`` are exactly the same as\nthe equivalents for MOOG above, but the low-level interface\n``turbospec.turbosynth`` to running Turbospec is slightly\ndifferent. The main difference between Turbospectrum and MOOG is how\nthe linelist is specified. The ``linelist=`` keyword can either be set\nto a list of linelists to use (like an atomic and a molecular one) or\nto a string. In the latter case, if the string filename does not exist\nthe code will also look for linelists that start in\n*turboatoms.*/*turbomolec.* or end in *.atoms*/*.molec*. You will have\nto download the ``Hlinedata.vac`` linelist from the APOGEE linelist\ndirectory as well if you are working in vacuum (the default and\nrecommended manner is to work in air wavelengths, which Turbospectrum\nexpects; the vacuum Hlinedata can be obtained with\n``apogee.tools.download.linelist('Hlinedata.vac')``. When working in\nair wavelengths, the internal Turbospectrum Hlinedata will be used. To\nwork in vacuum, specify ``air=False`` when running Turbospectrum\nsyntheses. However, this is not recommended as Turbospectrum is\ndesigned to run in air wavelengths! When using the ``201404080919``\nlinelist (see examples below), which is a corrected version of the\nDR12 linelist, it will be automatically downloaded from the `Zenodo\n\u003chttps://zenodo.org/record/32629#.Vi0XBBCrSfS\u003e`__ location that\ncontains this linelist. See Appendix C of `this paper\n\u003chttp://arxiv.org/abs/1510.06745\u003e`__ for more information on this\nlinelist.\n\nWe repeat the calculations done above using MOOG with\nTurbospectrum here as an example::\n\n\timport apogee.modelspec.turbospec\n\tfrom apogee.modelatm import atlas9\n\tatm= atlas9.Atlas9Atmosphere(teff=4750.,logg=2.5,metals=-0.25,am=0.25,cm=0.25)\n\t# The following takes a while ...\n\tsynspec= apogee.modelspec.turbospec.synth([26,-0.25,0.25],[22,-0.3],modelatm=atm,\\\n\t\t linelist='201404080919',lsf='all',cont='aspcap',vmacro=6.,isotopes='solar')\n\t\nand we can again plot these::\n\n    import apogee.spec.plot as splot\n    splot.waveregions(synspec[0])\n    splot.waveregions(synspec[1],overplot=True)\n\n.. image:: _readme_files/_synth_turbospec_example.png\n\nAnd for the Al variations in Al windows (re-using ``atm_ng`` from\nhigher up)::\n\n\t  abu= [13,-1.,-0.75,-0.5,-0.25,0.,0.25,0.5,0.75,1.]\n\t  synspec= apogee.modelspec.turbospec.windows('Al',abu,modelatm=atm_ng,\\\n\t  \t   linelist='201404080919')\n\nand we can plot the aluminum windows::\n\n    splot.windows(synspec[0],'Al')\n    for ii in range(1,len(abu)-1): splot.windows(synspec[ii],'Al',overplot=True)\n\n.. image:: _readme_files/_windows_al_turbospec_example.png\n\nAgain, the ``turbospec.windows`` synthesis is performed by first\nsynthesizing a single full APOGEE wavelength spectrum to use as a\nbaseline and then generating multiple synthetic spectra in the\nrequested windows for which the baseline is used outside of the\nwindow. For most elements of interest this is very fast, because their\nlines only span a narrow wavelength range: some quick testing seems to\nindicate that as long as the total wavelength region spanned by an\nelement's windows is less than about 80 Angstrom, using the\n``windows`` function is faster than synthesizing the whole\nspectrum. The wavelength region spanned by an element's windows can be\ncomputed with ``apogee.spec.window.total_dlambda``. The baseline can\nbe pre-computed using ``turbospec.turbosynth``, such that it can be\nre-used when varying different elements. One has to generate the\nbaseline continuum, the continuum normalized spectrum, the wavelength\ngrid on which the synthesis is computed, but also the continuous\nopacity, which can be saved to a file by specifying the ``modelopac=``\nkeyword. For example::\n\n\t baseline= apogee.modelspec.turbospec.turbosynth(modelatm=atm_ng,\\\n\t  \t    linelist='201404080919',\\\n\t\t    modelopac='mpac')\n         mwav= baseline[0]\n         cflux= baseline[2]/baseline[1]\n         baseline= baseline[1]\n\t  \nthen we can repeat the calculation above as::\n\n     \t  synspec= apogee.modelspec.turbospec.windows('Al',abu,\\\n\t              baseline=baseline,mwav=mwav,cflux=cflux,modelopac='mpac',\\\n\t\t      modelatm=atm_ng,linelist='201404080919')\n\nwhich is indistinguishable from the plot above. Remember that you end\nup with a file that contains the continuous opacity, so you might want\nto remove it again.\n\nFitting spectra\n^^^^^^^^^^^^^^^^^\n\nTo replicate the APOGEE data analysis, one can use the APOGEE model\ngrids to fit a spectrum. This has been implemented here for the\noverall six (or seven if you vary the microturbulence) parameter grid\nas well as for fitting individual elements. For example, let's look\nagain at entry 3512 in the subsample of S/N \u003e 200 stars in the DR12\nred-clump catalog. Load the catalog::\n\n\t  import apogee.tools.read as apread\n\t  data= apread.rcsample()\n\t  indx= data['SNR'] \u003e 200.\n\t  data= data[indx]\n\t\nand now fit entry 3512::\n\n    from apogee.modelspec import ferre\n    # The following takes a while\n    params= ferre.fit(data[3512]['LOCATION_ID'],data[3512]['APOGEE_ID'],\n                      lib='GK',pca=True,sixd=True)\n    print params\n    [[  4.67245500e+03   2.64900000e+00   2.08730163e-01  -4.43000000e-01\n  -6.40000000e-02   1.10000000e-01   4.90000000e-02]]\n\nWe can compare this to the official fit::\n\n   fitparams= data[3512]['FPARAM']\n   print fitparams\n   [  4.67250000e+03   2.64860010e+00   2.08765045e-01  -4.42680001e-01\n  -6.43979982e-02   1.10050000e-01   4.94019985e-02]\n   print numpy.fabs(fitparams-params)\n   [  4.50000000e-02   3.99898529e-04   3.48818403e-05   3.19998741e-04\n   3.97998154e-04   5.00002503e-05   4.01998520e-04]\n\nTo initialize the fit by first running the ``Cannon`` (`Ness et\nal. 2015 \u003chttp://arxiv.org/abs/1501.07604\u003e`__; see below) with a\ndefault set of coefficients, do (this is much faster than the standard\nfit, because the standard fit starts from twelve different initial\nconditions)::\n\n   ferre.fit(data[3512]['LOCATION_ID'],data[3512]['APOGEE_ID'],\n                    lib='GK',pca=True,sixd=True,initcannon=True)\n   array([[  4.65617700e+03,   2.60000000e+00,   2.12986185e-01,\n             -4.40000000e-01,  -1.29000000e-01,   1.30000000e-01,\n             2.80000000e-02]])\n\nThis gives a fit that is very close to the standard ASPCAP fit.\n\nTo fix some of the parameters in the fit, do for example to just fit\n``Teff``, ``logg``, and ``metals``::\n\n   xparams= ferre.fit(data[3512]['LOCATION_ID'],data[3512]['APOGEE_ID'],\n                     fixam=True,fixcm=True,fixnm=True,\n                     lib='GK',pca=True,sixd=True)\n   print xparams\n   [[  4.69824100e+03   2.73600000e+00   2.01069231e-01  -4.21000000e-01\n   0.00000000e+00   0.00000000e+00   0.00000000e+00]]\n\nand compared to the previous results::\n\n    from apogee.tools import paramIndx\n    print (params-xparams)[paramIndx('Teff')]\n    -25.786\n    print (params-xparams)[paramIndx('logg')]\n    -0.087\n    print (params-xparams)[paramIndx('metals')]\n    -0.022\n\nIn ``apogee.modelspec.ferre.fit`` we can also directly specify a\nspectrum + spectrum error array instead of the ``location_id`` and\n``apogee_id`` given above.\n\nTo fit for the abundances of individual elements use\n``ferre.elemfit``. By default this function replicates the standard\nASPCAP fit: the grid dimension 'C', 'N', 'ALPHAFE', or 'METALS' is\nvaried based on whether the particular element is 'C', 'N', an alpha\nelement, or one of the remaining elements. For example, for the star\nabove we can get the Mg abundance by doing (we use ``params`` from\nabove as the baseline stellar-parameter fit)::\n\n    mgparams= ferre.elemfit(data[3512]['LOCATION_ID'],data[3512]['APOGEE_ID'],\n                      'Mg',params,\n                      lib='GK',pca=True,sixd=True)\n\nThe output is the full standard 7D output, but only the 'ALPHAFE'\ndimension was varied. Therefore, the [Mg/M] measurement is::\n\n\t  print mgparams[0,paramIndx('ALPHA')]\n\t  -0.007\n\nwhich we can compare to the official data product, which is in\n'FELEM'::\n\n\tfrom apogee.tools import elemIndx\n\tprint data[3512]['FELEM'][elemIndx('Mg')]\n\t-0.0078463\n\nTo for example also let the effective temperature float in the Mg abundance fit you can do::\n\n   mgparams= ferre.elemfit(data[3512]['LOCATION_ID'],data[3512]['APOGEE_ID'],\n                      'Mg',params,\n                      lib='GK',pca=True,sixd=True,fixteff=False)\n   print mgparams[0,paramIndx('ALPHA')]\n   -0.016\n\nThat is, the Mg abundance only changes by 0.01 dex. ``elemfit`` can also return an estimate of the error on the abundance, for example, do::\n\n     mgparams, mgerr= ferre.elemfit(data[3512]['LOCATION_ID'],data[3512]['APOGEE_ID'],\n                      'Mg',params,\n                      lib='GK',pca=True,sixd=True,estimate_err=True)\n     print mgparams[0,paramIndx('ALPHA')], mgerr\n     -0.0068 [ 0.0519986]\n\nIf the estimated uncertainty is NaN, then it is larger than about 0.3\ndex. To fully map the chi squared curve for a given element, you can\nuse ``ferre.elemchi2``. Clever use of this will also allow one to\ninvestigate correlations between the elemental abundance and stellar\nparameters.\n\nTo fit for all of the elemental abundances you can use ``elemfitall``,\nwhich returns a dictionary of abundances relative to hydrogen for all\nAPOGEE elements::\n\n\tfelem= ferre.elemfitall(data[3512]['LOCATION_ID'],data[3512]['APOGEE_ID'],fparam=params,lib='GK',pca=True,sixd=True)\n\nWe can compare this to the pipeline products, for example for Ni::\n\n\tprint felem['Ni']\n\t[-0.453]\n\tprint data[3512]['FELEM'][elemIndx('Ni')]\n\t-0.45136\n\nor for Si (which in the standard pipeline product is given as [Si/Fe], so we have to add [Fe/H])::\n\n\tprint felem['Si']\n\t[-0.204]\n\tprint data[3512]['FELEM'][elemIndx('Si')]+params[:,paramIndx('METALS')] \n\t[-0.20453]\n\n``elemfitall`` can also estimate uncertainties in all of the\nabundances by setting the keyword ``estimate_err=True``; uncertainties\nare returned as keys 'e_X'.\n\n\nUsing The Cannon\n^^^^^^^^^^^^^^^^^\n\nThis package has some (currently) limited functionality to apply the\n``Cannon`` (`Ness et al. 2015 \u003chttp://arxiv.org/abs/1501.07604\u003e`__) to\nAPOGEE data. So far, a linear or a quadratic fit for an arbitrary set\nof labels is supported by ``apogee.spec.cannon.linfit`` and\n``apogee.spec.cannon.quadfit``, which returns the coefficients of the\nfit, the scatter, and possibly the residuals. Using the coefficients\nto determine labels for a new spectrum is supported through\n``apogee.spec.cannon.polylabels`` (although this implementation takes\na shortcut to avoid the necessary non-linear\noptimization). ``apogee.spec.cannon.polylabels`` has a default set of\ncoefficients and scatter, so you can run for the example above (this\nis what is used by the ``initcannon=True`` option of\n``apogee.modelspec.ferre.fit`` above to initialize the FERRE fit)::\n\n\t     import apogee.spec.cannon\n\t     apogee.spec.cannon.polylabels(data[3512]['LOCATION_ID'],data[3512]['APOGEE_ID'])\n\t     array([[  4.80598726e+03,   2.22568929e+00,  -4.12532522e-01,\n\t               8.04473056e-02]])\n\nwhich returns ``(Teff,logg,metals,[a/Fe])``. This default Cannon setup\nwas not trained on dwarfs, which will therefore come out in funny\nparts of parameter space.\n\nStacking spectra\n^^^^^^^^^^^^^^^^^\n\nVery simple stacking functions are included in\n``apogee.spec.stack``. Currently these consist of a (masked)\nmedian-stacking routine and an inverse-variance stacking.\n\nAPOGEE 1 AND 2 SELECTION FUNCTIONS\n==========================\n\nRaw selection functions\n^^^^^^^^^^^^^^^^^^^^^^^\n\nOne of the main uses of this codebase is that it can determine the\nselection function---the fraction of objects in APOGEE's color and\nmagnitude range(s) successfully observed spectroscopically. This code\nis contained in *apogee.select.apogeeSelect*. Because the selection function differs between APOGEE-1 (observations in SDSS-III) and APOGEE-2 (SDSS-IV), these survey selection functions need to be evaluated separately. Both functions are implemented as sub-classes of the ``apogeeSelect`` superclass. \n\nThe selection function for APOGEE 1 is loaded using::\n\n   import apogee.select.apogeeSelect\n   apo= apogee.select.apogee1Select()\n\nwhich will load the selection function for the full sample (this will\ntake a few minutes, and can take longer if the necessary files need to be downloaded, dependent on your connection). Replacing ``apogee1Select()`` with ``apogee2Select`` will load the selection function for APOGEE-2. For ``apogee2Select``, you can supply the ``hemisphere=`` keyword to select between APOGEE-2 `'north'` and `'south'` (by default this is set to `'north'`). If only\na few fields are needed, only those fields can be loaded by supplying\nthe *locations=* keyword, e.g.::\n\n       apo= apogee.select.apogee1Select(locations=[4240,4241,4242])\n\nwill only load the fields *030+00*, *060+00*, and *090+00* (this functionality is also available in ``apogee2Select``). Locations\nare identified using their location_id. Because loading the selection\nfunction takes a long time, you might want to pickle it to save it\n(this is supported); to reduce the size of the object and pickle, you\ncould ``del apo._specdata`` and ``del apo._photdata`` if you don't\nwant to make any plots (see below) with the unpickled object\n(evaluating the selection function does not require these attributes).\n\nThe basic algorithm to determine the selection function is very simple:\n\n* Only completed plates are considered\n* Only completed cohorts are used; only stars observed as part of a completed cohort are considered to be part of the statistical sample (but, there is an initialization option *frac4complete* that can be used to set a lower completeness threshold; this still only uses complete plates)\n* For any field/cohort combination, the selection function is the number of stars in the spectroscopic sample divided by the number of stars in the photometric sample (within the color and magnitude limits of the cohort).\n* Only stars in APOGEE's main sample (selected using a dereddened *J-K*\\ :sub:`s` \u003e 0.5 color cut only, in the case of APOGEE-1) are included in the spectroscopic sample. See the function `apogee.tools.read.mainIndx \u003chttp://github.com/jobovy/apogee/blob/master/apogee/tools/read.py#L950\u003e`__ for the precise sequence of targeting-flag cuts that define the main sample.\n\nThe selection function for APOGEE-1 can be evaluated (as a function) by calling the instance with the location_id and desired apparent H band magnitude. For example::\n\n    apo(4240,11.8)\n    0.0043398099560346048\n    apo(4242,12.7)\n    0.0094522019334049405\n    apo(4242,12.9)\n    0.\n\n(all of the examples here use a preliminary version of the selection function for year1+2 APOGEE data; later versions might give slightly different answers and later years will give very different answers if the number of completed cohorts changes)\n\nThe latter is zero, because the long cohort for this field has not\nbeen completed yet (as of year1+2). \n\nEvaluation of the APOGEE-2 selection function also requires a dereddened (J-Ks) colour as an argument, e.g.::\n    \n    apo(5155,11.8,0.6)\n    0.1602803738317757\n    apo(5155,11.8,0.9)\n    0.9022988505747126\n    apo(5155,13.,0.9)\n    0.0\n    \nYou can see that the redder color bins in APOGEE-2 have higher levels of completeness.\n\nTo get a list of all locations that are part of the statistical sample (i.e., that have at least a single completed cohort), do::\n\n   locs= apo.list_fields(cohort='all') #to get all locations\n   locs= apo.list_fields(cohort='short') #to get all locations with a completed short cohort\n   locs= apo.list_fields(cohort='medium') #to get all locations with a completed medium cohort\n   locs= apo.list_fields(cohort='long') #to get all locations with a completed long cohort\n   \nTo get the H-band limits for a field's cohort do::\n\n   apo.Hmin(4240,cohort='short')\n   apo.Hmax(4240,cohort='short')\n   \nand similar for medium and long cohorts. We can also get the center of the plate in longitude and latitude, the radius within which targets are drawn, or the string name for each field::\n\n    apo.glonGlat(4240)\n    apo.radius(4240)\n    apo.fieldName(4240)\n    \nThe above functions work for both APOGEE-1 and 2 selection functions. The APOGEE-2 function can also return information about the color bins employed in the target selection for that survey::\n\n    apo.NColorBins(5155)\n    2 #this location had two (J-K) bins\n    apo.JKmin(5155, bin=0)\n    0.5\n    apo.JKmax(5155, bin=0)\n    0.800000011920929\n    apo.JKmin(5155, bin=1)\n    0.800000011920929\n    apo.JKmax(5155, bin=1)\n    999.9\n    \nThe selection function can be plotted for both ``apogee1Select`` and ``apogee2Select`` objects using::\n\n    apo.plot_selfunc_xy(vmax=15.) #for Galactic X and Y\n    apo.plot_selfunc_xy(type='rz',vmax=15.) #For Galactocentric R and Z\n\n.. image:: _readme_files/_selfunc_xy.png \n\n.. image:: _readme_files/_selfunc_rz.png\n   \nwhich gives a sense of the spatial dependence of the selection\nfunction (which is really a function of *H* and not distance; *H* is\nconverted to distance here assuming a red-clump like absolute\nmagnitude and a fiducial extinction model). An optional ``color_bin`` keyword allows for plotting of the selection function in each color bin for APOGEE-2 (this defaults to the first bin if not set). The selection function for\na given cohort can also be plotted as a function of Galactic longitude\nand latitude::\n\n    apo.plot_selfunc_lb(cohort='short',type='selfunc',vmax=15.)\n\n.. image:: _readme_files/_selfunc_lb_short.png\n\nThis function can also show the number of photometric and\nspectroscopic targets, the H-band limits for each cohort, and the\nprobability that the spectroscopic sample was drawn from the\nphotometric sample (through use of the *type=* keyword).\n\nThe photometric sample's color--magnitude distribution can be shown,\nas well as that of the spectroscopic sample and the photometric sample re-weighted using the selection function::\n\n   apo.plotColorMag(bins=101,specbins=51,onedhistsbins=201,onedhistsspecbins=101,cntrSmooth=.75)\n\n.. image:: _readme_files/_colormag.png\n\nThis allows one to see that the spectroscopic sample (red) is a fair\nsampling of the underlying photometric sample (black), after\ncorrecting for the (simple) selection function (blue). For individual\nplates, the cumulative distribution in *H* can be compared for the\nphotometric and spectroscopic samples (correcting for the selection\nfraction) using::\n\n\t  apo.plot_Hcdf(4242)\n\nwhich shows this for all completed cohorts in field 4242 (*090+00*):\n\n.. image:: _readme_files/_hcdf_4242.png\n\nThe red line is the spectroscopic sample and the black line the\nphotometric sample. We can calculate the K-S probability that the red\nand black distributions are the same::\n\n    apo.check_consistency(4242)\n    0.76457183071108814\n\nThus, there is a very high probability that these two distributions\nare the same.\n\nThe selection function instance also has a function that will\ndetermine which stars in a given sample are part of the\n**statistical** sample. For example, if one has started from the\n*allStar* sample and performed some spectroscopic cuts, you can run\nthis sample through this function to see which stars are part of the\nstatistical sample, so that their relative frequency in the sample can\nbe adjust to reflect that of the underlying photometric sample. For\nexample,::\n\n\timport apogee.tools.read as apread\n\tallStar= apread.allStar(rmcommissioning=True,main=False,ak=True, akvers='targ',adddist=False)\n\t#Do some cuts to the sample\n\tallStar= allStar[various cuts]\n\t#Now which part of the sample is statistical?\n\tstatIndx= apo.determine_statistical(allStar)\n\nThe array **statIndx** now is an boolean index array that identifies\nthe stars that are in the statistical sample.\n\n\nCombining APOGEE-1 and 2 Selection Functions\n^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n\nA detailed look at the *combined* selection function for the latest APOGEE DR16 release can be found as a jupyter notebook in this `gist\n\u003chttps://gist.github.com/jobovy/47507a217409f152315323905edd711d\u003e`__, but we can examine it's high level properties and access here.\n\nThe *combined* selection function of the APOGEE-1 and 2 surveys allows the use of the full available data set and includes data from SDSS-III and IV. We have implemented this through the ``apogeeCombinedSelect`` class, which is called as::\n\n    apo = apogee.select.apogeeCombinedSelect(year = 7)\n    \nSpecifying the year up to DR16. This loads an instance of ``apogee1Select`` and the northern and southern hemisphere instances of ``apogee2Select`` (which are stored inside the ``apogeeCombinedSelect`` object as ``apo.apo2Nsel`` and ``apo.apo2Ssel``), then combines them to make a single consistent selection function, which can be evaluated, as if it was the regular ``apogee2Select`` instance like::\n\n    apo(4240,11.8,0.8)\n    0.014097291164373848\n    \nsince location 4240 is an APOGEE-1 location, it is simply evaluated as a location with a *single* color bin, and the APOGEE-1 selection fraction is returned. We can then re-plot the selection fraction on the sky for the entire APOGEE sample up to DR16, as before, using::\n\n    apo.plot_selfunc_lb(cohort='short',type='selfunc',)\n    \n.. image:: _readme_files/_apogeeCombinedSelect_lb.png\n\nWhich, by default, will plot the selection fraction for just the first of the color bins in any APOGEE-2 fields (this can be adjusted with the ``color_bin`` keyword, as before). Compared to the equivalent plot above, it is clear that APOGEE now covers a far larger portion of the sky than in DR12 (shown above), and with a far higher selection fraction in many fields.\n\nWe can also now re-plot the comparison between the spectroscopic and photometric color--magnitude distributions, now for the whole APOGEE data set, as before::\n\n    apo.plotColorMag(bins=101,specbins=51,onedhistsbins=201,onedhistsspecbins=101,cntrSmooth=.8)\n    \n.. image:: _readme_files/_apogeeCombinedSelect_colormag.png\n\nThe newly adopted color binning in APOGEE-2 is clear in this plot, but we can see that the selection function still does a good job of re-weighting the underlying photometric sample (underlying in black, re-weighted in blue contours) to match the spectroscopic sample (red contours).  \n\nAs mentioned before, the loaded ``apogeeCombinedSelect`` object also contains the individual ``apogee1Select`` and ``apogee2Select`` objects, which can be accessed via ``apo.apo1sel``, ``apo.apo2Nsel`` and ``apo.apo2Ssel``, respectively. You can see that functionality in action in this  `jupyter notebook \u003chttps://gist.github.com/jobovy/47507a217409f152315323905edd711d\u003e`__, which also does some further exploration of the selection and completeness of DR16.\n\nEffective selection function\n^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n\nAs discussed in `Bovy, Rix, Schlafly et al. (2015)\n\u003chttp://arxiv.org/abs/1509.XXXXX\u003e`__ and `Bovy, Rix, Green et\nal. (2015) \u003chttp://arxiv.org/abs/1509.XXXXX\u003e`__, the selection\nfunction can be efficiently used when fitting the spatial (or\nphase-space) density profile of a stellar population through the use\nof the *effective selection function*. This function encapsulates the\nselection function itself, the three-dimensional extinction, and the\nphotometric-distance relation used to turn the *H*-band dependent\nselection function *S(H,l,b,...)* (in APOGEE's case) into a selection\nfunction in terms of distance *S(D,l,b)*. The latter is much easier to\nuse.\n\nThe ``apogee`` package contains a class that implements the effective\nselection function for APOGEE. This functionality is included in\n``apogee.select.apogeeSelect.apogeeEffectiveSelect``. The effective\nselection function requires a three-dimensional extinction map (to\napply extinction when going from distance to magnitude), which has to\nbe provided as a ``mwdust.Dustmap3D`` object (see `mwdust\n\u003chttps://github.com/jobovy/mwdust\u003e`__). The initialization further\nrequires a raw APOGEE selection-function instance (see ``apo`` above - this can be an APOGEE 1, 2 or Combined selection function instance)\nand a Monte Carlo sampling from the absolute *H* magnitude of the\ntracer (this can be a single value for a standard candle; the default\nis to use the red clump with *M_H = -1.49*)::\n\n   from apogee.select.apogeeSelect import apogeeEffectiveSelect\n   from mwdust import Green15\n   g15= Green15(filter='2MASS H')\n   apof= apogeeEffectiveSelect(apo,MH=-1.49,dmap3d=g15)\n\nWe can then evaluate the effective selection function as follows::\n\n   apof(4240,[5.])\n   array([ 0.01028933])\n\nThis returns the fraction of stars observed in the 4240 field\n(*030+00*) at 5 kpc from the Sun (this function is much more efficient\nfor arrays). This function also takes the same ``MH=`` keyword that\nthe initialization takes, so you can override the object-wide default.\n\nIf using an APOGEE-2 or Combined selection function instance, one should also supply the ``JKO=`` keyword, which works similarly to the ``MH=`` keyword, in that it should be passed some representation of the dereddened (J-K) color distribution of the tracer which corresponds to the given absolute magnitude sampling. As an example, if using RGB stars in APOGEE, one could sample a set of isochrones in the APOGEE color and magnitude range, to gain a consistent sampling of the underlying absolute H magnitude and colour.\n\nTOOLS FOR WORKING WITH INTERESTING APOGEE SUBSAMPLES\n=====================================================\n\nThis codebase contains tools to characterize the properties of\ndifferent subsamples of the APOGEE data using stellar-evolution\nmodels. In particular, it contains methods to reproduce the selection\nof red clump (RC) stars as in `Bovy et al. 2014\n\u003chttp://adsabs.harvard.edu/abs/2014ApJ...790..127B\u003e`__, to calculate\nthe mean *K*\\ :sub:`s` magnitude along the RC as a function of\nmetallity and color (Fig. 3 in that paper). The code also allows the\naverage RC mass, the amount of stellar-population mass represented by\neach RC star, and the age distribution (Figs. 12, 13, and 14 in the\nabove paper) to be computed. The tools in this package are kept\ngeneral such that they can also be useful in defining other subsamples\nin APOGEE.\n\nRC catalog tools\n^^^^^^^^^^^^^^^^^\n\nThe RC catalog is constructed by inspecting the properties of stellar\nisochrones computed by stellar-evolution codes and finding the region\nin surface-gravity--effective-temperature--color--metallicity space in\nwhich the absolute magnitude distribution is extremely narrow\n(allowing precise distances to be derived). The *apogee* toolbox can\nload different stellar-isochrone models and compute their\nproperties. This is implemented in a general *apogee.samples.isomodel*\nclass; the code particular to the RC lives in *apogee.samples.rc*,\nwith *rcmodel* being the equivalent of the more general\n*isomodel*. This code requires the `isodist\n\u003chttp://github.com/jobovy/isodist\u003e`__ library with accompanying data\nfiles; see the *isodist* website for info on how to obtain this.\n\nThe actual code used to generate the APOGEE-RC catalog from the\ngeneral APOGEE catalog is included as `this script\n\u003chttps://github.com/jobovy/apogee/blob/master/apogee/samples/make_rcsample.py\u003e`__.\n\nFor example, we can load near-solar metallicity isochrones from the\n`PARSEC \u003chttp://stev.oapd.inaf.it/cgi-bin/cmd\u003e`__ library for the RC\nusing::\n\n\tfrom apogee.samples.rc import rcmodel\n\trc= rcmodel(Z=0.02)\n\nThis command will take about a minute to execute. We can then plot the\nisochrones, similar to Fig. 2 in the APOGEE-RC paper::\n\n\t    rc.plot(nbins=101,conditional=True)\n\nwhich gives\n\n.. image:: _readme_files/_rc_cmd.png\n\nWe can also calculate properties of the absolute magnitude distribution as a function of color::\n\n   rc.mode(0.65)\n   -1.659\n   rc.sigmafwhm(0.65)\n   0.086539636654887273\n\nand we can make the same plot as above, but including the model, full-width, half-maximum, and the cuts that isolate the narrow part of the luminosity distribution::\n\n    rc.plot(nbins=101,conditional=True,overlay_mode=True,overlay_cuts=True)\n\n(this takes a while) which shows\n\n.. image:: _readme_files/_rc_cmd_wmode.png\n\nWe can also compute the average mass of an RC star, the fraction of a\nstellar population's mass is present in the RC, and the amount of\nstellar population mass per RC star. These are all calculated as a\nfunction of log10(age), so a grid of those needs to be specified::\n\n\t lages= numpy.linspace(numpy.log10(0.8),1.,20)\n\t amass= rc.avgmass(lages)\n\t plot(lages,amass,'k-')\n\nwhich gives\n\n.. image:: _readme_files/_rc_avgmass.png\n\nand::\n\n\tpopmass= rc.popmass(lages)\n\tplot(lages,popmass,'k-')\n\n.. image:: _readme_files/_rc_popmass.png\n\n\nFor convenience, the data in Figs. 3, 13, 14, and 15 in `Bovy et\nal. 2014 \u003chttp://adsabs.harvard.edu/abs/2014ApJ...790..127B\u003e`__ has\nbeen stored as functions in this codebase. For example, we can\ncalculate distances as follows::\n\n   from apogee.samples.rc import rcdist\n   rcd= rcdist()\n   rcd(0.65,0.02,11.)\n   array([ 3.3412256])\n\nwhere the inputs to *rcd* are *J-K*\\ :sub:`s` color, metallicity *Z*\n(converted from [Fe/H]), and the apparant *K*\\ :sub:`s` magnitude.\n\nWe can also get the data from Figs. 13, 14, and 15. This can be\nachieved as follows::\n\n\t from apogee.samples.rc import rcpop\n\t rcp= rcpop()\n\nwhich sets up all of the required data. We can then get the average\nmass etc.::\n\n     rcp.avgmass(0.,0.) #[Fe/H], log10 age\n     2.1543462571654866\n     rcp.popmass(0.,0.)\n     38530.337516523861\n\nand we can plot them. E.g.::\n\n    rcp.plot_avgmass()\n\nproduces Fig. 13 and::\n\n\t rcp.plot_popmass()\n\ngives the bottom panel of Fig. 14. We can also calculate the age\ndistribution::\n\n\tage_func= rcp.calc_age_pdf()\n\nwhich returns a function that evaluates the age PDF for the\nsolar-neighborhood metallicity distribution assumed in the paper. We\ncan also directly plot it::\n\n    rcp.plot_age_pdf()\n\nwhich gives Fig. 15. More info on all of these functions is available\nin the docstrings.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjobovy%2Fapogee","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjobovy%2Fapogee","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjobovy%2Fapogee/lists"}