Filament2D¶
- class fil_finder.Filament2D(pixel_coords, converter=None, wcs=None, distance=None)[source]¶
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
).- converter
UnitConverter
, optional Unit converter class.
- wcs
WCS
, optional WCS information for the pixel set.
- distance
Quantity
, optional Distance to the region described by the pixel set. Requires for conversions to physical units.
- pixel_coordstuple of
Attributes Summary
Dictionary with branch lengths, average intensity, and pixels.
Interquartile range of the RHT orientation distribution along the longest path.
Curvature along each branch in the filament.
Skeleton pixels associated branch end.
The networkx graph for the filament.
Skeleton pixels associated intersections.
Pixel coordinates of the longest path.
Mean orientation of the filament along the longest path.
Orientations along each branch in the filament.
Distribution of orientations from the RHT along the longest path.
Fit uncertainties from
width_analysis
.Flag to catch poor fits.
The fitted radial profile model.
Fit parameters from
width_analysis
.Parameter names from
radprof_model
.The model type used to fit the radial profile.
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)[source]¶
Pixels within each skeleton branch.
- Parameters
- img_coordsbool
Return the branch pts in coordinates of the original image.
- branch_table(include_rht=False)[source]¶
Save the branch properties of the filament.
- Parameters
- include_rhtbool, optional
If
branches=True
is used inFilament2D.exec_rht
, the branch orientation and curvature will be added to the table.
- Returns
- tab
Table
Table with the branch properties.
- tab
- static from_pickle(filename)[source]¶
Load a Filament2D from a pickle file.
- Parameters
- filenamestr
Name of the pickle file.
- image_slicer(image, out_shape, pad_size=0)[source]¶
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.
- length(unit=Unit('pix'))[source]¶
The longest path length of the skeleton
- Parameters
- unit
Unit
, optional Pixel, angular, or physical unit to convert to.
- unit
- model_image(max_radius=<Quantity 20. pix>, bkg_subtract=True, bkg_mod_index=2)[source]¶
Return a model image from the radial profile fit.
- Parameters
- max_radius
Quantity
, 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.
- max_radius
- Returns
- model_array
Quantity
A 2D array computed using the radial profile model.
- model_array
- plot_graph(save_name=None, layout_func=<function spring_layout>)[source]¶
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)[source]¶
Plot the radial profile of the filament and the fitted model.
- plot_rht_distrib(save_name=None)[source]¶
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"))[source]¶
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
- image
ndarray
orQuantity
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.
- image
- Returns
- radprof_fit_table(unit=Unit('pix'))[source]¶
Return an
Table
with the fit parameters and uncertainties.- Parameters
- unit
Unit
, optional Pixel, angular, or physical unit to convert to.
- unit
- radprof_fwhm(unit=Unit('pix'))[source]¶
The FWHM of the fitted radial profile and its uncertainty.
- Parameters
- unit
Unit
, optional Pixel, angular, or physical unit to convert to.
- unit
- rht_analysis(radius=<Quantity 10. pix>, ntheta=180, background_percentile=25)[source]¶
Use the RHT to find the filament orientation and dispersion of the longest path.
- Parameters
- radius
Quantity
, 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.
- radius
- rht_branch_analysis(radius=<Quantity 10. pix>, ntheta=180, background_percentile=25, min_branch_length=<Quantity 3. pix>)[source]¶
Use the RHT to find the filament orientation and dispersion of each branch in the filament.
- Parameters
- radius
Quantity
, 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_length
Quantity
, 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.
- radius
- ridge_profile(image)[source]¶
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=<Quantity 20. pix>, header=None, model_kwargs={}, **kwargs)[source]¶
Save a stamp of the image centered on the filament, the skeleton, the longest path skeleton, and the model.
- Parameters
- image
ndarray
orQuantity
The image from which the filament was extracted.
- pad_size
Quantity
, optional Size to pad the saved arrays by.
- header
Header
, 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
.
- image
- skeleton(pad_size=0, corner_pix=None, out_type='all')[source]¶
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
- mask
ndarray
Boolean mask containing the skeleton pixels.
- mask
- 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>)[source]¶
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
- image
ndarray
orQuantity
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_thresh
Quantity
, optional Minimum length for a branch to be eligible to be pruned.
- image
- to_pickle(savename)[source]¶
Save a Filament2D class as a pickle file.
- Parameters
- savenamestr
Name of the pickle file.
- total_intensity(bkg_subtract=False, bkg_mod_index=2)[source]¶
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_intensity
Quantity
The total intensity for the filament.
- total_intensity
- 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)[source]¶
Create an average radial profile for the filament and fit a given model.
- Parameters
- image
Quantity
orndarray
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_dist
Quantity
, optional Largest radius around the skeleton to create the profile from. This can be given in physical, angular, or physical units.
- pad_to_distance
Quantity
, 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’.
- fitter
Fitter
, 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.
- beamwidth
Quantity
, 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
.
- image