API reference

LineStacker

Stacking positions (Coord, readCatalog(), makeCoords(), readCoords()), their conversion to pixels, random positions, and the package settings (verbose, casa_logfile). The stacking itself is in LineStacker.image (cubes) and LineStacker.OneD_Stacker (spectra); LineStacker.analysisTools tests stacks.

LineStacker.verbose = True

When True (default), LineStacker reports what it does, the files it writes (with their full path), what it reads, and progress bars. Set LineStacker.verbose = False to silence it; every function that prints also takes verbose=True/False to decide for one call. Warnings about possible problems are shown either way.

LineStacker.casa_logfile = 'auto'

Where CASA writes its log when LineStacker starts CASA itself (only to read or write CASA images; FITS cubes never start CASA):

  • 'auto' (default): one file, <temporary dir>/linestacker-casa-<user>.log, instead of a new casa-<date>.log in the working directory at every run; a logfile set in ~/.casa/config.py is used instead.

  • a path: CASA’s log goes there.

  • None: no log file.

  • 'casa': CASA’s own default (casa-<date>.log in the working directory).

Set it before the first CASA image is read. Inside a CASA session, or once casatools/casatasks were imported, CASA’s own settings apply.

LineStacker.cache_check = True

Cubes are read once and kept in memory. When True (default) LineStacker checks, every time it uses a cached cube, that its file has not changed (about 0.1 ms per CASA image, a few microseconds per FITS file) and reads it again if it has. Set LineStacker.cache_check = False to trust the cache until LineStacker.image.clear_cache().

LineStacker.round_half_up(x)[source]

Round like Python 2’s round() did (halves away from zero). Python 3’s round() rounds halves to even, which would move some stack centres by one channel compared with LineStacker < 2.0.

class LineStacker.Coord(ra, dec, spec='continuum', weight=1, image=0, type='physical', imagenumber=-1, frame='icrs', z=None, index=None)[source]

Describes a stacking position on an image.

Class used internally to represent coordinates. May describe a physical coordinate or a pixel coordinate.

Init: Creates a coordinate. A pixel coordinate should always specify to which image it belongs. Physical coordinates are astropy angles (as produced by LineStacker.readCoords, readCatalog and makeCoords) or plain numbers in radians, in the equatorial frame given by frame (default ICRS).

Parameters:
  • ra – x coordinate of stacking target (RA, or x pixel for pixel coordinates). Also available as coord.x.

  • dec – y coordinate of stacking target (Dec, or y pixel). Also coord.y.

  • spec – spectral coordinate of stacking target (redshift, observed spectral value or channel depending on spectralMethod). Also coord.z.

  • weight – Weight of the source for mean stacking. Default is 1.

  • image – Cube associated to the source, either its path or its index in the list of images given to the stacking function. Automatically set with LineStacker.readCoords.

  • type – Either ‘physical’ or ‘pixel’

  • imagenumber – Index of the cube in the image list (set by readCoords to the index of the coordinate file the source was read from).

  • frame – Equatorial frame of ra, dec: ‘icrs’ (default), ‘fk5’ (J2000), ‘fk4’…

copy()[source]

Independent copy (weights arrays are copied too).

LineStacker.readCoordsNamesGUI()[source]

Opens a file dialog (Tk) to select coordinate files; returns their paths.

LineStacker.readCoords(coordfiles, unit='deg', lineON=True, delimiter='default', frame='icrs', images='default', type='physical', verbose=None)[source]

Reads coordinate files (one file per cube, the format of LineStacker 1.x) and returns a list of LineStacker.Coord.

Parameters:
  • coordfiles – List of path to coordinate files. Files in csv format: x (RA) and y (Dec) in the equatorial frame given by frame. If using to stack line, redshift should be in the third column. A weight may be added in the last column to weight positions for mean stacking. If set to None stacking position is defined as the center of each cube. Coordinates can either be in degrees (e.g. “10.625, 41.2”), or in hour angle + deg, as hms dms format (e.g. “‘00h42m30s’, ‘+41d12m00s’”), or as hour angle + deg without hms nor dms (e.g. “00 42 30, +41 12 00” or CASA’s “00:42:30, +41.12.00”). A plain number is always in unit, also next to a sexagesimal value. Empty lines and lines starting with # are ignored.

  • unit – Unit of plain numbers. Allows two values, ‘deg’ or ‘rad’.

  • lineON – Either True or False, should be set to True if doing line stacking. Default is True.

  • delimiter – Delimiter used to separate coordinates, ‘default’ tries comma, space and tab (in that order). With commas, an empty field in a line (e.g. “x, y, , w”) is an error for line stacking.

  • frame – Equatorial frame of the positions: ‘icrs’ (default), ‘fk5’ (J2000), ‘fk4’…

  • images – List of images to which each coordfile is assigned, if set to ‘default’, image names are same as coordfiles, with ‘.fits’ instead of ‘_coord.txt’. The stacking functions also accept coordinates whose image is not in their imagenames list: the n-th coordinate file is then matched to the n-th image.

  • type – Coordinate type, can be either ‘physical’ (default), or ‘pixel’

  • verbose – report how many positions were read (default: LineStacker.verbose)

LineStacker.makeCoords(ra, dec=None, z=None, weight=None, image=None, unit='deg', frame='icrs', type='physical', verbose=None)[source]

Builds stacking coordinates directly from Python values (lists, numpy arrays, astropy quantities or a SkyCoord), e.g. in a notebook.

Parameters:
  • ra – Positions, one value per source. Numbers are in unit (or pixels if type=’pixel’); astropy Angles/Quantities carry their own unit; strings are sexagesimal with RA in hours (‘03:31:04.15’, ‘-27:40:59.87’, or CASA’s ‘-027.40.59.866’). A SkyCoord can be given as ra, with dec=None.

  • dec – Positions, one value per source. Numbers are in unit (or pixels if type=’pixel’); astropy Angles/Quantities carry their own unit; strings are sexagesimal with RA in hours (‘03:31:04.15’, ‘-27:40:59.87’, or CASA’s ‘-027.40.59.866’). A SkyCoord can be given as ra, with dec=None.

  • z – Spectral value of each source: the redshift for spectralMethod=’z’ (the default of LineStacker.image.stack), the observed frequency/wavelength for ‘obsSpec’, the channel for ‘channel’. None for continuum stacking.

  • weight – Weight of each source for mean stacks (default 1).

  • image – Cube of each source (path to a FITS file or CASA image), or one path for all sources. None when all sources lie in the single cube given to the stacking function.

  • unit – ‘deg’ (default) or ‘rad’, for plain numbers.

  • frame – Equatorial frame of the positions: ‘icrs’ (default), ‘fk5’ (J2000), ‘fk4’… A SkyCoord in any frame (e.g. Galactic) is converted to it.

  • type – ‘physical’ (sky positions, default) or ‘pixel’.

Returns:

list of LineStacker.Coord – to give to LineStacker.image.stack (imagenames can then be omitted when every source names its cube).

LineStacker.readCatalog(catalog, ra='ra', dec='dec', z='z', weight='weight', image='image', unit='deg', frame='icrs', imagedir=None, format=None, verbose=None)[source]

Reads the stacking positions of all sources from one catalogue table, one row per source. The cube of each source is given in the table (image column); it is never guessed.

Parameters:
  • catalog – Path to a table file: CSV (with a header line), ECSV, FITS table, VOTable or any format astropy.table reads (see format). Also accepted: an astropy Table, a pandas DataFrame or a dict of columns.

  • ra – Column names of the positions (default ‘ra’, ‘dec’; also found: RAJ2000/DEJ2000, ra_deg/dec_deg…). Numbers are in unit unless the column has a unit (FITS, ECSV, VOTable); strings are sexagesimal with RA in hours (CASA’s ‘-027.40.59.866’ accepted).

  • dec – Column names of the positions (default ‘ra’, ‘dec’; also found: RAJ2000/DEJ2000, ra_deg/dec_deg…). Numbers are in unit unless the column has a unit (FITS, ECSV, VOTable); strings are sexagesimal with RA in hours (CASA’s ‘-027.40.59.866’ accepted).

  • z – Column of the spectral value (default ‘z’, also ‘redshift’): the redshift, or the observed frequency/wavelength or channel for spectralMethod ‘obsSpec’/’channel’. If the catalogue has no such column (or z=None) the positions are for continuum stacking.

  • weight – Column of the weights (optional, default 1).

  • image – Column naming the cube of each source (FITS file or CASA image; default ‘image’, also ‘cube’, ‘file’). Relative paths are looked up next to the catalogue first, then from the working directory. Without this column, give the stacking function a single cube.

  • unit – ‘deg’ (default) or ‘rad’, for unit-less numeric positions.

  • imagedir – Folder to which relative cube names are relative (overrides the rule above).

  • format – astropy table format, e.g. ‘ascii.csv’, ‘ascii.commented_header’ (default: guessed from the file).

  • verbose – report what was read (default: LineStacker.verbose)

Returns:

list of LineStacker.Coord – for LineStacker.image.stack and the analysis tools; imagenames can be omitted there when the catalogue has an image column.

LineStacker.getPixelCoords(coords, imagenames=None, hdul='auto')[source]

Creates pixel coordinate list from a physical coordinate list and a list of images.

Parameters:
  • coords – A list of LineStacker.Coord coordinates.

  • imagenames – A list of images’ paths (FITS files or CASA images). Optional when every coordinate names its cube (readCatalog, makeCoords).

  • hdul – index of the FITS HDU holding the cube; ‘auto’ (default) uses the first HDU containing an image (HDU 0 for ALMA/CASA FITS, 1 for MUSE).

Returns:

list of LineStacker.Coord – new coordinates of type ‘pixel’; the original coordinates are not modified. Each new coordinate’s index is the position of the original in coords.

LineStacker.randomCoords(imagenames, ncoords=10, hdul='auto', margin=0, rng=None)[source]

Random positions anywhere in a set of images: pixel coordinates whose spec is a random channel of their cube, to be stacked with spectralMethod=’channel’.

Parameters:
  • imagenames – A list of images paths (or one path).

  • ncoords – Number of random coordinates. Default is 10.

  • margin – Minimal distance (pixels) to the image edges, e.g. half the stampsize.

  • rng – numpy Generator or seed, for reproducible draws.

LineStacker.randomizeCoords(coords, beam, maxBeamRange=5, imagenames=None, hdul='auto', rng=None, maxTries=100)[source]

New positions at a random distance between beam and maxBeamRange*beam from each of the original coordinates (random direction). See also LineStacker.analysisTools.randomizeCoords, which takes the limits in radians.

Parameters:
  • coords – list of original coordinates (LineStacker.Coord instances)

  • beam – beam size in radians, new random coordinates will be at a minimum distance beam from the original coordinates.

  • maxBeamRange – maximum distance from original coordinates at which new coordinates can be located, in units of beams. Default is 5.

  • imagenames – images the coordinates refer to; when given, new positions are kept inside their image.

  • rng – numpy Generator or seed, for reproducible draws.

LineStacker.image

Stacking in the image domain: spectral lines in data cubes, or continuum.

Inputs are FITS files or CASA images (CASA images need casatools), and can be mixed. Line stacking extracts a sub-cube around each source, centred on its line; continuum stacking (continuum=True) stacks images. Cubes without a spectral axis (or with a single channel) are always stacked as continuum; cubes with a spectral axis are collapsed in memory when continuum stacking is asked for (with a warning).

What the stacked cube is:

  • Stamps are cut on each cube’s own pixel grid, centred on the source; cubes are not reprojected. Cubes whose pixels differ in size or orientation, or whose projection, celestial frame or distortions differ, from the first cube’s give a warning: reproject them first (e.g. CASA imregrid) to use the stacked image spatially.

  • The output sky axes are offsets from the stacked position, (0, 0) at the stamp centre, with the first cube’s pixel size and orientation.

  • All cubes must have the same kind of spectral axis (FREQ, WAVE, AWAV, VRAD…); units are converted to those of the first cube, in which fEm, lEm and observed spectral values are given. Non-linear spectral axes are refused for line stacks. Different spectral reference frames (SPECSYS) give a warning: LineStacker does not convert frames.

  • The beam in the header (BMAJ, BMIN, BPA) is the mean of the input beams, an approximation of the stack’s effective beam when they differ.

  • Blank pixels (NaN) stay NaN and are left out pixel by pixel; stacked pixels without any valid data are NaN.

  • Pixel units (BUNIT) are compared: scaled units are converted to the first cube’s (mJy/beam to Jy/beam), recognised but physically different ones are refused, unrecognised ones give a warning.

  • A continuum stack of collapsed cubes keeps BUNIT, which is then per channel (‘sum’ adds channels); the COLLAPSE keyword says how.

LineStacker.image.stack(coords, outfile='stackResult.fits', stampsize=32, imagenames=None, method='mean', spectralMethod='z', weighting=None, returnWeights=False, maskradius=0, fEm=-1, lEm=-1, N_chans='default', plotIt=False, regridFromZ=False, regridMethod='scaleToMax', conserveFlux=True, saveSubCubes=False, hdul='auto', continuum=False, collapse='sum', primarybeam=None, verbose=None)[source]

Performs line (or continuum) stacking in the image domain.

Parameters:
  • coords – A list of LineStacker.Coord (see LineStacker.readCatalog, LineStacker.makeCoords, LineStacker.readCoords). Set to None to stack the centre of every cube.

  • outfile – Target name for stacked image. Names ending in .fits are written as FITS, other names (e.g. ‘stackResult.image’) as CASA images (needs casatools). None to skip writing.

  • stampsize – size of target image in pixels

  • imagenames – Cubes or images to extract flux from: FITS files or CASA images (both can be mixed), in the same order as the coordinate files. Can be omitted when every coordinate names its cube (readCatalog with an image column, makeCoords(image=…)). All cubes must have the same kind of spectral axis (e.g. all FREQ); different units (Hz, GHz) are converted to those of the first cube. Stamps are cut on each cube’s own pixel grid: cubes with other pixel sizes or orientations are not reprojected (a warning says so).

  • method – ‘mean’ (weighted) or ‘median’ (over the sources covering each channel; weights are ignored)

  • spectralMethod –

    What the spectral value of each coordinate (its z, the 3rd column of a coordinate file) is. Possible methods are:

    ’z’: the redshift of the observed line, if used fEm (emission frequency) or lEm (emission wavelength) must be informed as an argument of this Stack function.

    ’obsSpec’: the (observed) central frequency, wavelength or velocity, in the spectral unit of the first cube.

    ’channel’: the channel number (0-based) of the line.

  • weighting –

    used if method set to ‘mean’, possible values are:

    ’sigma2’: weight times 1/sigma**2, sigma being the standard deviation of the source’s stamp (pixels outside maskradius, blank pixels excluded)

    ’sigma2F’: the same, computed channel by channel

    ’1/A’, /!\ only use if lines are visible pre-stacking: weight divided by the line amplitude (maximum of the central-pixel spectrum; sources with a non-positive amplitude get weight 0)

    ’sigma’: weight times 1/sigma (sigma as for ‘sigma2’; if maskradius is 0 the mask radius is twice the beam major axis)

    ’pb’: weight times the squared primary-beam response at each source (needs primarybeam); for primary-beam corrected images this is inverse-variance weighting

    None: the weights of the coordinates (1 by default).

    Each weighting multiplies the coordinates’ own weights. Weights must be finite and >= 0.

  • returnWeights –

    If true weights of each source are written in outfile “weightFile.csv” in format: coord.ra, coord.dec, coord.z, coord.weight.

    If multiple weights exist for one source (for each spectral channel) all are written.

  • maskradius – allows blanking of centre pixels in weight calculation

  • fEm – rest emission frequency of the line, should be used if spectralMethod = ‘z’ and spectral axis of image cube is in frequency (in the unit of the first cube, usually Hz).

  • lEm – rest emission wavelength of the line, should be used if spectralMethod = ‘z’ and spectral axis of image cube is in wavelength (in the unit of the first cube, e.g. Angstrom for MUSE).

  • N_chans – number of channels of the resulting stack, default is number of channels in the first image.

  • plotIt – direct plot option

  • regridFromZ – if set to True each source’s spectrum is resampled (linear interpolation) so that all sources share the same rest-frame channel width, correcting the redshift dependence of observed line widths. Requires spectralMethod=’z’.

  • regridMethod – Used if regridFromZ is True. Can be set either to ‘scaleToMin’ or ‘scaleToMax’. The common rest-frame channel is the one of the source with the smallest (‘scaleToMin’) or highest (‘scaleToMax’) redshift. ‘scaleToMax’ (default) makes the channels of the other sources wider, ‘scaleToMin’ narrower.

  • conserveFlux – Used if regridFromZ is True, for the sources whose channels are made wider (‘scaleToMax’). True (default): a new channel is the mean of the cube channels it covers (partly covered ones by their fraction): all the data are used, and the integrated flux of each source is kept exactly; the line peak is that of the wider channel. False: a new channel takes the value of the spectrum at its centre, so the cube channels in between are not used (LineStacker 1.x and 2.0.0). Channels made narrower are interpolated either way.

  • saveSubCubes – If set to True (or to str) sub cubes will be saved as a numpy file. (outSubCubes.npy if set to True, user defined is set to str)

  • hdul – index of the FITS HDU holding the cube; ‘auto’ (default) picks the first HDU containing an image.

  • continuum – If True, stack continuum images instead of lines (spectralMethod, fEm, lEm, N_chans and regridFromZ are then not used). Continuum stacking is also used automatically when no image has a spectral axis (or only one channel), and when the coordinates carry no spectral value (readCoords(…, lineON=False)). Cubes with a spectral axis are then collapsed in memory (with a warning), see collapse.

  • collapse – How cubes are collapsed for continuum stacking: ‘sum’ (default), ‘mean’ or ‘median’ over channels. Blanked channels are ignored.

  • primarybeam – Used by weighting=’pb’: the primary-beam image of each cube (FITS or CASA, e.g. tclean’s .pb), as one path for a single cube, a list in the order of imagenames or a dict {cube: pb image}; the response is read at each source’s position (and line channel). Or a function f(dx, dy, nu) returning the response at offsets dx, dy (radians, east and north on the sky) from the image reference pixel and frequency nu (Hz, None without a frequency axis), e.g. GaussianPrimaryBeam(dish=12.). Entries of a list or dict can also be functions.

  • verbose – If True, print the path of every file written (stacked cube, weights, sub-cubes). Default: LineStacker.verbose (True unless changed).

Returns:

list – [central pixel at the central channel, spectrum of the central pixel, stacked cube (x, y, stokes, channel), number of sources missing from each channel]. For a continuum stack the spectrum has one channel.

class LineStacker.image.GaussianPrimaryBeam(dish=12.0, factor=1.13, nu0=None)[source]

Gaussian primary beam (power pattern) of a dish, for weighting=’pb’: response exp(-4 ln2 r**2 / FWHM**2) with FWHM = factor * c / (nu * dish), r being the offset from the image reference pixel (the pointing centre of single-pointing images). factor=1.13 is the ALMA 12 m value, as in LineStacker.uv.

Parameters:
  • dish – dish diameter in metres (default 12)

  • factor – FWHM in units of lambda/D (default 1.13)

  • nu0 – frequency (Hz) to use for images without a frequency axis

fwhm(nu)[source]

FWHM in radians at frequency nu (Hz).

LineStacker.image.readCube(imagename, hdul='auto', collapse=None)[source]

Reads a cube or image (FITS file or CASA image) as a numpy array ordered (x, y, stokes, channel), x along RA and y along Dec, as LineStacker uses it. Blank pixels are NaN.

Parameters:
  • imagename – path of the FITS file or CASA image

  • hdul – FITS HDU holding the data (‘auto’: first HDU with an image)

  • collapse – None (default) for the full cube, or ‘sum’, ‘mean’, ‘median’ to collapse the spectral axis (blank channels ignored).

LineStacker.image.clear_cache()[source]

Forget the cubes read so far: LineStacker reads each cube once and keeps it in memory for the following stacks and analysis tools (a cube is read again when its file changes). This frees that memory.

LineStacker.image.getFlux(imagename, hdul='auto')[source]

Pixel value at the reference pixel of an image, e.g. the centre of a stacked image (first Stokes plane and channel).

LineStacker.OneD_Stacker

Stacking of 1D spectra: each spectrum is a Spectrum, which knows where its line is; Stack() aligns the spectra on their lines and averages them channel by channel. Velocities are in km/s.

class LineStacker.OneD_Stacker.Spectrum(spectrum=None, amp=None, velocities=None, frequencies=None, z=None, fEmLine=False, centerIndex=None, centralVelocity=None, centralFrequency=None, weights=1, name='', fit=False, velOrFreq='vel', velConvention='radio')[source]

One spectrum to stack: its fluxes, optionally its spectral values, and where its line is.

Parameters:
  • spectrum – Spectrum should be of the shape [N,2] or [2,N], where N is the number of spectral bins. The second dimension being the flux and the first the spectral values, which must be evenly spaced (increasing or decreasing; within 5% of a channel).

  • amp – Instead of defining spectrum one can define only the amplitude (flux).

  • velocities – In the case where amp is defined it is still possible to define the velocities

  • frequencies – In the case where amp is defined it is still possible to define the frequencies

  • z – Redshift, one of the possible way to define central frequency. If using redshift fEmLine (emission frequency of the line) should be defined. In addition the spectrum should consist of BOTH amplitudes and spectral information (frequencies or velocities), and not amplitude alone. Velocities are then in km/s relative to the rest frequency fEmLine (as e.g. a CASA spectrum with restfreq=fEmLine), in the convention velConvention: the line is at v = c z/(1+z) (radio), c z (optical) or c((1+z)**2-1)/((1+z)**2+1) (relativistic).

  • fEmLine – Emission frequency of the line, needed if redshift argument is used.

  • centerIndex – channel index of the line center, another possible way to define line center.

  • centralFrequency – (observed) Frequency of the line center, another possible way to define line center.

  • centralVelocity – Observed velocity of the line center, another possible way to define line center.

  • weights –

    The weighting scheme to use.

    Can be set to ‘1/A’ or ‘sigma2’. If sigma2 is used std of the entire spectra is used UNLESS, fit is set to True, in which case the central part around the line is excluded from std calculation (central here means one FWHM on each side of the center of the line).

    Alternatively user input can be used, float or list (or array)

  • name – name of the spectrum, can allow easier identification

  • fit – If fit is set to True, the spectrum will be fitted with a gaussian to try and identify the line center (as well as amplitude if weight is set to 1/A)

  • velOrFreq – Defining if spectral dimension is velocity or frequency.

  • velConvention – Velocity convention of the velocities (km/s), used with z: ‘radio’ (default, as CASA and LineStacker.uv), ‘optical’ or ‘relativistic’.

velToFreq(vel, z, fEmLine)[source]

Frequency of the velocity vel (km/s) relative to the frequency fEmLine/(1+z) (z=0: the rest frequency), in the spectrum’s velConvention. Same unit as fEmLine.

freqToVel(freq, z, fEmLine)[source]

Velocity (km/s) of the frequency freq relative to fEmLine/(1+z) (z=0: the rest frequency), in the spectrum’s velConvention.

LineStacker.OneD_Stacker.velocity_to_frequency(vel, fRef, convention='radio')[source]

Frequency (unit of fRef) of velocities vel (km/s) relative to fRef: radio f = fRef (1 - v/c), optical f = fRef / (1 + v/c), relativistic f = fRef sqrt((1 - v/c) / (1 + v/c)).

LineStacker.OneD_Stacker.frequency_to_velocity(freq, fRef, convention='radio')[source]

Velocity (km/s) of frequencies freq relative to fRef (inverse of velocity_to_frequency).

LineStacker.OneD_Stacker.set_centers(spectra, center='fit')[source]

Sets the line centre (centerIndex) of every spectrum, in place, with a centring method of Stack.

Stack and the analysis tools centre copies of the spectra and leave their centerIndex unchanged (earlier versions, 1.x included, set it). Use set_centers to keep the centres a method finds, for later stacks with the default center=’lineCenterIndex’.

Parameters:
  • spectra – List of spectra (LineStacker.OneD_Stacker.Spectrum objects).

  • center – ‘fit’ (default), ‘zero_vel’, ‘center’ or a channel number, as for Stack.

Returns:

list of int – the new centerIndex of each spectrum.

LineStacker.OneD_Stacker.Stack(spectra, chansStack='full', method='mean', center='lineCenterIndex', regridFromZ=False, regridMethod='scaleToMin', verbose=None, conserveFlux=True)[source]

Stacks spectra (LineStacker.OneD_Stacker.Spectrum objects), aligned on their lines: weighted mean or median, channel by channel.

Parameters:
  • spectra – List of spectra (LineStacker.OneD_Stacker.Spectrum objects).

  • chansStack – Number of channels to stack. Set to ‘full’ to stack all channels from all spectra. User input (int) otherwise

  • method – stacking method, ‘mean’ and ‘median’ supported

  • center –

    Method to find central frequency of the stack, possible values are:

    ”center”, to stack all spectra center to center,

    ’fit’ to use gaussian fitting on the spectrum to determine line center,

    ’zero_vel’ to stack on velocity=0 bin,

    ’lineCenterIndex’ use the line center initiated with the spectrum,

    Or directly defined by the user (int)

  • regridFromZ – if set to True spectra will be regridded to take into account the redshift difference of the different sources. See LineStacker.analysisTools.regridFromZ1D for a more complete description.

  • regridMethod – Used if regridFromZ is True. Can be set either to ‘scaleToMin’ or ‘scaleToMax’. In the first case all spectra are regridded to match the smallest redshift (over-gridding), all spectra are regridded to match the highest redshift in the other case (under-gridding).

  • verbose – report the regridding (default: LineStacker.verbose)

  • conserveFlux – Used if regridFromZ is True with regridMethod=’scaleToMax’ (channels made wider). True (default): a new channel is the mean of the channels it covers; False: it takes the value of the spectrum at its centre (LineStacker 1.x and 2.0.0). See LineStacker.analysisTools.regridFromZ1D.

Returns:

  • tuple – (stacked spectrum, number of spectra in each channel). Channels without valid data (no spectrum covers them, or only blank fluxes or zero weights) are NaN.

  • The spectra given are not modified (the centring works on copies, so)

  • each spectrum keeps its own centerIndex for later stacks (use

  • set_centers to store the centres a method finds).

LineStacker.analysisTools

Tools to test stacks and prepare data for stacking: bootstrapping, subsampling, stacks at random positions, noise estimates, rebinning and regridding of lines of different widths and redshifts.

The Monte-Carlo tools (bootstraping_OneD, bootStraping_Cube, subsample_OneD, stack_estimator) accept n_jobs (number of CPU cores, -1 for all), backend (‘process’ or ‘thread’, see LineStacker.tools.parallel), seed and verbose. All random draws happen before the work is split, so results do not depend on n_jobs. With seed=None the draws come from numpy’s global random state, so np.random.seed() still makes runs reproducible.

LineStacker.analysisTools.bootstraping_OneD(spectra, nRandom=1000, chansStack='full', method='mean', center='lineCenterIndex', save='all', seed=None, n_jobs=1, backend=None, verbose=None)[source]

Bootstrapping of a 1D stack: stacks of random draws, with replacement, of the spectra. See LineStacker.OneD_Stacker.Stack for the stacking parameters.

Parameters:
  • spectra – a list of LineStacker.OneD_Stacker.Spectrum objects

  • nRandom – number of bootstrap iterations

  • chansStack – number of channels to stack, either a fixed number or ‘full’ for entire spectra

  • method – stacking method, ‘mean’ or ‘median’

  • center – Method to center spectra. See LineStacker.OneD_Stacker.Stack for further information on centering methods.

  • save –

    data to save at each bootstrap iterations

    possible values are ‘all’, ‘amp’ and ‘ampAndWidth’

    ’all’ saves the full stack at each bootstrap iteration (can use a lot of memory)

    ’amp’ saves the amplitude of the line (maximum value of the stack) at each bootstrap iteration, fastest

    ’ampAndWidth’ fits the line with a gaussian and saves the corresponding amplitude and width (the Gaussian sigma, in channels; FWHM = 2.355 sigma) at each bootstrap iteration (fits that do not converge are stored as [nan, nan]), can be cpu expensive.

  • seed – seed for reproducible resampling (None uses numpy’s global random state)

  • n_jobs – number of CPU cores to use (-1 for all). Worth it mostly for ‘ampAndWidth’ and for medians.

  • backend – ‘process’ or ‘thread’, see LineStacker.tools.parallel

  • verbose – print what is done and a progress bar (default: LineStacker.verbose)

Returns:

list – nRandom+1 entries (as chosen by save), the first one for the stack of all spectra.

LineStacker.analysisTools.bootStraping_Cube(coords, stampsize=32, imagenames=None, method='mean', weighting=None, maxmaskradius=0, fEm=0, spectralMethod='z', N_chans=30, nRandom=1000, save='amp', lEm=-1, hdul='auto', maskradius=None, seed=None, n_jobs=1, backend=None, continuum=False, collapse='sum', verbose=None, regridFromZ=False, regridMethod='scaleToMax', conserveFlux=True, primarybeam=None)[source]

Bootstrapping of a cube stack: stacks of random draws, with replacement, of the sources. See LineStacker.image.stack for the stacking parameters.

Parameters:
  • coords – A list of LineStacker.Coord of all target coordinates

  • stampsize – size of target image in pixels

  • imagenames – Name of images to extract cubes from

  • method – stacking method, ‘mean’ or ‘median’

  • weighting –

    weighting method to use if stacking method is mean

    possible values are ‘sigma2’, ‘sigma2F’, ‘1/A’, ‘sigma’, ‘pb’ (with primarybeam) or None (weights of the coords)

    see LineStacker.image.stack for a complete description of weighting methods

  • maxmaskradius – radius of the mask used to blank the centre pixels in weight calculation (also accepted as maskradius)

  • fEm – rest emission frequency of the line (or lEm for wavelength cubes)

  • N_chans – number of channels of the resulting stack

  • nRandom – number of bootstrap iterations

  • save –

    data to save at each bootstrap iterations

    possible values are ‘all’, ‘amp’, ‘ampAndWidth’ and ‘outflow’

    ’all’ saves the full stack at each bootstrap iteration (can use a lot of memory)

    ’amp’ saves the amplitude (maximum value of the stack) of the line, at each bootstrap iteration, fastest

    ’ampAndWidth’ fits the line with a gaussian and saves the corresponding amplitude and width (the Gaussian sigma, in channels; FWHM = 2.355 sigma) at each bootstrap iteration (fits that do not converge are stored as [nan, nan]), can be cpu expensive

    ’outflow’ fits the line with two gaussian components and saves the stack parameters at each bootstrap iteration, can be cpu expensive

    for ‘amp’, ‘ampAndWidth’ and ‘outflow’ the line is obtained by summing all pixels inside the stack stamp.

  • seed – see the module description

  • n_jobs – see the module description

  • backend – see the module description

  • continuum – continuum stacking, see LineStacker.image.stack (‘amp’ is then the stamp-summed flux; ‘ampAndWidth’ and ‘outflow’ need a spectral axis)

  • collapse – continuum stacking, see LineStacker.image.stack (‘amp’ is then the stamp-summed flux; ‘ampAndWidth’ and ‘outflow’ need a spectral axis)

  • verbose – print what is done and a progress bar (default: LineStacker.verbose)

  • regridFromZ – as for LineStacker.image.stack, to bootstrap a stack made with them

  • regridMethod – as for LineStacker.image.stack, to bootstrap a stack made with them

  • conserveFlux – as for LineStacker.image.stack, to bootstrap a stack made with them

  • primarybeam – as for LineStacker.image.stack, to bootstrap a stack made with them

Returns:

list – nRandom+1 entries (as chosen by save), the first one for the stack of all sources.

LineStacker.analysisTools.congrid(a, newdims, method='linear', centre=False, minusone=False)[source]

Arbitrary resampling of an array to new dimension sizes (same number of dimensions), with the sampling points of IDL’s congrid.

Parameters:
  • a – array to resample

  • newdims – new size of every dimension

  • method – ‘neighbour’ (closest value), ‘nearest’ or ‘linear’ (n 1-D interpolations with scipy.interpolate.interp1d), or ‘spline’ (scipy.ndimage.map_coordinates, cubic)

  • centre – True: interpolation points at the centres of the bins; False (default): at their front edges

  • minusone – False (default): an axis of i samples resized to x is sampled by factors of i/x; True: by (i-1)/(x-1), which avoids extrapolating one sample beyond the input

  • LineStacker's (Blank (NaN) values are not handled specially here;)

  • rebin_OneD). (rebinning functions handle them (see)

  • https (From)

  • 2001 ((Copyright (c))

  • Enthought (2002)

  • 2003-2017 (Inc.; Copyright (c))

  • reserved.) (SciPy Developers. All rights)

LineStacker.analysisTools.rebin_OneD(spectra, verbose=None, conserveFlux=True)[source]

Rebin a list of spectra so that all lines span as many channels as the narrowest one (widths in channels, from Gaussian fits). The lines must be visible source by source. Fluxes are linearly interpolated; a rebinned channel interpolated from a blank (NaN) channel is NaN. The spectral axes, per-channel weights and line centres (centerIndex) follow the new channels.

Parameters:
  • spectra – A list of LineStacker.OneD_Stacker.Spectrum objects

  • verbose – print what is done (default: LineStacker.verbose)

  • conserveFlux – True (default): a new channel is the mean of the channels it covers, so the noise goes down with the wider channels and the integrated flux of each line is kept exactly. False: a new channel takes the value of the spectrum at its centre, and the channels in between are not used (LineStacker 1.x and 2.0.0). The line widths in channels come out the same either way.

Returns:

list of LineStacker.OneD_Stacker.Spectrum – the rebinned spectra (copies).

LineStacker.analysisTools.rebin_CubesSpectra(coords, imagenames=None, regionSize=False, widths=False, outputName='_SpectralRebinned', hdul='auto', outdir=None, verbose=None, conserveFlux=True)[source]

Rebin a list of image-cubes so that all lines have the width of the narrowest one (widths from Gaussian fits, or given). The lines must be visible source by source. A rebinned channel interpolated from a blank (NaN) channel is NaN. One coordinate per cube is enough (the first one of each cube is used).

Parameters:
  • coords – A list of LineStacker.Coord (one per image).

  • imagenames – Name of images to rebin (FITS or CASA images)

  • regionSize –

    size (in pixels) of the square region whose summed spectrum is fitted (placed around the source as the stamps of LineStacker.image.stack)

    If set to False spectra will be extracted solely from the coord pixel

  • widths –

    widths of the lines

    If set to ‘False’ the spectra will be fitted with a gaussian to extract the width

  • outputName – Suffix of the rebinned cube, to add to the original cube name.

  • outdir – Folder for the rebinned cubes (created if needed); default: next to the originals.

  • verbose – print where the rebinned cubes are written, and a progress bar (default: LineStacker.verbose)

  • conserveFlux – True (default): a new channel is the mean of the channels it covers: all the data are used, and the integrated flux of each line is kept exactly. False: a new channel takes the value of the spectrum at its centre (linear interpolation; the channels in between are not used), as in LineStacker 1.x and 2.0.0.

Returns:

list of str – the names of the rebinned cubes (same format as the inputs).

LineStacker.analysisTools.maximizeAmp(spectra)[source]

Grade of a stacked spectrum: its maximum (blank channels ignored; 0 if every channel is blank).

LineStacker.analysisTools.maximizeSNR(spectra)[source]

Grade of a stacked spectrum: amplitude of a Gaussian fit over the standard deviation of the valid (finite) channels outside the line (2.35 sigma on each side). 0 if the fit fails, finds no line inside the spectrum, or leaves fewer than 2 valid channels outside it.

LineStacker.analysisTools.maximizeOutflow(spectra)[source]

Grade of a stacked spectrum for a second (e.g. outflow) component: amplitude x width**2 of the fainter component of a two-Gaussian fit (blank channels ignored; 0 if the fit fails).

LineStacker.analysisTools.subsample_OneD(spectra, nRandom=10000, maxTest=<function maximizeSNR>, seed=None, n_jobs=1, backend=None, minSize=3, maxSize=None, verbose=None, **kwargs)[source]

Stacks random subsets of the spectra and grades every stack with maxTest; each spectrum collects the grades of the stacks it was part of.

Parameters:
  • spectra – A list of LineStacker.OneD_Stacker.Spectrum objects

  • nRandom – Number of iterations of the Monte-Carlo process

  • maxTest – function test to grade the sources build your own, or use existing: maximizeAmp, maximizeSNR, maximizeOutflow. Default is to maximize the signal to noise ratio. With backend=’process’ a custom function must be defined at module level (not a lambda) so it can be sent to the workers.

  • minSize – range of the random subsample sizes (default 3 to all spectra)

  • maxSize – range of the random subsample sizes (default 3 to all spectra)

  • seed – see the module description. Gaussian-fit based grades (maximizeSNR, maximizeOutflow) benefit from n_jobs>1.

  • n_jobs – see the module description. Gaussian-fit based grades (maximizeSNR, maximizeOutflow) benefit from n_jobs>1.

  • backend – see the module description. Gaussian-fit based grades (maximizeSNR, maximizeOutflow) benefit from n_jobs>1.

  • verbose – print what is done and a progress bar (default: LineStacker.verbose)

  • **kwargs – passed to LineStacker.OneD_Stacker.Stack (method, center, chansStack…)

Returns:

dict – {spectrum name: summed grade} (spectra without a name are named by their index, ‘0’, ‘1’…). The centring works on copies: the spectra keep their centerIndex.

LineStacker.analysisTools.noise_estimator(imagenames, nRandom=10000, maskradius=0, maskCenter=None, continuum=True, chanToNoise='random', hdul='auto', plotIt=True, seed=None, verbose=None)[source]

Estimates the noise of images or cubes from randomly drawn pixels (blank, i.e. NaN or infinite, pixels are never drawn; pixels that are exactly zero are data).

Parameters:
  • imagenames – Path to image (FITS or CASA image), or list of paths

  • nRandom – Number of iterations

  • maskradius – Radius of the mask (in pixels)

  • maskCenter – Center location of the mask (in pixels, [x, y]; default [0, 0]). NB: CENTER OF IMAGE IS DEFINED AS [0,0]

  • continuum – If set to True points will be taken at random on the any of the spectral channels. Otherwise all channels are probed independently.

  • chanToNoise – If set to a specific (int) value then noise will be extracted from the specified channel. NB: only works if continuum is set to True.

  • plotIt – show the (masked) first image

  • seed – seed for reproducible draws (None uses numpy’s global random state)

  • verbose – print what is done and a progress bar (default: LineStacker.verbose)

Returns:

float or numpy array – the standard deviation of the drawn pixels (continuum=True), or one per channel.

LineStacker.analysisTools.stack_estimator(coords, nRandom=100, imagenames=None, stampsize=1, method='mean', N_chans=30, lowerLimit='default', upperLimit='default', save='central_pixel', fEm=0, spectralMethod='z', lEm=-1, hdul='auto', seed=None, n_jobs=1, backend='thread', verbose=None, **kwargs)[source]

Performs stacks at random positions a set number of times. Allows to probe the relevance of stack through stacking random positions as a Monte Carlo process. The random positions keep each source’s redshift; positions whose stamp would fall outside the image are drawn again.

Parameters:
  • coords – A list of LineStacker.Coord of all target coordinates.

  • nRandom – Number of iterations

  • imagenames – Name of imagenames to stack

  • stampsize – Size of the stamp to stack (because only the central pixel is extracted anyway, this should be kept to default to enhance efficiency)

  • method – Method for stacking, see LineStacker.image.stack

  • N_chans – Number of channels in the stack

  • lowerLimit – Lower spatial limit (distance from stacking position, radians) to randomize new stacking position. Default is 5 beams

  • upperLimit – Upper spatial limit (distance from stacking position, radians) to randomize new stacking position. Default is 10 beams

  • save – either ‘central_pixel’ or ‘all’. If ‘central_pixel’ only the spectrum of central pixel is saved.

  • spectralMethod – Method to select the central frequency of the stack. See LineStacker.image.stack.

  • seed – see the module description (‘thread’ is the default backend here: the cubes stay shared)

  • n_jobs – see the module description (‘thread’ is the default backend here: the cubes stay shared)

  • backend – see the module description (‘thread’ is the default backend here: the cubes stay shared)

  • verbose – print what is done and a progress bar (default: LineStacker.verbose)

  • **kwargs – weighting, maskradius, regridFromZ, regridMethod, conserveFlux, primarybeam…: the other stacking options of LineStacker.image.stack, so the random stacks are made as the stack itself

Returns:

list – [standard deviation, mean, all random stacks].

LineStacker.analysisTools.randomizeCoords(coords, beam=0, lowerLimit='default', upperLimit='default', imagenames=None, hdul='auto', seed=None)[source]

New positions at a random distance (uniform between lowerLimit and upperLimit) and in a random direction from each coordinate. The positions are not checked against the images; LineStacker.randomizeCoords (distances in beams) keeps them inside their image, and stack_estimator draws its own.

Parameters:
  • coords – A list of LineStacker.Coord coordinates

  • lowerLimit –

    Lower limit of the distance (radians) to the original position.

    Default is 5 beams

  • upperLimit –

    Upper limit of the distance (radians) to the original position.

    Default is 10 beams

  • beam – beam size (radians), needed if lowerLimit or upperLimit are set to ‘default’

  • imagenames – needed for pixel coordinates (to convert distances to pixels)

LineStacker.analysisTools.regridFromZ(coords, imagenames=None, stampsize=32, N_chans=0, fEm=0, writeImage=True, regridMethod='scaleToMin', hdul='auto', outdir='./regridedImages', verbose=None, conserveFlux=True)[source]

Cube regridding function correcting the observed linewidth change due to redshift. Spectral dimensions are rebinned to a new_size=old_size*zRatio where zRatio=(1+z)/(1+zRef) where z is the observed line redshift and zRef is either the smaller (scaleToMin) or bigger (scaleToMax) redshift among the studied lines. Spectra are resampled with a cubic spline through the valid channels (separately between blank channels, which are never used): new channels between a valid and a blank channel, or beyond the last channel, are NaN.

LineStacker.image.stack(…, regridFromZ=True) corrects the line widths in memory instead, without writing cubes (with linear interpolation).

Parameters:
  • coords – A list of LineStacker.Coord of all target coordinates.

  • imagenames – Name of images to extract flux from.

  • stampsize – size of target image in pixels

  • N_chans – unused, kept for compatibility

  • fEm – rest emission frequency of the line (frequency cubes only)

  • writeImage – boolean, if set to True regridded images will be written to disk (in outdir)

  • regridMethod – Method of regridding, can be set either to ‘scaleToMin’ or ‘scaleToMax’. In the first case all spectra are regridded to match the smallest redshift (over-gridding), all spectra are regridded to match the highest redshift in the other case (under-gridding).

  • outdir – folder for the regridded cubes (default ./regridedImages; created if needed). Nothing in it is deleted: a regridded cube replaces a file of the same name, other files stay.

  • verbose – print where the regridded cubes are written, and a progress bar (default: LineStacker.verbose)

  • conserveFlux – Used with regridMethod=’scaleToMax’, which makes channels wider. True (default): a new channel is the mean of the channels it covers (all the data are used, integrated flux kept). False: it takes the value of the spline at its centre (LineStacker 1.x and 2.0.0).

Returns:

tuple or list – If writeImage is True: (imagenames, coords), the regridded cubes and their coordinates. Stack them as they are, with LineStacker.image.stack(coords, imagenames=imagenames, spectralMethod=’z’, fEm=fEm): a regridded cube’s spectral axis is labelled in the rest frame (its coordinate has z = 0, channels of rest-frame width), and sources already at the reference redshift keep their original cube and redshift. Regridded cubes are stamps of stampsize pixels around each source, with the sky coordinates of the original cube. If writeImage is False: the list of regridded stamps.

LineStacker.analysisTools.regridFromZ1D(spectra, regridMethod='scaleToMin', verbose=None, conserveFlux=True)[source]

1D regridding function correcting the observed linewidth change due to redshift. Spectra are rebinned to a new_size=old_size*zRatio where zRatio=(1+z)/(1+zRef) where z is the observed line redshift and zRef is either the smaller (scaleToMin) or bigger (scaleToMax) redshift among the studied lines. Fluxes are resampled with a cubic spline through the valid channels (separately between blank channels, which are never used): new channels between a valid and a blank channel, or beyond the last channel, are NaN. Spectral axes, per-channel weights and line centres (centerIndex) follow the new channels.

Parameters:
  • spectra – List of spectra (LineStacker.OneD_Stacker.Spectrum objects).

  • regridMethod – Method of regridding, can be set either to ‘scaleToMin’ or ‘scaleToMax’. In the first case all spectra are regridded to match the smallest redshift (over-gridding), all spectra are regridded to match the highest redshift in the other case (under-gridding).

  • verbose – print what is done and a progress bar (default: LineStacker.verbose)

  • conserveFlux – Used with regridMethod=’scaleToMax’, which makes channels wider. True (default): a new channel is the mean of the channels it covers (all the data are used, integrated flux kept). False: it takes the value of the spline at its centre (LineStacker 1.x and 2.0.0).

Returns:

list of LineStacker.OneD_Stacker.Spectrum – the regridded spectra (copies).

LineStacker.tools

LineStacker.tools.ProgressBar(n, total, verbose=None)[source]

Draws a progress bar (at most about 100 redraws).

Parameters:
  • n – current step

  • total – total number of steps

  • verbose – draw the bar (default: LineStacker.verbose)

LineStacker.tools.resolve_n_jobs(n_jobs)[source]

Number of workers for an n_jobs argument (None/1 = serial, -1 = all cores).

LineStacker.tools.fit

Gaussian fitting of spectra (single, double, and symmetric double peaks).

The fitting functions ignore non-finite samples (NaN channels) and raise FitError (a RuntimeError) when a fit cannot be done or does not converge: too few valid samples, a constant spectrum, invalid initial values, or non-finite fitted parameters.

exception LineStacker.tools.fit.FitError[source]

A fit could not be done or did not converge.

LineStacker.tools.fit.Gauss(f=None, f0=0, dV='default', emittedF=0, sPeak=1.0, dF=1, noise=False, sigmaNoise=0)[source]

Gaussian line on the axis f: peak sPeak at f0 and FWHM dF; with dF=0 the FWHM is that of the velocity width dV (m/s) at the frequency emittedF, dF = dV emittedF / c. noise=True adds Gaussian noise of standard deviation sigmaNoise.

LineStacker.tools.fit.gaussFct(x, a, x0, sigma, constant=0)[source]

Gaussian a exp(-(x-x0)**2 / (2 sigma**2)) + constant.

LineStacker.tools.fit.DoubleGauss(f=None, amp1=0, amp2=0, f01=0, f02=0, sigma1=0, sigma2=0)[source]

Sum of two Gaussians (amplitudes amp1, amp2, centres f01, f02, widths sigma1, sigma2).

LineStacker.tools.fit.DoubleGaussPeak(f=None, amp=0, dist=0, sigma=0)[source]

Two Gaussians of the same amplitude and width, dist apart, centred on the middle of the axis f.

LineStacker.tools.fit.GaussFit(fctToFit=None, fullFreq=None, sigma='default', returnInfos=False, returnError=False)[source]

Simple Gaussian fitting function. Return order: fitting function, (fitting parameters), (error on fitting parameters). Non-finite samples are ignored; raises FitError (a RuntimeError) if the fit fails.

Parameters:
  • fctToFit – One dimensional array to be fitted

  • fullFreq – Spectral dimension array. Not required

  • sigma – initial width for fitting, ‘default’ is 3 bins

  • returnInfos – If set to True function returns fitted parameters

  • returnError – If set to True function returns error on fitted parameters

LineStacker.tools.fit.DoubleGaussFit(fctToFit=None, fullFreq=None, sigma1='default', sigma2='default', ampScale=0.1, returnAllComp=False, returnInfos=False, returnError=False)[source]

Double Gaussian (sum of two Gaussians) fitting function. Return order: fitting function, (first Gaussian, second Gaussian), (fitting parameters), (error on fitting parameters). Non-finite samples are ignored; raises FitError (a RuntimeError) if the fit fails.

Parameters:
  • fctToFit – One dimensional array to be fitted.

  • fullFreq – Spectral dimension array. Not required

  • sigma1 – Initial width of the first Gaussian component for fitting, ‘default’ is 3 bins.

  • sigma2 – Initial width of the second Gaussian component for fitting, ‘default’ is 6 bins.

  • ampScale – Initial amp ratio (between the two Gaussian components) for fitting, default is 0.1.

  • returnAllComp – If set to True function returns both individual components.

  • returnInfos – If set to True function returns fitted parameters.

  • returnError – If set to True function returns error on fitted parameters.

LineStacker.tools.fit.DoublePeakFit(fctToFit=None, fullFreq=None, returnInfos=False)[source]

Fit of two Gaussians of the same amplitude and width placed symmetrically about the middle of the spectral axis (see DoubleGaussPeak). Returns the model (and the parameters amp, dist, sigma with returnInfos=True). Raises FitError if the fit fails.

LineStacker.tools.parallel

Small helper to spread Monte-Carlo iterations (bootstraps, subsamples, random stacks) over several CPU cores.

Every function in LineStacker that accepts n_jobs draws all its random numbers up front, in the calling process, and only distributes the deterministic work. Results are therefore identical whatever n_jobs or backend is, and reproducible with seed.

backend='process' (default) runs workers in separate processes and is the right choice for Python-heavy work such as Gaussian fits. backend='thread' avoids starting processes and copying data; it helps when the work is mostly large numpy operations (e.g. median stacks of big cubes).

When using processes from a script on macOS or Windows, protect the script’s entry point:

if __name__ == '__main__':
    main()

otherwise each worker re-runs the script while starting.

LineStacker.tools.parallel.set_default_backend(backend)[source]

Set the backend used when a function is called with backend=None (‘process’ or ‘thread’).

LineStacker.tools.parallel.get_shared(name)[source]

Access, from a worker function, an object passed through shared.

LineStacker.tools.parallel.map_chunks(func, tasks, n_jobs=1, backend=None, shared=None, progress=True)[source]

Apply func to every element of tasks and return the results in order. func must be a module-level function (so it can be sent to worker processes). Large inputs common to all tasks go in shared (a dict); workers read them with get_shared().

Parameters:
  • func – function taking one task and returning its result

  • tasks – list of tasks (usually slices of iterations)

  • n_jobs – number of workers; 1 runs serially, -1 uses all cores

  • backend – ‘process’ or ‘thread’ (None uses the default, see set_default_backend)

  • shared – dict of read-only objects made available to func via get_shared

  • progress – show LineStacker’s progress bar