Filament2D

class fil_finder.Filament2D(pixel_coords, converter=None, wcs=None, distance=None)

Bases: FilamentNDBase

Analysis and properties of a 2D filament.

Parameters

pixel_coordstuple of ndarray

Pixel coordinates as a set of arrays (i.e., the output from where).

converterUnitConverter, optional

Unit converter class.

wcsWCS, optional

WCS information for the pixel set.

distanceQuantity, optional

Distance to the region described by the pixel set. Requires for conversions to physical units.

Attributes Summary

branch_properties	Dictionary with branch lengths, average intensity, and pixels.
curvature	Interquartile range of the RHT orientation distribution along the longest path.
curvature_branches	Curvature along each branch in the filament.
end_pts	Skeleton pixels associated branch end.
graph	The networkx graph for the filament.
intersec_pts	Skeleton pixels associated intersections.
longpath_pixel_coords	Pixel coordinates of the longest path.
orientation	Mean orientation of the filament along the longest path.
orientation_branches	Orientations along each branch in the filament.
orientation_hist	Distribution of orientations from the RHT along the longest path.
radprof_errors	Fit uncertainties from width_analysis.
radprof_fit_fail_flag	Flag to catch poor fits.
radprof_model	The fitted radial profile model.
radprof_params	Fit parameters from width_analysis.
radprof_parnames	Parameter names from radprof_model.
radprof_type	The model type used to fit the radial profile.
radprofile	The binned radial profile created in width_analysis.

Methods Summary

branch_pts([img_coords])	Pixels within each skeleton branch.
branch_table([include_rht])	Save the branch properties of the filament.
from_pickle(filename)	Load a Filament2D from a pickle file.
image_slicer(image, out_shape[, pad_size])	Create a cut-out of a given image to some output shape with optional padding on the edges.
length([unit])	The longest path length of the skeleton
median_brightness(image)	Return the median brightness along the skeleton of the filament.
model_image([max_radius, bkg_subtract, ...])	Return a model image from the radial profile fit.
plot_graph([save_name, layout_func])	Plot the graph structure.
plot_radial_profile([save_name, xunit, ax])	Plot the radial profile of the filament and the fitted model.
plot_rht_distrib([save_name])	Plot the RHT distribution from Filament2D.rht_analysis.
profile_analysis(image[, max_dist, num_avg, ...])	Create profiles of radial slices along the longest path skeleton.
radprof_fit_table([unit])	Return an Table with the fit parameters and uncertainties.
radprof_fwhm([unit])	The FWHM of the fitted radial profile and its uncertainty.
radprof_table([xunit])	Return the radial profile as a table.
rht_analysis([radius, ntheta, ...])	Use the RHT to find the filament orientation and dispersion of the longest path.
rht_branch_analysis([radius, ntheta, ...])	Use the RHT to find the filament orientation and dispersion of each branch in the filament.
ridge_profile(image)	Return the image values along the longest path extent of a filament, or from radial slices along the longest path.
save_fits(savename, image[, pad_size, ...])	Save a stamp of the image centered on the filament, the skeleton, the longest path skeleton, and the model.
skeleton([pad_size, corner_pix, out_type])	Create a mask from the pixel coordinates.
skeleton_analysis(image[, verbose, ...])	Run the skeleton analysis.
to_pickle(savename)	Save a Filament2D class as a pickle file.
total_intensity([bkg_subtract, bkg_mod_index])	Return the sum of all pixels within the FWHM of the filament.
width_analysis(image[, all_skeleton_array, ...])	Create an average radial profile for the filament and fit a given model.

Attributes Documentation

branch_properties

Dictionary with branch lengths, average intensity, and pixels.

curvature

Interquartile range of the RHT orientation distribution along the longest path.

curvature_branches

Curvature along each branch in the filament.

end_pts

Skeleton pixels associated branch end.

graph

The networkx graph for the filament.

intersec_pts

Skeleton pixels associated intersections.

longpath_pixel_coords

Pixel coordinates of the longest path.

orientation

Mean orientation of the filament along the longest path.

orientation_branches

Orientations along each branch in the filament.

orientation_hist

Distribution of orientations from the RHT along the longest path.

Contains the angles of the distribution bins and the values in those bins.

radprof_errors

Fit uncertainties from width_analysis.

radprof_fit_fail_flag

Flag to catch poor fits.

radprof_model

The fitted radial profile model.

radprof_params

Fit parameters from width_analysis.

radprof_parnames

Parameter names from radprof_model.

radprof_type

The model type used to fit the radial profile.

radprofile

The binned radial profile created in width_analysis. This contains the distances and the profile value in the distance bin.

Methods Documentation

branch_pts(img_coords=False)

Pixels within each skeleton branch.

Parameters

img_coordsbool

Return the branch pts in coordinates of the original image.

branch_table(include_rht=False)

Save the branch properties of the filament.

Parameters

include_rhtbool, optional

If branches=True is used in Filament2D.exec_rht, the branch orientation and curvature will be added to the table.

Returns

tabTable

Table with the branch properties.

static from_pickle(filename)

Load a Filament2D from a pickle file.

Parameters

filenamestr

Name of the pickle file.

image_slicer(image, out_shape, pad_size=0)

Create a cut-out of a given image to some output shape with optional padding on the edges. The given image must be on the same pixel grid as the image used to create the skeleton.

Parameters

imagendarray or Quantity

Image to slice out around the skeleton.

out_shapetuple

2D output shape.

pad_sizeint, optional

Number of pixels to pad.

Returns

out_arrndarray or Quantity

Output array with given shape.

length(unit=Unit('pix'))

The longest path length of the skeleton

Parameters

unitUnit, optional

Pixel, angular, or physical unit to convert to.

median_brightness(image)

Return the median brightness along the skeleton of the filament.

Parameters

imagendarray or Quantity

The image from which the filament was extracted.

Returns

median_brightnessfloat or Quantity

Median brightness along the skeleton.

model_image(max_radius=<Quantity 20. pix>, bkg_subtract=True, bkg_mod_index=2)

Return a model image from the radial profile fit.

Parameters

max_radiusQuantity, optional

Set the radius to compute the model to. The outputted array will be padded by the number of pixels the max_radius corresponds to.

bkg_subtractbool, optional

Subtract off the fitted background level.

bkg_mod_indexint, optional

Indicate which element in Filament2D.radprof_params is the background level. Defaults to 2 for the Gaussian with background model.

Returns

model_arrayQuantity

A 2D array computed using the radial profile model.

plot_graph(save_name=None, layout_func=<function spring_layout>)

Plot the graph structure.

Parameters

save_namestr, optional

Name of saved plot. A plot is only saved if a name is given.

layout_funcnetworkx layout function, optional

Layout function from networkx. Defaults to spring_layout.

plot_radial_profile(save_name=None, xunit=Unit('pix'), ax=None)

Plot the radial profile of the filament and the fitted model.

Parameters

xunitUnit, optional

Pixel, angular, or physical unit to convert to.

axaxes, optional

Use an existing set of axes to plot the profile.

plot_rht_distrib(save_name=None)

Plot the RHT distribution from Filament2D.rht_analysis.

Parameters

save_namestr, optional

Name of saved plot. A plot is only saved if a name is given.

profile_analysis(image, max_dist=<Quantity 20. pix>, num_avg=3, xunit=Unit("pix"))

Create profiles of radial slices along the longest path skeleton. Profiles created from filament_profile.

Note

Does not include fitting to the radial profiles. Limited fitting of Gaussian profiles is provided in filament_profile. See a dedicated package like radfil for modeling profiles.

Parameters

imagendarray or Quantity

The image from which the filament was extracted.

max_distastropy Quantity, optional

The angular or physical (when distance is given) extent to create the profile away from the centre skeleton pixel. The entire profile will be twice this value (for each side of the profile).

num_avgint, optional

Number of points before and after a pixel that is used when computing the normal vector. Using at least three points is recommended due to small pixel instabilities in the skeletons.

Returns

distsQuantity

Distances in the radial profiles from the skeleton. Units set by xunit.

profilesQuantity

Radial image profiles.

radprof_fit_table(unit=Unit('pix'))

Return an Table with the fit parameters and uncertainties.

Parameters

unitUnit, optional

Pixel, angular, or physical unit to convert to.

radprof_fwhm(unit=Unit('pix'))

The FWHM of the fitted radial profile and its uncertainty.

Parameters

unitUnit, optional

Pixel, angular, or physical unit to convert to.

radprof_table(xunit=Unit('pix'))

Return the radial profile as a table.

Parameters

xunitUnit, optional

Spatial unit to convert radial profile distances.

Returns

tabTable

Table with the radial profile distance and values.

rht_analysis(radius=<Quantity 10. pix>, ntheta=180, background_percentile=25)

Use the RHT to find the filament orientation and dispersion of the longest path.

Parameters

radiusQuantity, optional

Radius of the region to compute the orientation within. Converted to pixel units and rounded to the nearest integer.

nthetaint, optional

Number of angles to sample at. Default is 180.

background_percentilefloat, optional

Float between 0 and 100 that sets a background level for the RHT distribution before calculating orientation and curvature.

rht_branch_analysis(radius=<Quantity 10. pix>, ntheta=180, background_percentile=25, min_branch_length=<Quantity 3. pix>)

Use the RHT to find the filament orientation and dispersion of each branch in the filament.

Parameters

radiusQuantity, optional

Radius of the region to compute the orientation within. Converted to pixel units and rounded to the nearest integer.

nthetaint, optional

Number of angles to sample at. Default is 180.

background_percentilefloat, optional

Float between 0 and 100 that sets a background level for the RHT distribution before calculating orientation and curvature.

min_branch_lengthQuantity, optional

Minimum length of a branch to run the RHT on. Branches that are too short will cause spikes along the axis angles or 45 deg. off.

ridge_profile(image)

Return the image values along the longest path extent of a filament, or from radial slices along the longest path.

Parameters

imagendarray or Quantity

The image from which the filament was extracted.

save_fits(savename, image, pad_size=<Quantity 20. pix>, header=None, model_kwargs={}, **kwargs)

Save a stamp of the image centered on the filament, the skeleton, the longest path skeleton, and the model.

Parameters

imagendarray or Quantity

The image from which the filament was extracted.

pad_sizeQuantity, optional

Size to pad the saved arrays by.

headerHeader, optional

Provide a FITS header to save to. If Filament2D was given WCS information, this will be used if no header is given.

model_kwargsdict, optional

Passed to model_image.

kwargsPassed to writeto.

skeleton(pad_size=0, corner_pix=None, out_type='all')

Create a mask from the pixel coordinates.

Parameters

pad_sizeint, optional

Number of pixels to pad along each edge.

corner_pixtuple of ints, optional

The position of the left-bottom corner of the pixels in the skeleton. Used for offsetting the location of the pixels.

out_type{“all”, “longpath”}, optional

Return the entire skeleton or just the longest path. Default is to return the whole skeleton.

Returns

maskndarray

Boolean mask containing the skeleton pixels.

skeleton_analysis(image, verbose=False, save_png=False, save_name=None, prune_criteria='all', relintens_thresh=0.2, max_prune_iter=10, branch_thresh=<Quantity 0. pix>)

Run the skeleton analysis.

Separates skeleton structures into branches and intersections. Branches below the pruning criteria are removed. The structure is converted into a graph object to find the longest path. The pruned skeleton is used in the subsequent analysis steps.

Parameters

imagendarray or Quantity

Data the filament was extracted from.

verbosebool, optional

Show intermediate plots.

save_pngbool, optional

Save the plots in verbose mode.

save_namestr, optional

Prefix for the saved plots.

prune_criteria{‘all’, ‘intensity’, ‘length’}, optional

Choose the property to base pruning on. ‘all’ requires that the branch fails to satisfy the length and relative intensity checks.

relintens_threshfloat, optional

Value between 0 and 1 that sets the relative importance of the intensity-to-length criteria when pruning. Only used if prune_criteria='all'.

max_prune_iterint, optional

Maximum number of pruning iterations to apply.

branch_threshQuantity, optional

Minimum length for a branch to be eligible to be pruned.

to_pickle(savename)

Save a Filament2D class as a pickle file.

Parameters

savenamestr

Name of the pickle file.

total_intensity(bkg_subtract=False, bkg_mod_index=2)

Return the sum of all pixels within the FWHM of the filament.

Warning

fil_finder_2D multiplied the total intensity by the angular size of a pixel. This function is just the sum of pixel values. Unit conversions can be applied on the output if needed.

Parameters

bkg_subtractbool, optional

Subtract off the fitted background level.

bkg_mod_indexint, optional

Indicate which element in Filament2D.radprof_params is the background level. Defaults to 2 for the Gaussian with background model.

Returns

total_intensityQuantity

The total intensity for the filament.

width_analysis(image, all_skeleton_array=None, max_dist=<Quantity 10. pix>, pad_to_distance=<Quantity 0. pix>, fit_model='gaussian_bkg', fitter=None, try_nonparam=True, use_longest_path=False, add_width_to_length=False, deconvolve_width=True, beamwidth=None, fwhm_function=None, chisq_max=10.0, **kwargs)

Create an average radial profile for the filament and fit a given model.

Parameters

imageQuantity or ndarray

The image from which the filament was extracted.

all_skeleton_arraynp.ndarray

An array with the skeletons of other filaments. This is used to avoid double-counting pixels in the radial profiles in nearby filaments.

max_distQuantity, optional

Largest radius around the skeleton to create the profile from. This can be given in physical, angular, or physical units.

pad_to_distanceQuantity, optional

Force all pixels within this distance to be kept, even if a pixel is closer to another skeleton, as given in all_skeleton_array.

fit_modelstr or Fittable1DModel, optional

The model to fit to the profile. Built-in models include ‘gaussian_bkg’ for a Gaussian with a constant background, ‘gaussian_nobkg’ for just a Gaussian, ‘nonparam’ for the non-parametric estimator. Defaults to ‘gaussian_bkg’.

fitterFitter, optional

One of the astropy fitting classes. Defaults to a Levenberg-Marquardt fitter.

try_nonparambool, optional

If the chosen model fit fails, fall back to a non-parametric estimate.

use_longest_pathbool, optional

Only fit profile to the longest path skeleton. Disabled by default.

add_width_to_lengthbool, optional

Add the FWHM to the filament length. This accounts for the expected shortening in the medial axis transform. Enabled by default.

deconvolve_widthbool, optional

Deconvolve the beam width from the FWHM. Enabled by default.

beamwidthQuantity, optional

The beam width to deconvolve the FWHM from. Required if deconvolve_width = True.

fwhm_functionfunction, optional

Convert the width parameter to the FWHM. Must take the fit model as an argument and return the FWHM and its uncertainty. If no function is given, the Gaussian FWHM is used.

chisq_maxfloat, optional

Enable the fail flag if the reduced chi-squared value is above this limit.

kwargsPassed to radial_profile.