special 0.0.5

Package for SPEctral Characterization of ImAged Low-mass companions

special is a package for the SPEctral Characterization of directly ImAged Low-mass companions. While some tools are specific to the characterisation of low-mass (M, L, T) dwarfs down to giant planets, special can also be used in a more general way for the characterisation of any object with a measured spectrum, provided an input model grid.

This package provides the following tools for the analysis of measured spectra:

• calculation of the spectral correlation between channels of an IFS datacube;

• calculation of empirical spectral indices for MLT-dwarfs;

• fitting of input spectra to different grids of models, including additional parameters such as (extra) black body component(s) and extinction;

• using either the MCMC (emcee) or nested (nestle) sampler to infer posterior distributions on spectral model parameters;

• searching for the best-fit template spectrum within a given template library, with up to two free parameters (flux scaling and relative extinction).

More details are available in Christiaens et al. (2021) (note it was originally implemented as specfit, a former module of the VIP package).

Documentation

The documentation for special can be found here.

Jupyter notebook tutorial

A Jupyter notebook tutorial examplifying most possibilities within special is available in the special-extras repository. Alternatively, you can execute this repository on Binder (in the tutorials directory), or go through it in the documentation.

TL;DR setup guide

$ pip install special

Installation and dependencies

The benefits of using a Python package manager (distribution), such as (ana)conda or Canopy, are many. Mainly, it brings easy and robust package management and avoids messing up with your system’s default python. An alternative is to use package managers like apt-get for Ubuntu or Homebrew/MacPorts/Fink for macOS. We recommend using Miniconda.

special depends on existing packages from the Python ecosystem, such as numpy, scipy, matplotlib, pandas and astropy. There are different ways of installing special suitable for different scenarios.

Using pip

The easiest way to install special is through the Python Package Index, aka PyPI, with the pip package manager. Simply run:

$ pip install special

With pip you can easily uninstall, upgrade or install a specific version of special. For upgrading the package run:

$ pip install --upgrade special

Alternatively, you can use pip install and point to the GitHub repo:

$ pip install git+https://github.com/VChristiaens/special.git

Using the setup.py file

You can download special from its GitHub repository as a zip file. A setup.py file (setuptools) is included in the root folder of special. Enter the package’s root folder and run:

$ python setup.py install

Using Git

If you plan to contribute or experiment with the code you need to make a fork of the repository (click on the fork button in the top right corner) and clone it:

$ git clone https://github.com/<replace-by-your-username>/special.git

If you do not create a fork, you can still benefit from the git syncing functionalities by cloning the repository (but will not be able to contribute):

$ git clone https://github.com/VChristiaens/special.git

Before installing the package, it is highly recommended to create a dedicated conda environment to not mess up with the package versions in your base environment. This can be done easily with (replace spec_env by the name you want for your environment):

$ conda create -n spec_env python=3.9 ipython

Note: installing ipython while creating the environment with the above line will avoid a commonly reported issue which stems from trying to import special from within a base python2.7 ipython console.

To install special, simply cd into the special directory and run the setup file in ‘develop’ mode:

$ cd special
$ python setup.py develop

If cloned from your fork, make sure to link your special directory to the upstream source, to be able to easily update your local copy when a new version comes out or a bug is fixed:

$ git add remote upstream https://github.com/VChristiaens/special.git

Loading special

Finally, start Python or IPython and check that you are able to import special:

import special

Now you can start characterizing exoplanets and other (sub)stellar objects!

About special

Contributions

Feel free to fork the repository and submit a pull request with either new features or bug fixes. External contributions are very welcome. In particular, please check the expected future areas for development.

Questions and suggestions

special was developed by Valentin Christiaens. Feel free to contact me at [e-mail] if you have any question or suggestion.

Acknowledgements

Please cite Christiaens et al. (2021) if you use special for your research, along with:

• Foreman-Mackey et al. (2013) if you use the emcee MCMC sampler;

• Skilling (2004), Mukherjee et al. (2006), or Feroz et al. (2009) if you use the nested sampler in ‘classic’, ‘single’ or ‘multi’ mode, respectively. Please also mention the nestle GitHub repository.