e3doubt

Tools for estimating uncertainty of EISCAT_3D experiments

https://github.com/dartspacephysiker/e3doubt

Repository

Tools for estimating uncertainty of EISCAT_3D experiments

README.rst

|DOI|

Overview
========

EISCAT_3D Uncertainty Estimation (e3doubt)

e3doubt is a Python frontend to the ISgeometry R package developed by I. Virtanen (UOulu), and is a tool for estimating the uncertainties in the plasma parameters measured using the incoherent scatter radar technique with different beam configurations and radar system parameters. It is designed with EISCAT_3D in mind, but is readily adaptable to other radar configurations.   

We recommend using the python scripts in the `examples` folder to learn how to use e3doubt. (Some of these examples require the `lompe `_ Python package.)

Prerequisites
=======

- python >= 3.10
- git >= 2.13
- R >= 3.4
- CMake >= 3(?) (Tested with CMake 3.22.0)

If you have a mac with brew installed, R installation should be as simple as `brew install r`

CMake is installable with anaconda: `conda install -c anaconda cmake` as of November 2023.

Install
=======

(NB: In the below, if you do not have mamba, replace `mamba` with `conda`)

Option 0: using pip directly
----------------------------

The package may someday be pip-installable from GitHub directly with::

    pip install "e3doubt @ git+https://github.com/Dartspacephysiker/e3doubt.git@main"

This could also be done within a minimal conda environment created with, e.g. ``mamba create -n e3doubt python=3.10 fortran-compiler``

Option 1: mamba/conda install (RECOMMENDED)
---------------------------------------------------------------

Get the code, create a suitable conda environment, then use pip to install the package in editable (development) mode::

    git clone https://github.com/Dartspacephysiker/e3doubt
    mamba env create -f e3doubt/binder/environment.yml -n e3doubt
    mamba activate e3doubt
    pip install --editable ./e3doubt

Editable mode (``-e`` or ``--editable``) means that the install is directly linked to the location where you cloned the repository, so you can edit the code.

Note that in this case, the ``deps-from-github`` option means that Ilkka Virtanen's ``ISgeometry`` package will be installed directly from the source on GitHub. (THIS HAS NOT BEEN TESTED)


FIRST RUN
===========
Once you've got everything downloaded, you'll need to run something like the following to make rpy2 aware of the ISgeometry R package. NOTE: You *must* have R installed on your machine for this to work

.. code-block:: python

    # Location of e3d install directory
    e3ddir = '/path/to/e3doubt/'
    
    # Import things we need from rpy2
    from rpy2.robjects.packages import importr
    from rpy2 import robjects as robj
    import os
    
    # base = importr('base')
    utils = importr('utils')
    
    # Install dependencies for ISgeometry package 
    utils.install_packages("maps")
    utils.install_packages("mapdata")

    utils.install_packages(os.path.join(e3ddir,'external/ISgeometry'),
                           repos=robj.NULL,
                           dependencies=True,
                           type="source")


If you get errors about R not being able to locate ISgeometry, make sure that the ``external/ISgeometry/`` directory is not empty:

.. code-block::
   cd /path/to/e3doubt

   # Pull in ISgeometry package
   git submodule update --recursive --remote



Dependencies
============
You should have the following modules installed (this is handled automatically when e3doubt is install using the mamba/conda environment.yml file mentioned above):

- `apexpy `_
- `iri2016 `_
- matplotlib
- numpy
- pandas
- `ppigrf `_ (install with pip install ppigrf)
- `pymsis `_
- rpy2


.. |DOI| image:: https://zenodo.org/badge/711767218.svg
        :target: https://zenodo.org/badge/latestdoi/711767218

How to cite
===========
Hatch, S. M., and I. Virtanen (2024). e3doubt [Computer software]. doi:10.5281/zenodo.10683228

I. Virtanen (2023). ISgeometry [Computer software]. doi:10.5281/zenodo.6623186

References
==========
e3doubt publication coming soon!

The mathematical development of ISgeometry is described in Appendix B of Lehtinen, Virtanen, and Orispää (2014).

Lehtinen, M., Virtanen, I. I., & Orispää, M. R. (2014). EISCAT_3D Measurement Methods Handbook. https://urn.fi/URN:ISBN:9789526205854

Owner

Citation (CITATION.cff)

cff-version: 1.1.0
message: "If you use this software, please cite it as below."
authors:
- given-names: Spencer Mark
  family-names: Hatch
  orcid: https://orcid.org/0000-0001-7412-4936
- given-names: Ilkka
  family-names: Virtanen
  orcid: https://orcid.org/0000-0002-7111-8888
title: "EISCAT_3D Uncertainty Estimation (E3Doubt)"
identifiers:
  - type: doi
    value: 10.5281/zenodo.10245643
    description:  e3doubt - First release
version: v0.2.0a
date-released: 2023-12-01
                          

GitHub Events