Data request types
A data request describes one kind of data to collect on the observation’s target: one filter of optical images, one radio integration, one radio map. An observation holds one or more requests, and they don’t have to be the same type.
Each request type comes in two parts:
- The request holds the per-request settings (filter, depth, number of samples, frequency windows). Two requests of the same type can differ in all of these.
- The configuration holds the type’s constraints and shared parameters (elevation and Sun limits, field of view, tiling, dithering, brightness models, tracking or mapping pattern). An observation has at most one configuration per type, and it applies to every request of that type.
This page defines what each type contains. For how to add and edit requests in the website, see 3. Data requests; for how requests repeat and group in time (epochs, samples, cohesion, cadence), see Scheduling and repetition.
Request types
Section titled “Request types”The type is named by requestType:
| Type | What it collects | Who adds it |
|---|---|---|
optical_imaging |
Science frames through an optical imager | You |
radio_tracking |
A point-and-integrate radio measurement on the target | You |
radio_mapping |
A raster or daisy scan of a region with a radio dish | You |
optical_imaging_bias_calibration, optical_imaging_dark_calibration, optical_imaging_flat_calibration |
Bias, dark and flat calibration frames | Skynet (see Calibration requests) |
Every request also carries:
| Field | Meaning | Default |
|---|---|---|
sampleCount |
How many samples of this request to take per epoch. Each sample is its own result. See Repetition: epochs and samples. | 1 |
order |
The request’s position in the observation | Required in the API; the editor sets it |
Optical imaging
Section titled “Optical imaging”An optical imaging request asks for images of the target through one filter (or filter combination) to a chosen depth.
Images and series
Section titled “Images and series”An optical request is one of two kinds:
- Images (the default): each sample is one image at the requested depth, scheduled on its own. To reach the depth, the telescope may take several frames and combine them (see Exposure sizing).
- Series (
seriesDurationSecset): each sample is one contiguous run of images on one camera for that many seconds. The camera takes as many images as fit back to back at its cadence (exposure plus readout), so two telescopes can return different image counts for the same request.sampleCountis then the number of series per epoch.
Within a series, every frame is one image. Frames are never combined: the requested depth sizes each frame, capped at the longest single frame that camera allows. When the depth needs more than that, each image falls short of it; with an instrument picked in the editor’s instrument bar, the request’s preview line shows the exposure the depth needs and the cap. Other rules for a series:
- The duration must be positive, and only optical requests take one (the API rejects
seriesDurationSecon other types). - The whole series must fit inside one observing window; the scheduler moves it to a window long enough to hold it.
- Skynet can’t plan a series together with tiling or dithering.
Exposure sizing
Section titled “Exposure sizing”An optical request sizes its exposures in exactly one of three ways:
| Mode | Field | How the exposure is found | Needs a brightness model |
|---|---|---|---|
| Fixed time | exposureTimeSec |
The time you set, used as-is on every telescope | No |
| Target SNR | targetSnr |
Computed per telescope to reach that signal-to-noise on the target | Yes |
| Fraction of full well | targetFullWellFraction |
Computed per telescope so the target reaches that fraction of the camera’s full-well capacity | Yes |
The editor offers Fixed and Target SNR; the fraction-of-full-well mode is API-only.
The API does not reject a request that sets more than one. It uses the first one set, in the order of the table (fixed time, then target SNR, then full-well fraction), and ignores the rest. A request with none set, or with an SNR or full-well target and no brightness model, can’t have its exposure computed, so no telescope can take it.
How each mode turns into frames:
- Fixed time takes one exposure of that length at each pointing (each tile and dither position). It is not split into shorter frames, and the saturation model does not cap it, so a fixed exposure gives different depths on telescopes of different size.
- Target SNR and fraction of full well compute a total exposure for each telescope from the brightness model at the planned time, using that camera’s readout noise, dark current and pixel scale, the site’s seeing, and the sky brightness at that time and pointing. The total is split into frames no longer than the mount can track and no longer than the saturation model allows, up to 100 frames, which together make up the sample’s result.
In every mode, the total exposure is kept between 0.1 s and 6 hours.
Filters
Section titled “Filters”A request names its filters in filterSpecifierIds. Each entry is a filter specifier: either one filter (for example V, lum or h-alpha) or a filter group, which means any one of its member filters will do. When a request lists several specifiers, the telescope uses one filter from each, all in the light path at the same time (for example a color filter plus a neutral-density filter); a request whose combination no filter wheel can provide doesn’t go to that instrument.
The editor picks one filter or one group per request and starts new requests on High Throughput. To image in several filters, use one request per filter.
The filter groups Skynet defines:
| Group | Members |
|---|---|
| High Throughput | clear, open, lum |
| Low Throughput | ND25, ND50, and the H-alpha, H-beta, OIII and SII narrow-band filters |
| Red-band | red, R, r’ |
| Green-band | green, V, g’ |
| Blue-band | blue, B, u’ |
| Narrow-band | The H-alpha, H-beta, OIII and SII filters, in every bandwidth |
| Neutral Density | ND1, ND10, ND25, ND50 |
| Halpha Filters, Hbeta Filters, OIII Filters, SII Filters | That line’s filters, in every bandwidth (3, 5 and 8 nm, plus the unlabeled one) |
| Light Pollution | lo-glow, cls-ccd |
Camera and readout preferences
Section titled “Camera and readout preferences”These narrow which camera readout modes a telescope may use for the request:
| Field | In the editor | Meaning |
|---|---|---|
optimizeFor |
Optimize for | resolution (finest sampling) or readout_speed (shortest dead time), used to choose among acceptable readout modes |
allowSubframe |
Subframe | Let the camera read out only the part of the sensor the field of view needs |
allowBinning |
Binning | Allow binned readout modes, within the configuration’s pixel-scale and sampling limits |
allowFastReadout |
Fast readout | Allow faster, noisier readout modes |
electronicShutter, globalShutter |
API only | Require (or exclude) a camera with that shutter type |
minBitDepth, maxBitDepth, highGain, hdr, rbiFlood |
API only | Restrict readout modes by bit depth, gain, high dynamic range, or RBI flooding |
allowCoadding |
API only | Default on. Off means each result must be a single frame, so the request only goes to telescopes that can reach the depth in one exposure |
The optical configuration
Section titled “The optical configuration”The optical imaging configuration holds the observing constraints (target elevation, Sun elevation, Moon phase and separation), the field of view, tiling, pointing and tracking mode, dithering, and the brightness and saturation models. The editor’s dialog for it is described under In the configuration dialog; brightness models are defined in Targets and brightness models.
Radio tracking
Section titled “Radio tracking”A radio tracking request keeps the dish on the target (or alternates between the target and an off-source position) and integrates.
| Field | Meaning | Default |
|---|---|---|
durationSec |
How long the measurement runs | Required |
spectroscopyWindows |
The frequency windows to record, each a center frequency and bandwidth in MHz | None |
polarization |
any, linear or circular |
None |
minResolutionMhz |
Minimum spectral resolution | None |
maxIntegrationTimeMs |
Maximum integration time per recorded sample, in ms; Skynet picks a default when unset | None |
recordMode |
Backend recording mode: spectrometer, or one of the pulsar modes |
spectrometer |
requireContinuum |
Whether continuum output is required | true |
The radio tracking configuration sets the tracking strategy (on, on_off or off_on), the offset to the off-source position (in beamwidths or degrees), and the minimum target elevation, maximum Sun elevation and minimum Sun separation.
Radio mapping
Section titled “Radio mapping”A radio mapping request sweeps the dish across a region to build a map. The request holds the spectroscopyWindows, polarization and minResolutionMhz, as for radio tracking.
The radio mapping configuration holds the pattern:
- Strategy —
raster(a grid of sweeps, with a size in X and Y and a sweep direction) ordaisy(with a diameter). - Size units and frame — beamwidths or degrees, in an equatorial, ecliptic, galactic, horizontal or topocentric frame.
- Density along and between sweeps.
- Depth — an integration time per point or a continuous slew speed.
- Constraints — minimum target elevation, maximum Sun elevation, minimum Sun separation.
A whole mapping pattern is one task on one telescope; see Results and tasks.
Calibration requests
Section titled “Calibration requests”Bias, dark and flat frames are requested by Skynet, not by observers. For each optical imager, Skynet keeps one long-lived calibration observation running, funded by the telescope’s calibration observing account (see Telescopes). It tops up its bias, dark and flat requests on a regular cadence and keeps them in step with the imager’s calibration settings, so an owner’s change applies to the running calibrations.
A calibration request names the frames it needs (requiredFrames), and may pin the camera and readout mode, a sensor temperature, and an expiry. A dark request adds an exposure time; a flat request adds its filters, a target fraction of full well, and minimum and maximum exposure times.
You don’t add calibration requests to your own observations: the Data Requests step offers only the three science types, and the masters built from Skynet’s calibration frames reduce your frames as they are processed.
Instrument selection
Section titled “Instrument selection”By default an observation may run on any instrument that your observing grants reach and that can take its requests: the instrument has to support the request type, have the filters, and meet the configuration’s constraints. The observation’s instrument access setting narrows that:
instrumentMode |
Meaning |
|---|---|
none (default) |
No restriction; the instrument list is ignored |
include |
Only the listed instruments |
exclude |
Any eligible instrument except the listed ones |
The list is instrumentUids, the instruments’ public UIDs, both in an observation spec (the editor, saved drafts, exports, alert subscriptions and project templates) and in an ObservationCreate body sent directly to the API. In a spec, a UID that no longer names an instrument (for example, one retired since the spec was written) is dropped rather than failing.
In both, the list only takes effect with include or exclude. With the default none, a list you send is ignored and the observation can run anywhere its grants reach. With include and an empty list, no instrument qualifies; the editor warns you to pick at least one instrument or switch back to Any.
Instrument access decides which instruments may take the observation. Whether one instrument must take all of it, or the instrument may change between visits or samples, is the separate instrument assignment setting; see Instrument assignment.
← Targets and brightness models · Scheduling and repetition →