Metadata-Version: 2.1
Name: mimical
Version: 0.3.3
Summary: Intensity modelling for multiply-imaged objects
Author: Struan Stevenson
Author-email: struan.stevenson@ed.ac.uk
Project-URL: GitHub, https://github.com/strusteve/mimical
License-File: LICENSE.txt
Requires-Dist: numpy
Requires-Dist: astropy
Requires-Dist: matplotlib
Requires-Dist: nautilus-sampler
Requires-Dist: pandas
Requires-Dist: corner

**Mimical** (**M**\odelling the **I**\ntensity of **M**\ultiply-**I**\maged **C**\elesti\ **A**\l **L**\ight)


Mimical is an intensity modelling code for multiply-imaged objects, performing simultaenous Bayseian inference of model parameters via the nested sampling algorithm. Mimical currently uses a built-in Sersic submodel, but users can easily bolt-on any other 2D submodel. Mimical supports user defined parameter polynomial or power-law depenency with image wavelength.


**Installation**

Mimical can be installed with pip:

.. code::

    pip install mimical


.. image:: docs/fit_example.png


**Required input**

#. ``images`` - An image array or list of image arrays with elements for each filter.
#. ``filt_list`` - A path string or list of path strings to the filter transmission curve files.
#. ``psfs`` - A PSF image array or list of PSF image arrays with elements for each filter. (Normalised to 1)
#. ``mimical_prior`` - The Mimical prior


**Mimical prior**

Below is an example ``mimical_prior`` for a run using the default Sersic submodel. The first set of element keys must match 
the submodel parameter names. Following this, the next element, named ``psf_pa``, traces the rotation of the PSF.
The final two elements must be named ``rms`` and ``counts_per_flux``.

.. code::

     mimical_prior = {}

     mimical_prior['amplitude'] = ((0, 1), 'Individual')
     mimical_prior['r_eff'] = ((0, 50), 'Polynomial', 1)
     mimical_prior['n'] = ((0.1, 10), 'Polynomial', 1)
     mimical_prior['x_0'] = ((48, 52), 'Polynomial', 0)
     mimical_prior['y_0'] = ((48, 52), 'Polynomial', 0)
     mimical_prior['ellip'] = ((0,0.75), 'Polynomial', 0)
     mimical_prior['theta'] = ((0, np.pi), 'Polynomial', 0)

     mimical_prior['psf_pa'] = ((-180, 180), 'Polynomial', 0)

     mimical_prior['rms'] = ('Infer',)``
     mimical_prior['counts_per_flux'] = (cpf_list, 'Individual')

The ``rms`` parameter traces the RMS noise in the image; this can be fit with Mimical but it is **highly recommended to fix it** in order to reduce dimensionality (see **Fixing parameters**), either by passing it in as a ``float`` / ``array`` / ``list`` of ``floats`` / ``list`` of ``arrays`` of the same length and shape as ``images``, or by selecting the special Mimical prior type ``'Infer'`` which automatically calculates the RMS of the image background as identified by SourceExtractor.

Similarly for ``counts_per_flux``, which allows Mimical to associate poisson uncertainty with the generated model, it is recommended to fix it to a provided quantity (``float`` / ``array`` / ``list`` of ``floats`` / ``list`` of ``arrays`` of the same length and shape as ``images``). This may be challenging to derive, but can be provided by the user with information on the gain, exposure time, etc.


**Optional input and parameters**

* ``submodel`` : 2D submodel used to model the underlying intensity profile.
* ``pool`` : Number of cores to parallelise likelihood calculations to.
* ``oversample_boxlength`` : Width of box about image center to oversample within.
* ``oversample_factor`` : Factor by which to oversample the central box.
* ``sextractor_clean`` : Whether or not to let sextractor clean the input images of contaminants.
* ``sextractor_target_maxdistancepix`` : The distance after which the closest detected source is considered a contaminant. Necessary for images in which the target is undetected.
* ``dilute`` : Whether or not to apply a circular miminum filter over the contamination map to dilute it.
* ``dilute_radius`` : If dilute is 'True', apply minimim filter with radius 'dilute_radius' over the contamination map.
* ``oversample`` : Oversample factor for the entire image or annuli defined by oversample radii.
* ``oversample_radii`` : Radii in which to oversample.




**Fixing parameters**

You can fix any of the parameters in the Mimical prior by setting the first element in the parameter tuple equal to either a float / int / list. For instance, to keep ``x_0`` constant across all images, one would pass a float/int and choose the options ``(float/int, 'Polynomial', 0)``. Or, to supply the ``RMS`` for each image separately, one would pass a list of length N\ :sub:`filters`\  and choose the options ``(list, 'Individual')``. If the user supplies arrays for ``RMS`` and ``counts-per-flux`` in the same shape as the ``images``, the corner plot samples will show the mean of these images for generality, but the full arrays will be parsed in the likelihood function.


**Parallelisation**

Mimical can be parallelised to different cores in one of two ways:

* The likelihood calculations can be parallelised to different cores by using the ``pool`` keyword argument. This is ideal for single object fits.
* When using ``fit_catalogue``, the ``mpi_serial`` keyword arguement can be set to ``True`` for individual object fits to be parallelised to separate cores. With this option enabled, mimical must be run using ``mpirun/mpiexec -n [ncores] python [filename].py``. This is ideal for large catalogue fits.

Running Mimical with both of these options enabled is **untested**.
