lvmsurveysim.target

Defining a target

A Target is defined as a SkyRegion on the sky with a name and additional methods for tiling and plotting. Regions on the sky can be of circular, elliptical, rectangular, or polygonal shape. Internally they are always represented as polygons on the sphere (the edges of the polygon are great circles segments).

While targets and regions can be initialised programatically, it is usually more convenient to define them in a YAML file. For example, the following text defines an elliptical and polygonal region

LMC:
    coords: [79.5135633, -68.5271292]
    region_type: circle
    frame: icrs
    region_params:
        r: 4.0
    priority: 30
    observatory: LCO
    telescope: LVM-160
    max_airmass: 2.00
    min_shadowheight: 1.0
    exptime: 1200
    n_exposures: 9
    min_exposures: 3
    min_moon_dist: 45
    max_lunation: 0.25
    overhead: 1.1
    tiling_strategy: center_first
    group: ["MCs"]

ORION_SPARSE:
    coords: [206.42, -17.74]
    region_type: circle
    frame: galactic
    region_params:
        r: 19.5
    priority: 9
    observatory: BOTH
    telescope: LVM-160
    max_airmass: 1.75
    min_shadowheight: 500.0
    exptime: 900
    n_exposures: 1
    min_exposures: 1
    min_moon_dist: 60
    max_lunation: 1.0
    overhead: 1.1
    tiling_strategy: center_first
    sparse: 5
    group: ["ORI"]

MW1:
coords: [315.0, 0.0]
region_type: rectangle
frame: galactic
region_params:
    width: 150.0
    height: 16.0
    pa: 0
priority: 10
observatory: LCO
telescope: LVM-160
max_airmass: 1.75
min_shadowheight: 1000.0
exptime: 900
n_exposures: 1
min_exposures: 1
min_moon_dist: 60
max_lunation: 1.0
overhead: 1.1
tiling_strategy: lowest_airmass
tiling_union: MW
group: ["MW"]

In all cases we need to define the region_type and the coordinate frame (either icrs or galactic) in which the coordinates are written. For M33 we specify the coords of the centre of the ellipse and define the region_params with the major and minor axis lengths and the parallactic angle. All values must be in degrees. For MW2 we provide a list of coordinates with all the vertices of the polygon. We also define the priority of the target for scheduling (higher priority means it is more likely to be observed) and the telescope we want to use to observe it.

More examples of regions can be seen here.

Targets can then be loaded by calling Target.from_list

m33 = Target.from_list('M33', target_file='my_targets.yaml')

Or we can load all the targets in the file

targets = TargetList(target_file='my_targets.yaml')

If the file is not specified in either case, lvmsurveysim defaults to $LVMCORE_DIR/surveydesign/targets.yaml.

target

lvmsurveysim.target._VALID_FRAMES = ['icrs', 'galactic']

Valid reference frames.

class lvmsurveysim.target.target.Target(*args, **kwargs)

Bases: object

A Region with additional observing information.

A Target object is similar to a SkyRegion but it is named and contains information about what telescope will observe it, its observing priority relative to all other targets, and a set of observing constraints ans strategies to be implemented during scheduling of the target (airmass, lunation, shadow height, tile order, …).

There is a special kind of target not represented internally as a SkyRegion, the fullsky target, which represents a (sparse) grid of tiles on the whole sky.

The Target constructor accepts the following keyword parameters, which are also available as keywords from a list read by from_list. Typically a Target will not be instatiated indivisually. The typical use case will involve the TargetList class which is initialize via a yaml configuration file, the survey ‘target list’.

Parameters

• name (str) – The name of the target.

• priority (int) – The priority at which this target should be observed. Higher numbers mean higher priority.

• telescope (str) – The telescope that will observe the target. Must be a string that matches a telescope entry in the configuration file or a Telescope instance.

• max_airmass (float) – Maximum air mass to observe the given target

• min_shadowheight (float) – Minimum shadow height in km to observe the given target

• exptime (float) – Exposure time of an individual pointing

• n_exposures – Number of individual pointings to reach desired S/N

• min_exposures (int) – Minimum number of exposures to make a “good visit”

• min_moon_dist (float) – Minimum moon distance between target before observations are called off.

• max_lunation (float) – The maximum lunation (fraction of moon illuminated, number between 0 and 1)

• overhead (float) – The overhead factor per exposure quantum for this target’s observing scheme.

• overlap – calculate overlap between this target and others and discard, defaults to true

• tile_union – tile_union that the target belongs to, if any; that is an area of sky that is tiled from a single hexagon grid to ensure gapless tiling of overlapping regions.

• tile_overlap (fraction of tile separation to overlap with neighboring tiles (ignored for sparse targets)) –

• geodesic – geodesic tiling of the full sphere instead of region

• sparse – sparse tiling factor, or depth value (number of subdivisions) in case of geodesic tiling

• group – (list of) group names the target belongs to (e.g. MilkyWay). used for aggregating survey statistics and plotting survey progress.

Variables

region (SkyRegion) – The SkyRegion object associated with this target.

center_first_priorities_()

Return an array with tile priorities according for the center-first tiling strategy.

Tiles are prioritized according to the distance from the region barycenter. Priorities are equal along lines of constant distance from the barycenter, quantized in units of the tile diameter.

Returns

priorities (~numpy.array) – Array of length of number of tiles with the priority for each tile.

density()

Return the tile density of the target.

The tile density is 1 if the target is not sparse, and 1/sparse otherwise.

classmethod from_list(name, targets=None)

Returns an instance of Target from a target list.

Initialises a new Target whose parameters have been previously defined in a target list. Target lists must be YAML files in which each target defines region and the telescope that will observe it, as detailed in Defining a target. For example:

M81:
    coords: [148.888333, 69.0652778]
    region_type: ellipse
    frame: icrs
    region_params:
        a: 0.209722
        b: 0.106958333
        pa: 149
    priority: 1
    observatory: APO {LCO, BOTH}
    telecope: LVM-1m {LVM-160}
    max_airmass: 1.75
    min_shadowheight: 1000.0
    exptime: 900
    n_exposures: 1
    min_exposures: 1
    ...

Parameters

• name (str) – The identifier for the target. Must be defined in the region. list file.

• target_file (str, Path, or None) – The path to the YAML file containing the region list. If None, default to the target list contained in lvmcore.

• Example –

  >>> from lvmsurveysim.target import Target
  >>> m81 = Target.from_list('M81')
  

get_pixarea(pixarea=None, ifu=None, telescope=None)

Gets the size of the tile in square degrees.

get_skyregion()

Return the SkyRegion of the target

get_tile_priorities()

Return an array with tile priorities according to the tiling strategy defined for this target.

Returns

priorities (~numpy.array) – Array of length of number of tiles with the priority for each tile.

get_tiles_from_union(coords, pa)

Select tiles belonging to this target from a list of coordinates.

This method is used to select and assign the tiles belonging to this target from a list of coordinates of a tile union.

Parameters

• coords (array) – Vectors of coordinates and PAs of the tile union before selection. Assumed to be in the ICRS frame.

• pa (array) – Vectors of coordinates and PAs of the tile union before selection. Assumed to be in the ICRS frame.

Returns

coords, pa (~numpy.array) – Vectors of coordinates and PAs remaining in tile union after selection.

in_tile_union_with(other)

Return True if self is a member of the same tile union as other.

is_sparse()

Return True if the Target is sparse.

make_tiles()

Return a list of Tile tile objects for this target. Requires the self.tiles, self.pa and self.tile_priorites arrays to have been calculated using the tile method.

plot(*args, **kwargs)

Plots the region. An alias for .SkyRegion.plot.

plot_tiling(projection='rectangular', ifu=None, frame=None, fig=None, **kwargs)

Plots the tiles within the region.

Parameters

• ifu (IFU) – The IFU used for tiling the region. If not provided, the default one is used.

• frame (str) – The reference frame on which the pixels will be displayed. Defaults to the internal frame of the target.

• ax (Axes) – A Matplotlib Axes object to use. Otherwise, a new one will be created.

• kwargs (dict) – Parameters to be passed to scatter.

Returns

figure (Figure) – The Matplotlib Figure.

classmethod supertarget(targets)

Create a new target from a list of targets forming a tile union.

This method takes a list of targets and returns a new target object whose region is the union of the regions of the targets in the list.

This is used in tiling tile unions, which are multiple distinct targets that overlap or at least share an edge and need to be tiled uniformly across these interfaces. This is achieved by tiling them as if they were a single target and then redistributing the tiles back to the original targets according to their boundaries.

Parameters:

targetslist of Target

list of targets forming a tile union.

Returns:

targetTarget

‘supertarget’ consisiting of the union of the input targets

tile(ifu=None, telescope=None, to_frame=None)

Tessellates the target region and populates the tiles, pa and tile_priorities fields.

Parameters

• ifu (IFU) – The IFU used for tiling the region. If not provided, the default one is used.

• telescope (Telescope) – The telescope on which the IFU is mounted. Defaults to the object telescope attribute.

• to_frame (str) – The reference frame in which the coordinates should be returned. If None, defaults to the region internal reference frame.

transform_skycoords(lat, lon, unit, to_frame)

Construct SkyCoords from a set of longitude and lattitude spherical coordinates. Optionally transform to a different frame and calculate the change of position angle resulting from that transform

The output is a set of SkyCoords and the position angle N through E

Parameters:

lat, lonarray-like

lattitude and longitude input coordinates

unitstr

the unit of lat and lon

to_framestr

optional, the name of a new frame of reference for the output values

Return:

skSkyCoords

output coordinates

paarray

position angle at new coordinates relative to the old coordinates

class lvmsurveysim.target.target.TargetList(targets=None, target_file=None)

Bases: list

A list of all the targets to observe.

Parameters

target_file (str) – The YAML file with all the targets to observe. Defaults to the lvmcore target list.

Returns

target_set (list) – A list of Target instances.

get_group_targets(group, primary=True)

Returns the targets that are in a group.

Parameters

• group (str) – The group name.

• primary (bool) – Return only the target if group is the primary group to which the target belongs (i.e., the first one in the list).

Returns

targets (list) – A list of target names that are included in group.

get_groups()

Returns a list of all the groups for all the targets in the list.

get_target(name)

Returns the target whose name correspond to name.

get_tile_unions()

Returns a list of all the tile unions in the target list.

get_union_targets(tile_union)

Returns the targets that are in a tile union.

Parameters

tile_union (str) – The group name.

Returns

targets (list) – A list of target names that are included in tile_union.

order_by_priority()

Return a copy of the target list ordered by priorities highest to lowest.

plot_tiling(frame='icrs', **kwargs)

Plots all the target pixels in a single Mollweide projection.

Parameters

• frame (str) – The coordinate frame to which all the pixel centres will be converted.

• kwargs (dict) – Parameters to be passed to Target.plot_tiling. By default, each target will be plotted in a different colour.

Returns

figure (Figure) – The Matplotlib Figure.

regions

class lvmsurveysim.target.skyregion.SkyRegion(typ, coords, **kwargs)

Bases: object

This class represents a region on the sky.

This class represents a region on the sky, parameterized either by one of a number of common shapes, or by a set of vertices of a polygon. Internally all shapes are held as polygon object so that the edges of the polygons are great circle segments on a sphere.

The class provides convenience methods to construct such polygons using the Target parameterization from the target yaml file. It also provides methods to compute intersections between the regions and whether a point is contained in the region (used later in tiling).

Parameters

• typ (str) – String describing the shape, one of ‘circle’, ‘ellipse’, ‘rectangle’ ‘polygon’ or ‘raw’. Depending on the value of this parameter, we expect to find further parameters in **kwargs.

• coords (tuple of float) – Center coordinates for ‘circle’, ‘ellipse’, ‘rectangle’ regions, or tuple of vertices for ‘polygon’ in degrees. For ‘raw’, we expect the SphericalPolygon object.

• **kwargs (dict) – Must contain keyword ‘frame’ set to ‘icrs’ or ‘galactic’. For ‘rectangle’ must contain ‘width’ and ‘height’ in degrees and ‘pa’ a position angle (N through E) also in degrees. For ‘circle’ must contain ‘r’ with radius in degrees. For ‘ellipse’ must contain ‘a’, ‘b’, ‘pa’ with semi-axes and position angle in degrees. For ‘raw’ we expect only the ‘frame’ to be passed as a keyword argument.

bounds()

Return a tuple of the bounds of the SkyRegion defined as the minimum and maximum value of the coordinates in each dimension.

centroid()

Return the center coordinates of the SkyRegion

contains_point(x, y)

Return True if the point (x,y) is inside the region, false otherwise.

icrs_region()

Return a copy of the region transformed into the ICRS system.

A deep-copy of the region with vertices transformed into the ICRS system is returned if the region is in any other reference frame.

Returns

SkyRegion with vertices in the ICRS system.

intersects_poly(other)

Return True if the SkyRegion intersects another SkyRegion.

classmethod multi_union(regions)

Return a new SkyRegion of the union of the SkyRegions in regions.

plot(ax=None, projection='rectangular', return_patch=False, **kwargs)

Plots the region.

Parameters

• ax (Axes) – The axes to use. If None, new axes will be created.

• (str) (projection) – The projection to use. At this time, only rectangular and mollweide are accepted.

• (bool) (return_patch) – If True, returns the matplotlib patch for the region.

• (dict) (kwargs) – Options to be passed to matplotlib when creating the patch.

Returns

• Returns the matplotlib fig, ax objects for this plot.

• If not specified, the default plotting styles will be used.

• If return_patch=True, returns the patch instead.

vertices()

Return a array of dimension Nx2 with the N vertices of the SkyRegion.