Source code for galpak.lib.galaxy_parameters

# coding=utf-8
import numpy
from math import isnan
from string_stdout import StringStdOut
from ansi_colors import AnsiColors
from galaxy_parameter import GalaxyParameter
import logging

try:
    import asciitable
except ImportError:
    logging.error('Please install asciitable.')


[docs]class GalaxyParameters(numpy.ndarray): """ A simple wrapper for an array of galaxy parameters. It is basically a flat numpy.ndarray of a bunch of floats with convenience attributes for explicit (and autocompleted!) access and mutation of parameters, and nice casting to string. .. warning:: Undefined parameters will be NaN, not None. Example : :: from galpak import GalaxyParameters gp = GalaxyParameters(x=1.618) // Classic numpy.ndarray numeric access assert(gp[0] == 1.618) // Autocompleted and documented property access assert(gp.x == 1.618) // Convenience dictionary access, assert(gp['x'] == 1.618) // ... useful when you're iterating : for (name in GalaxyParameters.names): print gp[name] Parameters : - x (pix) - y (pix) - z (pix) - flux - radius aka. r½ (pix) half-light radius in pixel - inclination (deg) - pa (deg) position angle from y-axis, anti-clockwise. - turnover_radius aka. rv (pix) turnover radius for arctan, exp, velocity profile [is ignored for mass profile] - maximum_velocity aka. Vmax (km/s) de-projected V_max [forced to be positive, with 180deg added to PA] - velocity_dispersion aka. s0 (km/s) Note that all the parameters are lowercase, even if they're sometimes displayed mixed-case. Additional attributes : - stdev : Optional stdev margin (GalaxyParametersError). GalPaK3D fills up this attribute. """ # HOW TO CHANGE THE PARAMETERS # # Say we want to add a new galaxy parameter named `sugar` : # 1. Update the list `GalaxyParameters.names`, add 'sugar' at the end. # 2. Add the property # sugar = GalaxyParameter(name='sugar', key=10, doc="Some more sugar", unit="sweetness", precision="3.2f") # - name (string) : the name of the variable, that MUST be the same as # the name in `GalaxyParameters.names` # - key (int) : the position in the the ndarray of this parameter. # - short (string) : a shorter name, for compact display. # - doc (string) : some documentation that will appear to the enduser. # - unit (string) : the unit, if any. # - precision (string) : the precision to use during string casting, # as used by `string.format()`. # 3. Update this class' __init__() method (signature and assignation) # 4. Update this class' __new__() method (signature and call to __init__) names = [ 'x', 'y', 'z', 'flux', 'radius', 'inclination', 'pa', 'turnover_radius', 'maximum_velocity', 'velocity_dispersion', ] x = GalaxyParameter(name='x', key=0, doc="X coordinates of the center.", unit="pixel") y = GalaxyParameter(name='y', key=1, doc="Y coordinates of the center.", unit="pixel") z = GalaxyParameter(name='z', key=2, doc="Z coordinates of the center.", unit="pixel", precision='3.6f') flux = GalaxyParameter(name='flux', key=3, precision='3.2e', doc="Sum of the values of all pixels.", unit="same units as the input Cube") radius = GalaxyParameter(name='radius', short="r½", key=4, unit="pixel", doc="Radius (half-light) of the galaxy.") inclination = pitch = GalaxyParameter(name='inclination', short="incl", key=5, unit="deg", doc="Inclination, aka. pitch along observation axis.") pa = PA = roll = GalaxyParameter(name='pa', short="PA", key=6, unit="deg", doc="Position Angle, anti-clockwise from Y (in degrees)," "aka. roll along observation axis.") turnover_radius = rv = GalaxyParameter(name='turnover_radius', short='rv', key=7, unit="pixel", doc="The turnover radius, inverse factor rv in arctan(r/rv).") maximum_velocity = max_vel = GalaxyParameter(name='maximum_velocity', short="Vmax", key=8, unit="km/s", doc="De-projected maximum velocity." "Positive only, with 180deg added to PA.") velocity_dispersion = sigma0 = GalaxyParameter(name='velocity_dispersion', short="Vdisp", key=9, unit="km/s", doc="Spatially constant disk dispersion," "added to kinematics dispersion.") # Developer notes : # There are many ways of doing the above : # - decorators : @property, @prop.setter, etc. # - __getattr__() and __setattr__() # - __getattribute__() and __setattribute__() # - explicit property() # We are using an extension of property() as it provides a cleaner way # to reuse getters and setters with multiple property names, # and provides autocompletion and customized docstrings. # Python dir() function is useful with __getattr__() and the likes, yet not # enough for proper documentation, and function wrappers are just horrible. # Another implementation of a similar feature : # https://github.com/numpy/numpy/blob/master/numpy/core/records.py ## CONSTRUCTORS stdev = None #standard deviation #confidence intervals ICpercentile = None lower = None upper = None """ Optional stdev margin (GalaxyParametersError) lower / upper bounds for a given percentile """ def __init__(self, x=None, y=None, z=None, flux=None, radius=None, inclination=None, pa=None, turnover_radius=None, maximum_velocity=None, velocity_dispersion=None): self.x = x self.y = y self.z = z self.flux = flux self.radius = radius self.inclination = inclination self.pa = pa self.turnover_radius = turnover_radius self.maximum_velocity = maximum_velocity self.velocity_dispersion = velocity_dispersion def __new__(cls, x=None, y=None, z=None, flux=None, radius=None, inclination=None, pa=None, turnover_radius=None, maximum_velocity=None, velocity_dispersion=None): obj = super(GalaxyParameters, cls).__new__(cls, shape=len(GalaxyParameters.names), dtype=float) obj.__init__( x, y, z, flux, radius, inclination, pa, turnover_radius, maximum_velocity, velocity_dispersion ) return obj ## NAMED CONSTRUCTORS (FACTORIES) @staticmethod
[docs] def from_ndarray(a): """ Factory to easily create a GalaxyParameters object from an ordered ndarray whose elements are in the order of `GalaxyParameters.names`. Use like this : :: from galpak import GalaxyParameters gp = GalaxyParameters.from_ndarray(my_ndarray_of_data) :rtype: GalaxyParameters """ required_number_of_values = len(GalaxyParameters.names) if numpy.size(a, 0) < required_number_of_values: raise ValueError("Provide an array of at least %d floats (nan is allowed)" % required_number_of_values) return GalaxyParameters(*a)
def save_to_file(self, filename, clobber=False, delimiter='|'): """ filename: file to save parameters clobber: True/False to overwrite file """ if not clobber and os.path.isfile(filename): raise IOError("The file '%s' already exists. Specify clobber=True to overwrite it.") else: out = filename if self.stdev is not None and (self.lower is None or self.upper is None): asciitable.write([self, self.stdev], output=out, names=self.names, Writer=asciitable.FixedWidth) elif self.stdev is not None and not(self.lower is None or self.upper is None): asciitable.write([self, self.stdev, self.lower, self.upper], output=out, names=self.names, Writer=asciitable.FixedWidth) else: asciitable.write([self], output=out, names=self.names, Writer=asciitable.FixedWidth) def from_file(self, filename, delimiter='|'): """ Reads the content from output.dat of GalaxyParameters """ try: m = asciitable.read(filename, delimiter=delimiter, Reader=asciitable.FixedWidth) p = m.shape[0] if p >= 2: self.stdev = GalaxyParameters() if p >= 3: self.lower = GalaxyParameters() if p >= 4: self.upper = GalaxyParameters() for k in self.names: self.__setitem__(k,m[k][0]) if p >= 2: self.stdev.__setitem__(k,m[k][1]) if p >= 3: self.lower.__setitem__(k,m[k][2]) if p >= 4: self.upper.__setitem__(k,m[k][3]) except ImportError: raise ImportError("Need atpy module for this") ## MAGIC METHODS def __getitem__(self, key): """ Support for dictionary-like accessors, like x = gp['x']. This has a (tiny) performance cost. """ if isinstance(key, str): try: return self[self.names.index(key)] except ValueError: raise ValueError("Property '%s' is not available. Use one of %s" % (key, self.names)) else: return super(GalaxyParameters, self).__getitem__(key) def __setitem__(self, key, value): """ Support for dictionary-like mutators, like gp['x'] = x This has a (tiny) performance cost. """ if isinstance(key, str): try: return super(GalaxyParameters, self).__setitem__(self.names.index(key), value) except ValueError: raise ValueError("Property '%s' is not available. Use one of %s" % (key, self.names)) else: return super(GalaxyParameters, self).__setitem__(key, value) def __str__(self): return self.short_info() def __repr__(self): return self.long_info() ## STRING CASTING
[docs] def short_info(self): """ Casts to single-line string. This is called by ``print()``. Looks like this : x=0.00 y=1.00 z=2.000000 flux=3.00e+00 r½=4.00 incl=5.00 PA=6.00 rv=7.00 Vmax=8.00 s0=9.00 :rtype: string """ s = '' for name in GalaxyParameters.names: attribute = vars(GalaxyParameters)[name] s += ("{short}={value:%s} " % attribute.precision).format( name=name, short=attribute.short, value=self.__getattribute__(name) ) return s
def colored_info(self, warn): """ Casts to colored single-line string when GalaxyParameters `warn` is 1. The parameter `warn` is a GalaxyParameters object too, but it's values should be either 0 (no warning) or 1 (warning). Looks just like short info, but with additional ANSI characters for color where `warn` flag is 1. :rtype: string """ s = '' for name in GalaxyParameters.names: attribute = vars(GalaxyParameters)[name] s += attribute.short + '=' s += self._wrap_with_warn("{value:%s}" % attribute.precision, warn.__getattribute__(name)).format( name=name, short=attribute.short, value=self.__getattribute__(name) ) s += ' ' return s
[docs] def long_info(self, error_as_percentage=False): """ Casts to multi-line string. This is called by ``repr()``. error_as_percentage: bool When true, will print the stdev margin as a percentage of the value. :rtype: string """ if self.stdev is not None: s = "\n Galaxy Parameters : value (± stdev) [units]" else: s = "\n Galaxy Parameters : value [units]" if self.lower is not None and self.upper is not None: s += "\t [Confidence Interval]" s += '\n' for name in GalaxyParameters.names: prop = vars(GalaxyParameters)[name] value = self.__getattribute__(prop.name) # The name of the property, and its value s += (' {name}: {value:%s}' % prop.precision).format( name=prop.name, value=value ) # The optional stdev margin if getattr(self, 'stdev', None) is not None: error_value = getattr(self.stdev, prop.name, None) if error_as_percentage: error_value = 100 * error_value / value if not isnan(error_value): s += (' ± {error_value:%s}' % prop.precision).format( error_value=error_value ) if error_as_percentage: s += '%' # And, finally, the optional unit if prop.unit is not None: s += " ({unit})".format(unit=prop.unit) if self.lower is not None and self.upper is not None: lower = getattr(self.lower, prop.name, None) upper = getattr(self.upper, prop.name, None) s += '\t CI '+str(self.ICpercentile)+'%:' s += (' [{lower:%s},{upper:%s}] ' % (prop.precision,prop.precision)).format( lower=lower, upper=upper ) s += '\n' return s
def structured_info(self): """ Casts to multiline parsable ``asciitable`` string. Use the ``asciitable.FixedWidth`` reader to easily retrieve the data. This method is used to store the chain into the `<prefix>_chain.dat`. See the tutorials for an example of how to retrieve the data. """ out = StringStdOut() if self.stdev is not None and (self.lower is None or self.upper is None): asciitable.write([self, self.stdev], output=out, names=GalaxyParameters.names, Writer=asciitable.FixedWidth) elif self.stdev is not None and not(self.lower is None or self.upper is None): asciitable.write([self, self.stdev, self.lower, self.upper], output=out, names=GalaxyParameters.names, Writer=asciitable.FixedWidth) else: asciitable.write([self], output=out, names=GalaxyParameters.names, Writer=asciitable.FixedWidth) return out.content @staticmethod def _wrap_with_warn(string, condition): """ Will return string wrapped by WARN color escape sequence if condition is not zero. """ if condition != 0 and not isnan(condition): return AnsiColors.WARNING + string + AnsiColors.ENDC else: return string
class GalaxyParametersError(GalaxyParameters): """ Error margin for GalaxyParameters. We could just use another GalaxyParameters object instead of extending it, but this makes sure that stdev recursion never happens, and it also customizes the casting to string. """ def get_error(self): return None def set_error(self, value): pass stdev = property(get_error, set_error, doc=""" This property is useless. Error margins have no stdev margins. They don't, do they ? """) @staticmethod def from_ndarray(a): """ Factory to easily create a GalaxyParametersError object from an ordered ndarray whose elements are in the order of `GalaxyParameters.names`. Use like this : :: gp = GalaxyParametersError.from_ndarray(my_ndarray_of_data) :rtype: GalaxyParametersError """ required_number_of_values = len(GalaxyParameters.names) if numpy.size(a, 0) < required_number_of_values: raise ValueError("Provide an array of at least %d floats (nan is allowed)" % required_number_of_values) return GalaxyParametersError(*a)