{ "cells": [ { "cell_type": "markdown", "metadata": {}, "source": [ "# Quickstart\n", "Louis RICHARD (louis.richard@irfu.se)\n", "\n" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Getting Started\n", "To get up and running with Python, virtual environments and pyRFU, see: \\\n", "https://pyrfu.readthedocs.io/en/latest/getting_started.html#installation\n", "\n", "Python 3.10 or later is required" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Virtual environments\n", "It's best to setup and use virtual environments when using Python - these allow you to avoid common dependency problems when you install multiple packages\\\n", "`python -m venv pyrfu-tutorial`\\\n", "Then, to run the virtual environment, on Mac and Linux :\\\n", "`source pyrfu-tutorial/bin/activate`\\\n", "To exit the current virtual environment, type `deactivate`" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Install pyRFU\n", "`pip install pyrfu`\n", "### Upgrade pyRFU\n", "`pip install pyrfu --upgrade`\n", "### Local data directory\n", "We use environment variables to set the local data directories:\\\n", "data_path (root data directory for all missions in pyRFU) e.g., if you set data_path=\"/Volumes/mms\", your data will be stored in /Volumes/mms\n", "\n", "The load routines supported include:\n", "- Fluxgate Magnetometer (FGM)\n", "- Search-coil Magnetometer (SCM)\n", "- Electric field Double Probe (EDP)\n", "- Fast Plasma Investigation (FPI)\n", "- Hot Plasma Composition Analyzer (HPCA)\n", "- Energetic Ion Spectrometer (EIS)\n", "- Fly's Eye Energetic Particle Sensor (FEEPS)\n", "- Ephemeris and Coordinates (MEC)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Import MMS routines" ] }, { "cell_type": "code", "execution_count": 1, "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "Load IGRF coefficients ...\n" ] } ], "source": [ "from pyrfu import mms" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Define time interval" ] }, { "cell_type": "code", "execution_count": 2, "metadata": {}, "outputs": [], "source": [ "tint = [\"2019-09-14T07:54:00.000\", \"2019-09-14T08:11:00.000\"]" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Setup the MMS data path\n", "The MMS data path can be setup using mms.db_init" ] }, { "cell_type": "code", "execution_count": 3, "metadata": { "pycharm": { "name": "#%%\n" } }, "outputs": [], "source": [ "mms.db_init(default=\"local\", local=\"/Volumes/mms\")" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Data can also be downloaded directly from the MMS science data center using:" ] }, { "cell_type": "code", "execution_count": 4, "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "Help on function download_data in module pyrfu.mms.download_data:\n", "\n", "download_data(var_str, tint, mms_id, login: str = '', password: str = '', data_path: str = '')\n", " Downloads files containing field `var_str` over the time interval\n", " `tint` for the spacecraft `mms_id`. The files are saved to `data_path`.\n", " \n", " Parameters\n", " ----------\n", " var_str : str\n", " Input key of variable.\n", " tint : list of str\n", " Time interval.\n", " mms_id : str or int\n", " Index of the target spacecraft.\n", " login : str, Optional\n", " Login to LASP MMS SITL. Default downloads from\n", " https://lasp.colorado.edu/mms/sdc/public/\n", " password : str, Optional\n", " Password to LASP MMS SITL. Default downloads from\n", " https://lasp.colorado.edu/mms/sdc/public/\n", " data_path : str, Optional\n", " Path of MMS data. If None use `pyrfu/mms/config.json`\n", "\n" ] } ], "source": [ "help(mms.download_data)" ] }, { "cell_type": "code", "execution_count": 5, "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "Help on function download_ancillary in module pyrfu.mms.download_ancillary:\n", "\n", "download_ancillary(product, tint, mms_id, login: str = '', password: str = '', data_path: str = '')\n", " Downloads files containing field `var_str` over the time interval\n", " `tint` for the spacecraft `mms_id`. The files are saved to `data_path`.\n", " \n", " Parameters\n", " ----------\n", " product : {\"predatt\", \"predeph\", \"defatt\", \"defeph\"}\n", " Ancillary type.\n", " tint : list of str\n", " Time interval\n", " mms_id : str or int\n", " Spacecraft index\n", " login : str, Optional\n", " Login to LASP MMS SITL. Default downloads from\n", " https://lasp.colorado.edu/mms/sdc/public/\n", " password : str, Optional\n", " Password to LASP MMS SITL. Default downloads from\n", " https://lasp.colorado.edu/mms/sdc/public/\n", " data_path : str, Optional\n", " Path of MMS data. If None use `pyrfu/mms/config.json`\n", "\n" ] } ], "source": [ "help(mms.download_ancillary)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Load data\n", "Keywords to access data can be found in the help of mms.get_data" ] }, { "cell_type": "code", "execution_count": 6, "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "Help on function get_data in module pyrfu.mms.get_data:\n", "\n", "get_data(var_str, tint, mms_id, verbose: bool = True, data_path: str = '')\n", " Load a variable. var_str must be in var (see below)\n", " \n", " Parameters\n", " ----------\n", " var_str : str\n", " Key of the target variable (use mms.get_data() to see keys.).\n", " tint : list of str\n", " Time interval.\n", " mms_id : str or int\n", " Index of the target spacecraft.\n", " verbose : bool, Optional\n", " Set to True to follow the loading. Default is True.\n", " data_path : str, Optional\n", " Path of MMS data. If None use `pyrfu/mms/config.json`\n", " \n", " Returns\n", " -------\n", " out : xarray.DataArray or xarray.Dataset\n", " Time series of the target variable of measured by the target\n", " spacecraft over the selected time interval.\n", " \n", " See also\n", " --------\n", " pyrfu.mms.get_ts : Read time series.\n", " pyrfu.mms.get_dist : Read velocity distribution function.\n", " \n", " Examples\n", " --------\n", " >>> from pyrfu import mms\n", " \n", " Define time interval\n", " \n", " >>> tint_brst = [\"2019-09-14T07:54:00.000\", \"2019-09-14T08:11:00.000\"]\n", " \n", " Index of MMS spacecraft\n", " \n", " >>> ic = 1\n", " \n", " Load magnetic field from FGM\n", " \n", " >>> b_xyz = mms.get_data(\"B_gse_fgm_brst_l2\", tint_brst, ic)\n", "\n" ] } ], "source": [ "help(mms.get_data)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Load magnetic field from (FGM)" ] }, { "cell_type": "code", "execution_count": 7, "metadata": {}, "outputs": [ { "name": "stderr", "output_type": "stream", "text": [ "[21-Jul-23 09:26:54] INFO: Loading mms1_fgm_b_gse_srvy_l2...\n" ] } ], "source": [ "b_xyz = mms.get_data(\"b_gse_fgm_srvy_l2\", tint, 1)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Time series are xarray.DataArray objects" ] }, { "cell_type": "code", "execution_count": 8, "metadata": {}, "outputs": [ { "data": { "text/html": [ "
<xarray.DataArray (time: 16320, represent_vec_tot: 3)>\n",
"array([[-2.1031418 , -1.6935391 , 2.835863 ],\n",
" [-2.1007674 , -1.7059438 , 2.8462613 ],\n",
" [-2.1185403 , -1.6850468 , 2.8634877 ],\n",
" ...,\n",
" [-0.7177708 , 1.81181 , 5.15961 ],\n",
" [-0.75993973, 1.8259526 , 5.165373 ],\n",
" [-0.7561481 , 1.8053148 , 5.204192 ]], dtype=float32)\n",
"Coordinates:\n",
" * time (time) datetime64[ns] 2019-09-14T07:54:00.006946627 .....\n",
" * represent_vec_tot (represent_vec_tot) <U1 'x' 'y' 'z'\n",
"Attributes: (12/17)\n",
" CATDESC: Magnetic field vector in Geocentric Solar Ecliptic (G...\n",
" COORDINATE_SYSTEM: GSE\n",
" DEPEND_0: Epoch\n",
" DISPLAY_TYPE: time_series\n",
" FIELDNAM: Magnetic field vector in GSE plus Btotal (8 or 16 S/s)\n",
" FILLVAL: -1e+31\n",
" ... ...\n",
" SI_CONVERSION: 1.0e-9>T\n",
" TENSOR_ORDER: 1\n",
" UNITS: nT\n",
" VALIDMAX: [17000. 17000. 17000. 17000.]\n",
" VALIDMIN: [-17000. -17000. -17000. 0.]\n",
" VAR_TYPE: data