mocapy

A Python package to interact with the MOCA database

The latest version of this package was only tested with Python 3.12.3 installed with a Mac M1-native conda setup.

You can install this package with the following command::

pip install git+https://github.com/jgagneastro/mocapy.git

One the package is installed, it is imperative to create a Python environment or a conda environment dedicated to its use, and install the exact versions of the packages that were used in its development. This is true because several Python packages will change over time in a non-retrocompatible way.

In order to create your own Python environment, open a terminal, navigate somewhere you will remember (e.g. your mocapy directory), and enter the following command::

python -m venv mocapy_env

This will create a mocapy_env directory where the exact versions of the Python packages required by mocapy will be stored without interfering with your system installations. Once this is done, you need to activate this virtual environment with the follwing terminal command::

source mocapy_env/bin/activate

Alternatively, you can create a conda environment for mocapy and then install the package inside that environment with::

conda create --name mocapy_env python==3.12.3
conda activate mocapy_env
pip install git+https://github.com/jgagneastro/mocapy.git

Note that you can choose your own environment name instead of mocapy_env.

Once this is done, you should see that your command line now stars with the "(mocapy_env) " flag before the usual prompts.

If you have downloaded the GitHub repository instead of installing it, you need to add it to your PYTHONPATH and then manually install all packages with the following command (here I am assuming you have navigated to the mocapy directory)::

pip install -r requirements.txt

Instead of navigating to your mocapy installation directory, you can also alternatively just download the requirements file wherever your environment was created with something like wget (or manually download requirements.txt from this repo) and then install the contents::

wget https://raw.githubusercontent.com/jgagneastro/mocapy/main/requirements.txt
pip install -r requirements.txt

Once the packages are installed, you should be able to launch Python and use mocapy normally. Note every time you need to use mocapy, you should launch the same mocapy Python environment, by navigating wherever you have created it, and launching the same command again::

source mocapy_env/bin/activate

If you used the conda environment instead of the pyenv environment, then you will do this instead (from anywhere)::

conda activate mocapy_env

Documentation

The full documentation for this project is not yet available.

The following Python command lines will allow you to download data from the MOCA database using raw MySQL syntax::

#Import the mocapy package
from mocapy import *

#Create a moca engine object
moca = MocaEngine()

#Query the moca database to obtain a Pandas DataFrame
df = moca.query("SELECT * FROM moca_objects LIMIT 20")

#See the outputs of the DataFrame
print(df)

You can also upload your own table to the database (as a temporary table) and use it to cross-match any database entries. In this example, we will use the previous df DataFrame which we downloaded from MOCAdb, but you could use any dataframe::

#Query the moca database again, but this time upload your own pandas DataFrame to cross-match against the database
dfnew = moca.query("SELECT * FROM cdata_spectral_types JOIN tmp_table USING(moca_oid)",tmp_table=df)

#See the outputs of the second DataFrame
print(dfnew)

If you would like to use your own list of stellar designations, we have provided an example file in /docs/star_designations.csv, which you can use with the following example::

# Import the necessary packages
from mocapy import *
import pandas as pd

# Initiate a connection to the MOCA database
moca = MocaEngine()

# Locate the file with the stellar designations
# Make sure the first line here has the word "designation" to indicate the column containing the stellar designations
file = "/mocapy/docs/star_designations.csv"

# Read the list of designations in a pandas DataFrame
df = pd.read_csv(file)

# Launch a query to MOCA joining the table "mechanics_all_designations" on your own list of stellar designations upon exact but case-insensitive matches (using the LIKE MySQL statement) in order to resolve the MOCA_OID unique identifiers, and use these moca_oid to join the summary_all_objects table containing best membership and other useful informations
mdf = moca.query("SELECT tt.designation AS input_designation, sam.* FROM tmp_table AS tt LEFT JOIN mechanics_all_designations AS mad ON(mad.designation LIKE tt.designation) LEFT JOIN summary_all_objects AS sam ON(sam.moca_oid=mad.moca_oid)", tmp_table=df)

# Display mdf summary
print(mdf)

You should get an output similar to this::

input_designation  moca_oid moca_aid moca_mtid  ...    gaiadr3_source_id                                   all_designations                                    designation_url  mtid_level
0            AU Mic   10946.0     BPMG         BF  ...  6794047652729201024  MCC 824|Gaia EDR3 6794047652729201024|TYC 7457...  <a href=https://mocadb.ca/search/results?searc...         0.0
1            HD 952  501711.0     None      None  ...  2863577296085970816  Gaia EDR3 2863577296085970816|TIC 365934195|2M...  <a href=https://mocadb.ca/search/results?searc...         NaN
2    Barnard's Star       NaN     None      None  ...                 None                                               None                                               None         NaN
3            HIP 12       NaN     None      None  ...                 None                                               None                                               None         NaN

[4 rows x 191 columns]

In this example, the last two stars did not have a match in the MOCA database, and thus the pandas DataFrame contains missing values.

Visualizing spectra and color-magnitude diagrams

Get_cmd is a MOCA tool that plots a color-magnitude diagram (the absolute M band magnitude as a function of the difference between the magnitudes of m1 and m2 bands) of the database field brown dwarfs sequence and overplots a manually entered object. For the moment, the use of this tool requires collaborators access to the database.

To overplot the entered object, the difference of m1 and m2 and the absolute magnitude of band M must be provided as m1m2 and M, respectively, along with their uncertainties as em1m2 and eM.

Each m1, m2 and M band can be specified using the exact unique photometry system identifier (moca_psid) of the moca_photometry_systems table or, more generally, the terms "j_any", "h_any" and "k_any". The bands are specified as strings through the variables m1_type, m2_type and M_type.

Some parameters can also be added to the CMD::

spt : (bool) Plot the spectral types of the field BD reference sequence (default = False)
young_objs : (bool) Plot the intermediate and low gravity substellar objects over the field reference sequence (default = False)
ref_err : (bool) Plot the error bars of the field BD reference sequence (default = False)
xmin, xmax = x-axis range (default = None, the range is automatically estimated)
ymin, ymax = y-axis range (default = None, the range is automatically estimated)
path = Path for saving the figure (default = None)
con = Connection to the database

To set the connection, add the right environment parameters moca_username, moca_password, moca_host and moca_dbname following the engine command below and provide this connection to get_cmd through the parameter con. If no connection is specified, the default public connection is used, which does not give the access to the tool yet.

The following Python command will allow you to compare the magnitudes M and m1m2 of the entered object with the field brown dwarf sequence::

#Import the mocapy package
import mocapy
from mocapy import MocaEngine
from mocapy import MocaViz
from sqlalchemy import create_engine

#Set the MOCA connection (as collaborators for now) :
engine = create_engine("mysql+pymysql://"+moca_username+":"+urlquote(moca_password)+"@"+moca_host+"/"+moca_dbname)
con = engine.connect()

#Create a mocaViz object
mocaviz = MocaViz()

#Call the function get_cmd :
mocaviz.get_cmd(m1m2, M, em1m2, eM, m1_type, m2_type, M_type, spt, young_objs, ref_err, xmin, xmax, ymin, ymax, path, con)

For example, to plot an entered object with an absolute magnitude in the band mko_jmag and difference between the bands mko_jmag and mko_kmag equal to 11 and 1, respectively, and their uncertainties over the sequence, you can use the following command::

mocaviz.get_cmd(1, 11, 0.1, 0.3, "mko_jmag", "mko_kmag", "mko_jmag", con = con)

.. image:: docs/cmd1.png :width: 450 :alt: cmd1 :align: center

If you want to plot this object over the sequence showing the spectral types and the young objects (low to intermediate gravity), you can use the parameters spt and young_seq::

mocaviz.get_cmd(1, 11, 0.1, 0.3, "mko_jmag", "mko_kmag", "mko_jmag", spt = True, young_seq = True, con = con)

.. image:: docs/cmd2.png :width: 450 :alt: cmd2 :align: center

Get_spectrum is a MOCA tool that plots the spectrum of the provided target as is or over a second target or MOCA database spectrum type reference models. For the moment, the use of this tool requires collaborators access to the database.

To display the spectrum of an object, either its designation or its unique s