Package: astromol
astromolA Database of Molecules Detected in Spaceastromolis a Python 3 package that provides a database of molecules detected in space and an object-oriented interface for interacting with the database and generating the figures and tables from theCensus of Interstellar, Circumstellar, Extragalactic, Protoplanetary Disk, and Exoplanetary Moleculesby B. McGuire.If you useastromolfor your own work, please cite the Zenodo entry:.Setup InstructionsClone theastromolrepository, accessible athttps://github.com/bmcguir2/astromolto your computer.  It isnotrecommended to clone thedevelopmentbranch.In your terminal, navigate to theastromoldirectory, then install usingpip install -e .The use of the-eflag creates a symlink to the package which will enable you to easily check for and download updates to the code by simply usinggit pullin theastromoldirectory without needing to re-install.Version ControlThe version number ofastromolis given in the format XXXX.Y.Z, with each number corresponding to a different level of update:XXXX is a year (i.e. 2018 or 2021) corresponding to the most recent major update of the Census paper.Y is reset to 0 with each update of XXXX, and is incremented by 1 anytime a new molecule (or molecules) is added to the database between census releases.Z is reset to 0 with each update of XXXX or Y, and is incremented by 1 anytime an update is made to the code base that is not related to the addition of new molecules or the release of a new census.The version number forastromolis accessible by:fromastromolimportversionversion()It is also stored in the__version__variable.The date of the last update toastromolis available as well by:fromastromolimportupdatedupdated()It is also stored in the__updated__variable as a Pythondatetimeobject.Updates to documentation, such as this readme file, that do not accompany an actual change in the codebase arenotincremented in the version numbers, but are of course recorded as commits in the GitHub repository.Overall Structure and UsageThis package was written primarily to faciliate the McGuire 2018 living census paper.  As such, the figure- and table-making functions contained in it are tailor-made to that purpose, with limited flexibility or functionality for alteration.  However, to make the data as widely useful and accessible as possible, the package has been written to be object-oriented such that it is relatively straigthforward for anyone else to manipulate the dataset to suit individual needs.The most useful way to use the package is to do the (dreaded) import *:fromastromolimport*This will pre-load all of the information on detected species, facilities, and astronomical sources as variables into a Python session to work with.Object ClassesData inastromolis stored in one of three classes:Molecule,Telescope, orSource.  Each molecule, telescope, or astronomical source entry in the database is a variable that comes preloaded with theastromolpackage.  Accessing these information therefore requires knowing these variable names.  These can be found either by inspecting the corresponding files (molecules.py,telescopes.py, andsources.py) or by using the helper function:print_variables()This function takes two optional arguments:type =andnatoms =.  The former can be set tomolecules,telescopes, orsources, and the later can be used by specifying an integer and only molecules with that number of atoms will be printed.  If nothing is set, all variables will be printed.Some helper lists have been pre-loaded, these are:all_moleculesall_telescopesall_sourcesThese are just lists containing all variables in the database of the corresponding type.  This isn't useful for direct inspection (as it will just return Object IDs), but is very useful for looping over.The Molecule ClassThis is the primary data container for the package.  Each molecular species is represented by aMoleculeobject.  These objects have several dozen attributes, a full list of which can be found by calling:help(Molecule)Many of these attributes are placeholders and are not yet filled with data.  To see a raw display of all the possible attributes for a molecule, and see which portions have data for that particular entry, use the Molecule Class methodinspect.  For example, to see the data for methanol (CH3OH), use:CH3OH.inspect()Alternatively, the functioninspectcan be called, although this just calls the underlying class method anyway:inspect(CH3OH)A more nicely formatted summary of much of the pertinent data can be achieved using the Molecule Class methodsummary:CH3OH.summary()or, again, the functionsummaryis available to call the underlying class method:summary(CH3OH)The Telescope ClassThis data container holds information on the telescopes used to detect molecules.  These include currently:NameShorter name / abbreviationType of facilityGeneralized operational wavelength rangesLatitude and longitude in degreesDiameter of the dish (when appropriate)Dates of commissioning and decommissioningThis class has the same inspection command to view the entire contents:ALMA.inspect()As well, the overallinspectfunction can accept Telescope objects as an argument.The Source ClassThis data container holds information on the sources in which molecules are detected.  Right now these are only for ISM/CSM species.  The data gathered includes:NameGeneralized typeRA and Dec (hh:mm:ss and deg:min:sec)Direct link to the simbad entry for this source [may actually show up as a clickable hyperlink if view in Jupyter Notebooks]This class has the same inspection command to view the entire contents:SgrB2.inspect()As well, the overallinspectfunction can accept Source objects as an argument.FunctionsAs discussed above, nearly all functions provided in thefunctions.pyfile are used for generating the figures, tables, and other minutae for the census document.  Also as mentioned earlier, some limited customizability has been built into these functions.  For all plotting functions, it is possible, for example, to specify a custom list of molecules on which to operate.For example:cumu_det_plot()will generate the plot of the cumulative number of detections over time, using all molecules in the database.  However, one could choose to instead plot the cumulative number of ionic species detected in the ISM by:ions=[xforxinall_moleculesif(x.cationorx.anion)]cumu_det_plot(mol_list=ions)It's also possible to modify the filename that is used for output:ions=[xforxinall_moleculesif(x.cationorx.anion)]cumu_det_plot(mol_list=ions,filename='cumulative_ions.pdf')Custom plotting functions can of course be written to generate whatever plots are desired using the information in the database.  As well, one can always modify the built-in functions to change labels, colors, etc. to suit a need or preference.PowerPoint Slide of Detected ISM MoleculesThemake_mols_slide()function will generate a slide containing a formatted display of all detected ISM/CSM molecules to date, in widescreen PowerPoint format, sorted by the number of atoms.  It will display as well the total number of species, the date of the most recent update, the version ofastromolused to generate the slide, and the appropriate literature reference.  This, too, can take a modified list of species with themol_list =optional argument.Note that in the current implementation, the placement of the columns is done manually.  While it can adapt a bit to changes in the list, the adaptation is not perfect so some adjustment afterward might be needed.  Additionally, if the custom list doesn't contain molecules of a given number of atoms, PowerPoint will likely say the file is "broken" and ask to "repair" it.  Choosing the repair option is fine, and will produce the slide as normal.Updates are planned for this feature down the road to make it more versatile.BibTeX DatabasesAlongside the codebase itself, the installation comes with (currently) three *.bib files in thebibtexfolder:exgal_refs.bib
exo_refs.bib
ppd_refs.bibAgain, the primary purpose of these is to interface with the functions to generate LaTeX tables for the census, but they may be useful.These are also maintained as libraries in the NASA ADS system, accessible here:Extragalactic Molecule DetectionsExoplanet Atmosphere Molecule DetectionsProtoplanetary Disk Molecule DetectionsPlanned DevelopmentA number of upgrades are planned to the code, to the structure of the database, and to the content of the database.  If an item is on this list, please do not open a new issue on GitHub to request it; emails tobrettmc@mit.eduare welcome to express a prioritization desire. Current planned upgrades include the following:Inclusion ofSMILESstrings for each molecule.  There is asmilesattribute for theMoleculeclass for this purpose, but the data haven't been aggregated and input yet.Inclusion of links to relevant spectroscopic data -- largely CDMS and JPL rotational catalogs -- for each molecule.Inclusion of outputs of quantum chemical structure calculations for each molecule, using the methods recommended inLee & McCarthy 2020.Migration of references from strings to entirely bibtex citekeys.  Implementation has partially begun for protoplanetary disk, extragalactic, and exoplanetary atmosphere molecules.Move to dealing with isotopologues asMoleculeobjects themselves.  This has already been implemented for protoplanetary disk species partially; references are still contained as a string in the main molecule.  A future update will deprecate strings entirely in favor of bibtex entries (from which strings are dynamically generated).Incorporation of isotopologue data for molecules other than those found in protoplanetary disks.  Likely to be a gradual effort.Addition of tracking for cometary species as well.Addition of data on telescopes and detection sources for non-ISM/CSM species.Coordinates for sources will eventually be updated to beastropyobjectsLinks to telescope facility websitesIncrease versatility of the generation of the PowerPoint slide by allowing selective coloring or bolding of molecules given certain properties.A database of publication objects and/or authors is being considered, but is a long way off.Bugs, Errors, and Feature RequestsShould you encounter a bug, discover a factual error, or have a request for a new feature, please submit an issue using the GitHub issues tracker and providing as much description as possible.Pull RequestsDirect contributions to the codebase are not being accepted at this time.