specviz documentationin the above case, the loader registry functionality will attempt to select the...

specviz DocumentationRelease 0.7.0.dev01633

JDADF Developers

Mar 15, 2021

CONTENTS

I Installation and Setup 3

1 Installation 7

2 Launching SpecViz 11

II Using SpecViz 13

3 Loading Data 17

4 Exporting Data 23

5 Workspaces and Plots 25

6 Regions of Interest (ROI) 29

7 Unit Conversion 31

8 Operations 33

9 Arithmetic Editor 35

10 Model Fitting 41

11 Statistics 43

12 Spectral line labels 45

III Advanced 49

13 Developer Documentation 53

14 API Documentation 59

Python Module Index 93

Index 95

i

specviz Documentation, Release 0.7.0.dev01633

Danger: Please note that this version of Specviz is no longer being actively supported or maintained. Thefunctionality of Specviz is now available and being actively developed as part of Jdaviz.

SpecViz is a tool for visualization and quick-look analysis of 1D astronomical spectra. It is written in the Python pro-gramming language, and therefore can be run anywhere Python is supported (see Installation). SpecViz is built on topof the SpecUtils Astropy-affiliated python library, providing a visual, interactive interface to the analysis capabilitiesin that library.

SpecViz allows spectra to be easily plotted and examined. It supports flexible spectral unit conversions, custom plottingattributes, interactive selections, multiple plots, and other features.

SpecViz notably includes a measurement tool for spectral lines which enables the user, with a few mouse actions,to perform and record measurements. It has a model fitting capability that enables the user to create simple (e.g.,single Gaussian) or multi-component models (e.g., multiple Gaussians for emission and absorption lines in additionto regions of flat continua). A typical data-analysis workflow might involve data exploration using SpecViz and thenscripting to create more complex measurements or modeling workflows using SpecUtils.

SpecViz will soon include the ability to:

• Measure the average of multiple spectra, detrending, and apply Fourier filters.

• Interactively renormalize data from spectral templates.

• And more. . .

CONTENTS 1

https://github.com/spacetelescope/jdaviz

https://specutils.rtfd.io


2 CONTENTS

Part I

Installation and Setup

3



5



6

CHAPTER

ONE

INSTALLATION

As a Python package, SpecViz is installable via any approach that is available for installing Python packages. Inpractice the easiest way is often using the the Anaconda package manager, but several other options are available.These are detailed below.

Note: SpecViz requires Python 3.6 or later.

1.1 Install via Anaconda

If you do not have Anaconda, please follow the instructions here to install it, or scroll down for manual installation ofSpecViz.

To check if Anaconda is installed correctly run the following command on a new terminal:

$ conda info

You should see information about your current conda installation printed out.

1.1.1 Creating a new conda environment

Since SpecViz uses Python 3.6 or later you may need to create a new environment with this requirement satisfied asfollows:

$ conda create -n <environment_name> python=3.6

1.1.2 Installing

If you are using the Space Telescope Science Institute’s AstroConda channel, then type the following at any Bashterminal prompt:

$ conda install specviz

If you do not have AstroConda installed, you can still install SpecViz from AstrocConda by specifying the <channel>in the below install command:

$ conda install --channel http://ssb.stsci.edu/astroconda specviz

At this point, you’re done! You can launch SpecViz by typing the following at any terminal:

7

https://anaconda.org

https://www.anaconda.com/distribution/

https://astroconda.readthedocs.io/


$ specviz

1.1.3 Uninstalling

To uninstall via Anaconda, type the following at a command line:

$ conda uninstall specviz

1.2 Install via source

SpecViz can also be installed manually using the source code following the instructions below. The dependenciesare listed in the setup.cfg file, and therefore most of them will be handled automatically by the setup functions, theexception to this is the exception of PyQt, which may require manual installation.

1.2.1 PyQt bindings

Note: SpecViz requires PyQt for its graphical user interface. Before you install via source please make sure yourenvironment includes PyQt. If you don’t have PyQt installed, please follow the instructions in this section.

You can check if PyQt is installed by looking for it in the list of packages in your environment. To get a list of packagesyou can run:

$ pip list

If you have anaconda installed you can check via:

$ conda list

If QtPy (not to be confused with PyQt) does not appear in the list, you must manually install it.

Currently, only python environments with 3.6 or higher installed can use pip to install PyQt5, in which case simplytype:

$ pip install pyqt5

to install it on your system.

In any other case, PyQt can be installed via anaconda:

$ conda install pyqt

8 Chapter 1. Installation

1.2.2 By cloning

You may also install by cloning the repository directly

$ git clone https://github.com/spacetelescope/specviz.git$ cd specviz$ git checkout tags/v0.3.0$ python setup.py install

1.2.3 By using pip

Clone the SpecViz repository somewhere on your system, and install locally using pip. If you are using an Anacondavirtual environment, please be sure to activate it first before installing: $ source activate <environment_name>.

$ pip install git+http://github.com/spacetelescope/[email protected]

This uses the pip installation system, so please note that

1. You need to have pip installed (included in most Python installations).

2. You do not need to run python setup.py install.

3. You do not need to install the dependencies by hand (except for PyQt).

Likewise, the pip command will use your default Python to install. You can specify by using pip2 or pip3, if you’renot using a virtual environment.

1.2.4 Uninstalling

To uninstall via pip, simply type the following at a command line:

$ pip uninstall specviz

1.3 Known Issues

On a Mac with Qt5, depending on exactly how you have set up Anaconda, you might see the following error afterfollowing the above instructions:

This application failed to start because it could not find or load the Qt platform plugin "cocoa".

Reinstalling the application may fix this problem.

If you see this message, you have encountered an incompatibility between Anaconda’s packaging of Qt4 and Qt5. Theworkaround is to uninstall Qt4 with the following command:

$ conda uninstall pyqt qt

and SpecViz should now happily run.

Conversely, if you’ve had PyQt5 installed previously and you wish to run the PyQt4 version, you may run into a similarerror:

$ RuntimeError: the PyQt4.QtCore and PyQt5.QtCore modules both wrap theQObject class

1.3. Known Issues 9


This issue can be solved with the following command:

$ conda uninstall pyqt5 qt5


10 Chapter 1. Installation


CHAPTER

TWO

LAUNCHING SPECVIZ

Once the user has installed SpecViz, they can launch it via the command line:

$ specviz

If the user wishes to inspect a single file, they can also pass in the filename as a command line argument along withthe -F flag as follows:

$ specviz -F <filename>

You can get further help with the command line options by simply typing specviz --help.

2.1 Specifying Loaders

SpecViz uses data loaders to open spectra files. In the above case, the loader registry functionality will attempt toselect the best available loader for the data. If the user wishes to specify a specific loader for their data, a -L flag canbe passed with the loader name:

$ specviz -F <filename> -L <loader_name>

For example you can load your APOGEE spectrum file using the APOGEE apStar loader as follows:

$ specviz -F ~/data/apStar-r5-2M27333842+4223549.fits -L APOGEE\ apStar

To get a list of loaders please see the table of loaders in the Loading Data section.

11


12 Chapter 2. Launching SpecViz

Part II

Using SpecViz

13



15



16

CHAPTER

THREE

LOADING DATA

SpecViz provides various ways to load spectral data, including a GUI and command line interface. It supports manyASCII and FITS Binary Table file types. FITS Image files are not currently supported, but there are plans to add thiscapability in the future.

3.1 Supported File Types

Although a variety of file types can be used through Custom Loader Creation, SpecViz leverages several built inloaders provided by SpecUtils. The table below defines the built in loaders and what file characteristics they expect.

Loader Name Extension Additional SpecificationAPOGEEapStar

.fits filename starts with apStar

APOGEEapVisit

.fits filename starts with apVisit

APOGEE asp-capStar

.fits filename starts with aspcapStar

ASCII .txt or .ascii

ECSV .ecsvHST/COS .fits header values TELESCOP = HST and INSTRUME = COSHST/STIS .fits header values TELESCOP = HST and INSTRUME = STISIPAC .txt or .

datJWST .fits hdulist includes an ASDF extensions, at least one HDU named EXTRACT1DSDSS-I/IIspSpec

.fits filename matches spSpec-NNNNN-NNNN-NNN.fits, where N is an integer

SDSS-III/IVspec

.fits filename matches spSpec-NNNN(N)-NNNNN-NNNN.fits, where N is an integer

muscles-sed .fits filename ends with sed.fits, hdulist has BinTable in the first extension, headerkeyword PROPOSID = 13650

tabular-fits .fits hdulist has BinTable in first extension.wcs1d-fits .fits header keyword NAXIS = 1, CTYPE1 in primary header

17


3.2 Loading Basic Spectra

To see instructions on loading data through the command line, see the Launching SpecViz section.

To load spectra once inside the SpecViz API you can click on the Load Data button in the workspace toolbar. Thiswill open a file dialog window. At the bottom of this window is a drop down list of built in loaders. If Auto* is chosen,SpecViz will attempt to open the file with the loaders whose identifier specification match the file.

18 Chapter 3. Loading Data


Once the file has been loaded, the spectrum plot should appear.

3.3 Loader Wizard

The Loader Wizard assists with loading spectra into SpecViz. For a given spectrum it creates a custom loader filewhich can then be used to load the spectrum (and spectra in the same format) without having to use the wizard,accessed from the Load Data file dialog window.

The Loader Wizard is invoked by clicking on the Loader Wizard button in the workspace toolbar. The below dialogbox will display:

3.3. Loader Wizard 19


The Loader Wizard uses astropy.table.Table.read to open the data file. Desired input parameters for astropy.table.Table.read can be entered in the top text box of the Loader Wizard. The syntax of this field should matchthe syntax following the filename parameter in an astropy.table.Table.read call. For example, the grayed outtext in the above figure shows an additional parameter of format="ascii". For multiple additional parameters youshould include commas, i.e. format = "ascii", comment = "*". See the astropy.table.Table documentationfor the available options. Once this field is filled out, you can press the Refresh Data button and the wizard will reloadthe table from the provided file. If the read command was successful, the drop downs in the Dispersion, Data andUncertainty sections of the wizard will be populated.

The bottom left field for the Loader Name determines the label assigned to the saved loader. When the Save to .pybutton is clicked, it will open a new dialog for saving the loader file on your machine. The loader label name and thefilename can be different.

You will not be able to save your new loader without valid units defined for the data section and the dispersion section.You can see a preview of the generated loader wizard by clicking on the Preview .py button.

The Loader Wizard is able to handle table data (including FITS binary tables), but cannot currently handle FITS imagedata. Additionally, although not currently implemented, we plan on supporting bit masks in a future release.


https://docs.astropy.org/en/stable/api/astropy.table.Table.html#astropy.table.Table.read




https://docs.astropy.org/en/stable/api/astropy.table.Table.html#astropy.table.Table



3.4 Custom Loader Creation

For data/file types with no built in loader and not supported in the File Loader Wizard, a custom loader may benecessary. Instructions on how to build a Custom Loader can be found in the Specutils documentation. If the finishedPython loader file is saved to ~/.specutils/ it will be accesible through the Specviz interface.


3.4. Custom Loader Creation 21

https://specutils.readthedocs.io/en/latest/custom_loading.html


CHAPTER

FOUR

EXPORTING DATA

A user can export a given spectrum in the data list by highlighting the spectrum and clicking the Export Data buttonin the main toolbar. This will provide the user with a save file dialog where they may choose where to save the exportedspectrum.

Note: ECSV is currently the only supported export format. This will change in the future as more exporting formatsare supported in the specutils package.


23

http://docs.astropy.org/en/stable/api/astropy.io.ascii.Ecsv.html



24 Chapter 4. Exporting Data

CHAPTER

FIVE

WORKSPACES AND PLOTS

5.1 Workspaces

Loaded data is added to the global data list for the entire workspace. A workspace is an instance of the SpecVizapplication. Several can be open at once and more can be added by selecting File > New Workspace from the menubar. Workspaces are completely independent of one another, and the user can have as many workspaces are they wish.

Each workspace consists of the following components:

• Data list

• Workspace toolbar

• plugin sidebar

• Plots

25


5.2 Data List

The data list appears on the left of the workspace. This is where all loaded data/spectra are displayed. The data valuesof the a given data item are global to the workspace while the visibility, color and state relate to the currently displayedplot. To select a specific data simply click on its name. You can also rename double click on it and typing in the newname; when finished press enter.

5.3 Workspace Toolbar

Note: When applying an operation on a data item (fitting, removing etc.) you must first select the data from the datalist before clicking the desired toolbar button.

This is the main toolbar and appears at the top of each workspace. The tool bar consists of buttons that controlloading/removing data, adding new plots and buttons that are associated with SpecViz plugins.

5.4 Plugin Sidebar

The plugin sidebar is where plugin modules such as statistics and model fitting appear. You can switch between pluginsby using the tabs next to the plugin sidebar.

5.5 Plots

Plots are the visual representation of a selection of data items within a particular workspace. A user can have as manyplots as they wish, and new plots can be created by clicking the New Plot button in the Workspace toolbar. Likewise,plot windows can be removed by clicking the X button in the plot tab right above the plot window.

Plots all share the same data list within a workspace. The caveat is that plots can only show data that have equivalentunits. Any data that cannot be added to a plot will show as disabled in the data list.

Clicking the checkbox next to an item in the data list will plot the data item on the current plot.

5.5.1 Plot Toolbar

The plot toolbar contains buttons that relate to the current plot.

The following features are accessible through the plot toolbar:

• Add or remove regions of interest

26 Chapter 5. Workspaces and Plots


• Change the color of the plot

• Unit conversion of the axes

• Reset the plot

• Export the plot to file


5.5. Plots 27



28 Chapter 5. Workspaces and Plots

CHAPTER

SIX

REGIONS OF INTEREST (ROI)

A user may select single or multiple wavelength ranges of spectra for model fitting or measuring statistics. This isdone with the “Region of Interest” (or, ROI) selector via the Add Region button in the plot toolbar. When a region isselected, it is highlighted with a blue shading. This region will be used for the statistics panel and the model fitting.

Note: Currently, only one region can be the “selected” region. This will change in the future to allow a subset ofplotted region to be defined as “selected”.

To remove a region, click on the Remove Region button on the plot toolbar. To expand or contract a region, click anddrag its edge until the desired range. The ROI can be moved by clicking the middle of the ROI and dragging. Therange of the currently selected region is displayed at the upper left corner of the plot window.

29



30 Chapter 6. Regions of Interest (ROI)


CHAPTER

SEVEN

UNIT CONVERSION

7.1 How Unit Conversion Works

SpecViz allows the user to change the units on their spectra. It uses the astropy.units module for unit conversion.

To change the units, click on the blue “Change Units” button in the plot toolbar. A dialog box will appear and you canchange the X or Y axis units by selecting new units from one of the two drop down boxes. The boxes are populatedby potential compatible units. The user can then select any of those options - as well as a “Custom” option - and thechanges will be reflected in the plot.

If you do not see the units you want in the drop down, you can select the “Custom” option. This will then make visiblea text box where you can enter your chosen units. To the left of the text box, a label will let you know if you areentering valid astropy unit. Red coloring means the units are invalid, and there should be suggestions provided. Greencoloring means you entered valid units and can now press the “OK” button. If the units are incompatible, the currentplot units will not be changed.

Invalid custom unit:

31

http://docs.astropy.org/en/stable/units/

http://docs.astropy.org/en/stable/units/index.html


Valid custom astropy unit:


32 Chapter 7. Unit Conversion

http://docs.astropy.org/en/stable/units/index.html


CHAPTER

EIGHT

OPERATIONS

Operations are modules that preform calculations on a given spectrum. To preform an operation, first select a spectrumfrom the data list. Then click on the “Operations” button in the workspace toolbar. A drop down will appear listingall the available operations.

8.1 Smoothing

First select smoothing from the operations menu. The following smoothing dialog will open:

Select the desired data, kernel type and width. When ready click Smooth. The newly smoothed data will appear as anitem in the data list. The naming convention for the outputs of smoothed data is as follows:

<Original Name> Smoothed(<Kernel Type>, <Kernel Size>)

The output data will be in the same units as the input data.


33


34 Chapter 8. Operations

CHAPTER

NINE

ARITHMETIC EDITOR

The Arithmetic Editor allows users to perform basic spectral arithmetic. Inputs are spectra loaded into the Specvizsession. Outputs are also spectra in SpecViz.

To load the Arithmetic Editor, click on the Arithmetic button in the workspace toolbar. This dialog box will appear:

From this dialog you can add, edit or remove arithmetic items from the editor.

Note: All spectra are specutils.Spectrum1D objects in astropy. Therefore, the Arithmetic Editor allows users toperform the arithmatic operations that are incorporated into the specutils.Spectrum1D object.

35


9.1 Example

We will walk you through an example of how to multiply a spectrum by a factor of 2. Start by clicking the “NewArithmetic Attribute” button in the top left and the following dialog box will appear:

Arithmetic is done using expressions entered into the large box. Examples of operations are given at the bottom ofthe dialog box. We first assign a name to the output data by entering it in the first text box; we will call the outputof this example double science_spectrum. Let’s choose a spectrum to operate on called “science spectrum” bychoosing it from the first drop-down menu and clicking “Insert.” Let’s choose to operate on the wavelength axis bychoosing “wavelength” from the second drop-down menu and clicking “Insert.” Click on the text editor to start editingand multiply the inserted component by 2:

36 Chapter 9. Arithmetic Editor


To validate arithmetic, click the OK button located at the bottom right hand corner of the dialog box.

Warning: If the python syntax is invalid, the editor will not allow you to continue! The editor can only returnSpecUtils Spectrum1D objects.

Now, there will be a new data item located in the data collection called double science_spectrum.

9.1. Example 37

https://specutils.readthedocs.io/en/latest/api/specutils.Spectrum1D.html


To show the result in the plotting window, select the data item by clicking the box next double science_spectrum.

This is a very simple example of the arithmetic you can perform with the SpecViz arithmetic editor. There are moreexample expressions located at the bottom of the equation editor dialog.




9.1. Example 39


CHAPTER

TEN

MODEL FITTING

SpecViz includes functionality to fit models to spectra. It uses astropy’s Models and SpecUtils to do so. The followingmodels are available in SpecViz:

SpecViz Model Name Astropy Model ClassConst Const1DGaussian Gaussian1DLinear Linear1DLorentz Lorentz1DVoigt Voigt1DPolynomial Polynomial1D

The models can be fitted with the following fitters: They can be fit with the following fitting algorithms in astropy

SpecViz Fitter Name Astropy Fitter ClassLevenberg-Marquardt LevMarLSQFitterSimplex SimplexLSQFitter

To use a model:

1. Create a new model by clicking on the “New Model” button on the WorkSpace toolbar.

2. Select the layer you wish to operate on from the combination box at the top of the fitting window. For example,you can choose the layer containing your emission or absorption line.

3. Create and position a region of interest (ROI). Multiple ROIs can be used. SpecViz fits the data under all theROIs.

4. Select the desired model from the green Add Model drop-down box to add it to Current Models.

5. If desired, repeat the above step to add additional models.

Warning: The selected model will only fit data points under all regions of interest (ROI). Data points that are notcovered by an ROI will not be fitted. If multiple ROIs overlap over a data point, its only considered once. All datapoints are fitted if there are no ROIs added to the plot.

To edit model parameters or enter a better first estimate of the model parameters:

1. If desired, double-click on the model name to rename it. When you see a blinking cursor, enter its new nameand press “Enter”.

2. Expand the model listing under the model name.

41

https://docs.astropy.org/en/stable/api/astropy.modeling.functional_models.Const1D.html#astropy.modeling.functional_models.Const1D

https://docs.astropy.org/en/stable/api/astropy.modeling.functional_models.Gaussian1D.html#astropy.modeling.functional_models.Gaussian1D

https://docs.astropy.org/en/stable/api/astropy.modeling.functional_models.Linear1D.html#astropy.modeling.functional_models.Linear1D

https://docs.astropy.org/en/stable/api/astropy.modeling.functional_models.Lorentz1D.html#astropy.modeling.functional_models.Lorentz1D

https://docs.astropy.org/en/stable/api/astropy.modeling.functional_models.Voigt1D.html#astropy.modeling.functional_models.Voigt1D

https://docs.astropy.org/en/stable/api/astropy.modeling.polynomial.Polynomial1D.html#astropy.modeling.polynomial.Polynomial1D

https://docs.astropy.org/en/stable/api/astropy.modeling.fitting.LevMarLSQFitter.html#astropy.modeling.fitting.LevMarLSQFitter

https://docs.astropy.org/en/stable/api/astropy.modeling.fitting.SimplexLSQFitter.html#astropy.modeling.fitting.SimplexLSQFitter


3. Double-click on the desired model parameter value in the listing. When you see a blinking cursor, enter the newvalue and press Enter.

To fit a model:

1. Select the layer you wish to operate on from the combination box at the bottom of the fitting window.

2. Adjust model parameter values to approximate fit.

3. Click the lock icon next to any parameter to choose whether it should be kept fixed (closed lock) or allowed tovary (open lock) during fitting.

4. Click on the settings icon at the bottom of the model fitting window select optionssuch as the desired fitter and maximum iterations.

5. Check the model’s Equation Editor by clicking the calculator button.It will pop up with the current model arithmetic. Review. edit and press ok when done.

6. Click the blue Fit Model button at the bottom of the fitting window.

7. The associated model parameters will be adjusted accordingly.

10.1 Equation Editor

The Equation Editor text box is used to define the relationship between different models for the same model dataitem. The editor can be launched by clicking the calculator Botton at the bottom of the model fitting window. Ifnothing is defined, the default is to add all the models together. To describe a non-default model relationship, adjustthe math operators, as shown in the examples below and then press Enter to produce the compound model:

Linear1 + Gaussian1

Linear1 * Gaussian1

Gaussian1 - Gaussian2

The entity that results from lumping together all the models, and combining them either using the arithmetic behaviorexpression, or just adding them all together, is called a “compound model”.

10.2 Model names

When added to the Current Models list, a model will receive a default name that is generated from the model type(as listed in the drop down model selector) plus a running numerical suffix.

These names can be changed by clicking on the default name and entering a new name. Note that changing modelnames will require that any expression in the Equation Editor text box be edited accordingly.


42 Chapter 10. Model Fitting


CHAPTER

ELEVEN

STATISTICS

11 statistic/analysis functions are calculated using the input spectrum or specified region of interest, depending onwhat is selected in the left sidebar. To get the statistics of a spectrum, select it on the data list on the left panel.

The user can calculate statistics for a selected region of a spectrum. First, a “Region of Interest” is selected. Once thisis done, the statistics are automatically calculated and displayed in the left sidebar. If a region of interest is selected,the statistic calculations are updated when that region of interest is changed.

Warning: If there are regions of interest (ROI) in the plot, the statistics are derived from the data points under theactive region of interest. Information about the region is displayed at the bottom of the statistics panel. Currentlyit is not possible to select multiple ROIs thus the statistics pertain to the single active ROI. If there are no ROIsadded to the plot, the statistics will be calculated for the entire spectrum.

11.1 Types of Statistics

Currently there are three types of statistics:

• Generic:

– Mean

– Median

– Std Dev

– SNR

– Max Flux

– Min Flux

– Count total

• Continuum Subtracted:Appends FWHM and Centroid to the Generic statistics.

• Continuum Normalized:Appends Eq Width the Generic statistics.

You can swap between the different types of statistics by using the drop down menu at the top of the statistics sidebar.

43


11.2 List of statistics

The following statistics are calculated:

Statistics FunctionMean meanMedian medianStd Dev stdCentroid centroidRMS (Calculated) ~numpy.sqrt(flux.dot(flux) / len(flux))SNR snrFWHM fwhmEq Width equivalent_widthMax maxMin minCount Total line_flux


44 Chapter 11. Statistics

https://docs.astropy.org/en/stable/api/astropy.units.Quantity.html#astropy.units.Quantity.mean

https://numpy.org/doc/stable/reference/generated/numpy.median.html#numpy.median

https://docs.astropy.org/en/stable/api/astropy.units.Quantity.html#astropy.units.Quantity.std

https://specutils.readthedocs.io/en/latest/api/specutils.analysis.centroid.html#specutils.analysis.centroid

https://specutils.readthedocs.io/en/latest/api/specutils.analysis.snr.html#specutils.analysis.snr

https://specutils.readthedocs.io/en/latest/api/specutils.analysis.fwhm.html#specutils.analysis.fwhm

https://specutils.readthedocs.io/en/latest/api/specutils.analysis.equivalent_width.html#specutils.analysis.equivalent_width

https://specutils.readthedocs.io/en/latest/api/specutils.analysis.line_flux.html#specutils.analysis.line_flux


CHAPTER

TWELVE

SPECTRAL LINE LABELS

SpecViz can display spectral line identifications (“Line labels”) on top of spectral data being displayed. Line identifi-cations are supplied by line lists. There is a set of line lists already included in the distribution, and the user can readhis/hers own line lists as text files formatted in Astropy’s ECSV format.

Once a spectrum is displayed in the plot window, clicking on the “Line Labels” tab in the plug-in sidebar will giveaccess to the line labels tool, which contain the functionality to manage the line lists.

12.1 Selecting line lists

Use the drop-down menu to select a line list. Alternatively, use the File menu button to read a line list from a user-supplied file (see more about that at the end of this page).

Currently, the following line lists are supplied within the package and available via the drop-down menu:

Line list Number of lines Wavelength rangeAtomic-Ionic 42 0.97 - 3.95 𝜇CO 66 1.56 - 2.51 𝜇H-He 145 0.72 - 3.74 𝜇H2 226 1.09 - 3.99 𝜇Common Stellar 95 1,215 - 10,938Common Nebular 51 3,430 - 7,130ILSS 25,800 2,950 - 13,160Reader-Corliss 46,646 16 - 39,985SDSS 48 1,034 - 8,660

Once a line list is selected, a dialog pop-up will ask what is the wavelength range one wants to read from the list. Thedialog is populated by default with the wavelength range spanned by the spectrum being displayed. It can also handleunits like energy and frequency. Typing in new values in the dialog text fields will retain then during subsequent usesof the dialog, until they are re-typed again.

The dialog will display the actual number of lines that will be read from the list. Large numbers of lines trigger analert, in the form of red text.

The two large lists provided within the tol must be handled with care, because if one attempts to read or select the entirelist, some functionality may be affected adversely and become very slow. It is recommended that small wavelengthranges be used with those lists, in a way that no more than about 2,000 lines be read.

45


12.2 Line list management

Each line list, once read, ends up in a table that is placed under a separate tab. The tab name is the list name. Eachtabbed panel contains several sections, described below:

1. Header with descriptive information on the line list.

2. The table itself. The exact column names and contents are list-dependent. Column headers can be clicked;that way, the column is sorted in ascending/descending order upon successive clicks. Hovering the mouse on acolumn heading may bring additional information on the column, such as units.

3. Control section. This contains a number of controls to help configure the display of the selected lines in thetable

Specific lines or groups of lines are selected in the table with the standard selection gestures provided by the underlyingoperating system. To select all lines in a table, click on the upper left corner of the table. To un-select all lines in atable, use the ‘Deselect’ button in the control section.

The ‘Color’, ‘Height’, and ‘Redshift’ controls allow the customization of the plot of the currently selected lines.‘Height’ is interpreted as the fractional height on the plot window. ‘Redshift’ can be interpreted in either ‘z’ or ‘km/s’units, according to the corresponding selector.

12.2.1 List sub-sets

When at least one line is selected in the table, clicking the ‘Create set’ button causes a new list to be built and displayedin a new tab after the ‘Original’ tab. The ‘Original’ tab always contains the entire original list. Successive use of tablerow selection gestures and the ‘Create set’ button, allows the creation of multiple sub sets. Sub-sets can be createdfrom the ‘Original’ list, as well as from any other sub-set.

Each list sub-set carries its own group of display controls: color, height, and redshift. With these, one can customizethe appearance of each sub-set on the plot.

The list sub-set capability can be combined with the column sorting and multiple row selection capabilities to imple-ment hierarchical sorting.

Say, as an example, one wants to display all the Fe lines in blue color, and all the high intensity Fe lines (if intensity isprovided by the line list) in red. One can sort the original table by species, select the subgroup of Fe lines, and createset #1. Next, on the #1 set, one sorts by intensity, selects all the high intensity lines, and creates set #2. One thende-selects everything in the Original set, and selects everything in sets #1 and #2. Finally, in set #1 one picks the bluecolor, and in set #2 the red color. Clicking ‘Draw’ will then plot everything.

12.3 Drawing the line labels

The ‘Draw’ button accomplishes the actual plotting. It works by finding all the lines that are selected in all tabs atonce. Before performing the actual plotting, it will first erase all line labels left on screen by previous drawings. The‘Erase’ button performs the same action, with no subsequent drawing.

At the left lower corner of the window, a counter keeps track of the total of lines selected at any time. The counterbecomes red as a warning that a large number of lines is selected. Plotting a large number of line labels slows downthe plot and zoom functionalities. The user must be aware that the response may become slow when large numbers oflines are selected.

The drawing operation includes a de-cluttering step. This achieves the dual goal of making the plot more readable,and faster to zoom/pan/rescale. The de-cluttering algorithm trades speed for cleverness, and a side effect of that is that,when plotting sets of lines at different heights on screen, some line labels may disappear even though they shouldn’t.Zooming in will eventually make all line labels visible.

46 Chapter 12. Spectral line labels


Experience has shown that the perceived speed depends to a certain amount on the particular hardware and softwareplatform the application is running on. Typically, a slow laptop can handle a couple of hundred lines with no prob-lem. A faster, multi-core desktop can be pushed up to perhaps a thousand line labels before performance degradessignificantly.

12.4 Results

The ‘Plotted’ tab will always contain the lines currently being displayed on the plot. The contents of this tab can beoutput to a ECSV file via the Export button on the top menu bar of the line lists window.

The file thus produced can be directly read by SpecViz via de File button (the yellow folder icon).

Example of an output file in ECSV format:

# %ECSV 0.9# ---# datatype:# - {name: Wavelength, unit: Angstrom, datatype: float64}# - {name: Species, unit: '', datatype: string}# meta: !!omap# - comments: [Common stellar lines., '', Copyrigtht (C) 1999-2004 by Christian Buil, 'http://www.→˓astrosurf.com/buil/us/spe2/hresol5.htm']# schema: astropy-2.0Wavelength Species1215.67 La1238.81 "N V"1242.8 "N V"1393.76 "Si IV"1402.77 "Si IV"

12.4. Results 47


48 Chapter 12. Spectral line labels

Part III

Advanced

49



51



52

CHAPTER

THIRTEEN

DEVELOPER DOCUMENTATION

This set of documentation focuses on the structure of SpecViz, its various pieces, and how they work together. Belowis a simplified reference diagram from some of the core aspects of the SpecViz architecture.

13.1 Data Model

All spectral data are stored internally as specutils.Spectrum1D, but these are exposed in SpecViz through DataItemobjects. These objects are Qt-aware and can interact with the GUI in ways that a simple specutils.Spectrum1D con-tainer cannot. However, individual DataItem objects are immutable in most cases, and only a single list of DataItemobjects are ever maintained in the SpecViz application instance. Instead, PlotDataItem objects are used which in-ternally reference a single DataItem. Multiple PlotDataItem objects can reference the same DataItem, this reducesduplication of data on the user’s disk. Likewise, PlotDataItem objects have many mutable aspects that can be definedon a per-object basis and do not affect the state of the underlying DataItem.

53

https://specutils.readthedocs.io/en/latest/api/specutils.Spectrum1D.html#specutils.Spectrum1D



The central piece of SpecViz is the internal Qt data model expressed in the DataListModel class. It is responsible formaintaining the collection of Spectrum1D objects and exposing them as Qt DataItem objects.

In the context of SpecViz, the Spectrum1D is considered immutable. In a similar sense, DataItem is only a Qt interfaceto an instance of the Spectrum1D class. As such, it is possible to change which Spectrum1D the DataItem contains,but otherwise exposes no other means to change the spectrum in-place.

While SpecViz contains Qt view widgets that expose DataListModel objects (e.g. QListView), this is generallynot done directly. Instead, a proxy model (PlotProxyModel) is used to wrap and expose the DataItem items asPlotDataItem objects. These are fundamentally different from the DataItem objects in that they contain mutableattributes that determine how the DataItem they contain will be expressed in SpecViz. This ranges from whetheror not the item is hidden, what its current plot color is, what its currently user-defined name is, etc. They are alsoworkspace-specific, and not plot window-specific like the PlotProxyModel and PlotDataItem objects.

13.2 Application and Workspaces

The specviz.app.Application is the singular Qt application instance run to begin interacting with SpecViz. It iswithin this class that Workspace instances are generated and maintained. It contains methods for adding, removing,and retrieving workspaces to the application instance. This class is also responsible for parsing and loading anyplugins that exist in the plugins directory as well as adding them to the plugin registry maintained by an instance ofthe Plugin class.

Within a single SpecViz application, multiple, independent Workspace objects can be created. Each workspace itsown internal DataListModel and therefore maintains a completely separate set of data items. Workspaces themselvescontain all the interactive elements a user will see, including the main tool bar, the data items list, plugins, andany number of PlotWindow instances. The display of the data items is handled by the PlotProxyModel, and thisPlotProxyModel is particular to a single PlotWindow. It itself shows all data items that exist in the DataListModel.Opening multiple PlotWindow objects will result in as many PlotProxyModel objects. This is helpful for performancereasons because data in the Workspace instance is never duplicated; these is a single control of data items, and thePlotProxyModel simply handles the display of the data items as PlotDataItem objects.

54 Chapter 13. Developer Documentation






As mentioned, each Workspace can contain multiple PlotWindow objects, and the set of these PlotWindowobjects is handled by the Workspace objects’ QMdiArea widget. The Workspace is also responsible foradding (add_plot_window()), removing (remove_current_window()), and providing access to the current(current_plot_window()), or entire list of, PlotWindow objects. Workspaces also act as the source for events raisedby interacting with both PlotWindow items as well as PlotDataItem objects in the list view widget.

window_activated Fired when a single Workspace becomes current.window_closed Fired when a Workspace is closed.current_item_changed Proxy signal indicating that an item in the list view has changed.current_selected_changed Fired when the selected item in the list view has changed.plot_window_added Fired when a new PlotWindow is added to the Workspace’s QMdiArea widget.plot_window_activated Fired when a PlotWindow becomes active.

Workspace objects also contain the methods for providing the Qt dialogs for loading data (load_data_from_file())using the specutils IO infrastructure, as well as exporting data (_on_export_data()), and deleting data items(_on_delete_data()).

13.3 Plot Windows and Plot Widget

PlotWindow objects are implemented as subclasses of QMdiSubWindow Qt objects. On creation, these sub windowobjects are added to the Workspace object’s QMdiArea and exposed as tabs in the plot window area. Each PlotWindowcontains the set of tools used to interact with the plot directly. This mostly includes things like changing line colors(which will be reflected in colored icon next to the data item in the data item list).

PlotWindow objects are instantiated by their parent Workspace, and are passed a reference to the Workspace ob-ject’s DataListModel. It is the responsibility of the PlotWindow (and, more specifically, the PlotWindow object’sPlotWidget) to create the corresponding PlotProxyModel used for that particular PlotWindow instance. In essence,the PlotWindow is really a container for housing the plot tool bar and the PlotWidget, and generally only containsfunctionality that doesn’t directly involve manipulating the PlotWidget directly.

The PlotWidget is the plotted representation of all the PlotDataItem objects in its internal PlotProxyModel. Thewidget itself is a subclass of PyQtGraph object’s PlotWidget object. Anything that affects the visual representation ofthe loaded data is done in this class. For instance, operations like changing the displayed units of the plot are handledhere, in which case, the PlotWidget updates its local PlotDataItem with the new unit information, triggering thePlotWidget to re-render.

PlotWidget also handles operations like adding/removing ROIs to/from a plot, as well as reporting region selectioninformation for the currently active ROI. In addition, it also contains the methods for adding (add_plot()) and re-moving (remove_plot()) PlotDataItem objects, and responding to changes in their visibility state. The PlotWidgethas several events that other widgets may listen to

plot_added Fired when a PlotDataItem has been added to the plot.plot_removed Fired when a PlotDataItem has been removed from the plot.roi_moved Fired when an ROI has been moved on the plot.roi_removed Fired when an ROI has been removed from the plot.

13.3. Plot Windows and Plot Widget 55


13.4 Plot Proxy Model and Plot Data Items

The PlotProxyModel is a simple wrapper that can be used to expose PlotDataItem objects for use in PlotWindowobjects. When a PlotWindow is created and activated, the parent Workspace receives a signal and sets themodel displayed in the data list view to the PlotWindow object’s PlotProxyModel. The PlotProxyModel it-self is given the source DataListModel model and maintains a dictionary mapping the UUID of each DataItemto the PlotProxyModel-specific PlotDataItem. By overriding the data and setData methods of the parentQSortFilterProxyModel, the PlotProxyModel is able to access information from both the PlotDataItem (e.g.color information, visibility information, etc) as well as from the DataItem (e.g. its name) for use in displayingthe information in data view widgets.

PlotDataItem objects themselves are subclasses of PyQtGraph object’s PlotDataItem class which handles the dis-play of data as Qt GraphicsItem objects. The PlotDataItem class contains extra information about the currentunit definitions and characteristics like color, line width, and visibility of the plot data. As an example, when a userchanges the units displayed for a plot, all plotted PlotDataItem objects have their units converted to the displayedvalues. PlotDataItem objects are also responsible for maintaining the pyqtgraph.ErrorBarItem for the display ofuncertainties that exist on the DataItem.

Likewise, changes to the PlotDataItem raise events that other widgets and objects may listen to

data_unit_changed Fired when the data units of the PlotDataItem have changed.objectspectral_axis_unit_changed Fired when the spectral axis units of the PlotDataItem have changed.color_changed Fired when the color of the PlotDataItem has changed.width_changed Fired when the width of the plotted line for the PlotDataItem has

changed.visibility_changed Fired when the visibility of the PlotDataItem has changed.

13.5 Centralized Hub and Plugins

The Hub class acts as a centralized API source for external functionality (e.g. plugins) to easily interact with the coreSpecViz infrastructure. It is mostly an abstraction over various, perhaps obscured portions of the internal data modeland plotting representations.

The most useful case for the Hub is within plugins. The design of the plugin infrastructure is such that, when adding aclass to the plugin registry, that class is injected with a reference to the Hub and has access to all the abstracted API.

SpecViz plugins are specified by the plugin decorator. When a SpecViz application instance is loaded, the decoratorwill add the plugin to the plugin registry and initialize the class to be added to the application instance. Storing theplugin in the registry allows the class definition to persist through the duration of the application lifetime which isespecially useful in the case of opening e.g. multiple Workspace objects, each of which must then re-initialize anyimported plugins from the registry.

There are three types of plugins for SpecViz:

1. plugin bar plugins: these are added to the right side of SpecViz and are encapsulated in a QTabWidget thatallows the user to select the plugin of interest and have its widget contents displayed in on the side.

2. tool bar plugins: these plugins are added to the top main tool bar of SpecViz and generally contain UI composesas pop-up dialogs or as basic functions.

3. plot bar plugins: these are added to the tool bar within a PlotWindow instance and generally interact with theplot itself.

In the future, the ability to hot-reload or load plugins on demand may be implemented. Likewise, UI elements thatdisplay a list of loaded plugins as well as the ability to disable plugins from being loaded is being considered.


https://pyqtgraph.readthedocs.io/en/latest/graphicsItems/errorbaritem.html#pyqtgraph.ErrorBarItem



13.5. Centralized Hub and Plugins 57


CHAPTER

FOURTEEN

API DOCUMENTATION

14.1 specviz.core

14.2 specviz.core.hub Module

14.2.1 Classes

Hub(workspace, *args, **kwargs) API for accessing the core specviz functions.

Hub

class specviz.core.hub.Hub(workspace, *args, **kwargs)Bases: object

API for accessing the core specviz functions. This acts as a centralized abstracted interface and is automaticallyadded to plugin defintions.

Parameters

workspace[Workspace] The workspace this hub will provide an abstracted interface for.

Attributes Summary

data_item The data item of the currently selected plot item.data_items List of all data items held in the data item model.model The data item model of the active workspace.plot_item The currently selected plot item.plot_items Returns the currently selected plot item.plot_widget The plot widget of the currently active plot window.plot_window The currently selected plot window of the

workspace.plot_windows The currently selected plot window of the

workspace.proxy_model The proxy model of the active workspace.

continues on next page

59

https://docs.python.org/3/library/functions.html#object


Table 2 – continued from previous pageregion_mask Generates a boolean mask based on all current roi

objects in the plot.regions The currently active ROI on the plot.selected_region The currently active ROI on the plot.selected_region_bounds The bounds of currently active ROI on the plot.spectral_regions Currently plotted ROIs returned as a

SpectralRegion.visible_plot_items Plotted data that are currently visible.workspace The active workspace.

Methods Summary

append_data_item(data_item) Adds a new data item object to appear in the left datalist view.

plot_data_item_from_data_item(data_item) Returns the PlotDataItem associated with the pro-vided DataItem.

set_active_plugin_bar([name, index]) Sets the currently displayed widget in the plugin sidepanel.

Attributes Documentation

data_itemThe data item of the currently selected plot item.

data_itemsList of all data items held in the data item model.

modelThe data item model of the active workspace.

plot_itemThe currently selected plot item.

plot_itemsReturns the currently selected plot item.

plot_widgetThe plot widget of the currently active plot window.

plot_windowThe currently selected plot window of the workspace.

plot_windowsThe currently selected plot window of the workspace.

proxy_modelThe proxy model of the active workspace.

region_maskGenerates a boolean mask based on all current roi objects in the plot.

regionsThe currently active ROI on the plot.

60 Chapter 14. API Documentation

https://specutils.readthedocs.io/en/latest/api/specutils.SpectralRegion.html#specutils.SpectralRegion


selected_regionThe currently active ROI on the plot.

selected_region_boundsThe bounds of currently active ROI on the plot.

spectral_regionsCurrently plotted ROIs returned as a SpectralRegion.

visible_plot_itemsPlotted data that are currently visible.

workspaceThe active workspace.

Methods Documentation

append_data_item(data_item)Adds a new data item object to appear in the left data list view.

Parameters

data_item[PlotDataItem] The data item to be added to the list view.

plot_data_item_from_data_item(data_item)Returns the PlotDataItem associated with the provided DataItem.

Parameters

data_item[PlotDataItem] The DataItem from which the associated PlotDataItem will be returned.

Returns

plot_data_item[PlotDataItem] The PlotDataItem wrapping the DataItem.

set_active_plugin_bar(name=None, index=None)Sets the currently displayed widget in the plugin side panel.

Parameters

name[str, optional] The displayed name of the widget in the tab title.

index[int, optional] The index of the widget in the plugin tab widget.

14.2. specviz.core.hub Module 61

https://specutils.readthedocs.io/en/latest/api/specutils.SpectralRegion.html#specutils.SpectralRegion


14.3 specviz.core.items Module

14.3.1 Classes

DataItem(name, identifier, data, *args, **kwargs) A Qt wrapper class around Spectrum1D.PlotDataItem(data_item[, color]) A PyQtGraph PlotDataItem object that wraps a

DataItem object (which in turn wraps a Spectrum1Dobject).

DataItem

class specviz.core.items.DataItem(name, identifier, data, *args, **kwargs)Bases: PyQt5.QtGui.QStandardItem

A Qt wrapper class around Spectrum1D.

Parameters

name[str] The name of this data item.

identifier[uuid.UUID] The UUID of this data item.

data[specutils.Spectrum1D] The internal spectrum object associated with this data item.

Attributes

data_changed[Signal] Fired when the internal stored data is changed.

Attributes Summary

DataRole

IdRole

NameRole

flux The flux values of the stored Spectrum1D object.identifier A unique identifier for the data.name A dislay name for the data.spectral_axis The spectral axis of the stored Spectrum1D object.spectrum The stored Spectrum1D object.uncertainty The flux uncertainty values of the stored Spectrum1D

object.



https://pyqtgraph.readthedocs.io/en/latest/graphicsItems/plotdataitem.html#pyqtgraph.PlotDataItem



https://docs.python.org/3/library/uuid.html#uuid.UUID







Methods Summary

set_data(data) Update the stored Spectrum1D data values.


DataRole = 259

IdRole = 258

NameRole = 257

fluxThe flux values of the stored Spectrum1D object.

identifierA unique identifier for the data.

nameA dislay name for the data.

spectral_axisThe spectral axis of the stored Spectrum1D object.

spectrumThe stored Spectrum1D object.

uncertaintyThe flux uncertainty values of the stored Spectrum1D object.


set_data(data)Update the stored Spectrum1D data values.

PlotDataItem

class specviz.core.items.PlotDataItem(data_item, color=None, *args, **kwargs)Bases: pyqtgraph.graphicsItems.PlotDataItem.PlotDataItem

A PyQtGraph PlotDataItem object that wraps a DataItem object (which in turn wraps a Spectrum1D object).

14.3. specviz.core.items Module 63







https://pyqtgraph.readthedocs.io/en/latest/graphicsItems/plotdataitem.html#pyqtgraph.PlotDataItem



Notes

Currently, the PlotDataItem class does not take in a reference to the data model. This means that it is notlistening to dataChanged signals raised from the data items within the model. Thus, if the data item for this plotdata item is changed, users must call the set_data method on this class to re-render the plot.

There are many different ways to create a PlotDataItem:

Data initialization arguments: (x,y data only)

PlotDataItem(xValues, yValues) x and y values may be any sequence (including ndarray) ofreal numbers

PlotDataItem(yValues) y values only – x will be automatically set to range(len(y))PlotDataItem(x=xValues,y=yValues)

x and y given by keyword arguments

PlotDataItem(ndarray(Nx2)) numpy array with shape (N, 2) where x=data[:,0] andy=data[:,1]

Data initialization arguments: (x,y data AND may include spot style)

Plot-DataItem(recarray)

numpy array with dtype=[('x', float), ('y', float), ...]

PlotDataItem(list-of-dicts)

[{'x': x, 'y': y, ...}, ...]

PlotDataItem(dict-of-lists)

{'x': [...], 'y': [...], ...}

Plot-DataItem(MetaArray)

1D array of Y values with X sepecified as axis values OR 2D array with acolumn ‘y’ and extra columns as needed.

Line style keyword arguments:

con-nect

Specifies how / whether vertexes should be connected. See arrayToQPath()

pen Pen to use for drawing line between points. Default is solid grey, 1px width. Use None todisable line drawing. May be any single argument accepted by mkPen()

shad-ow-Pen

Pen for secondary line to draw behind the primary line. disabled by default. May be anysingle argument accepted by mkPen()

fil-lLevel

Fill the area between the curve and fillLevel

fill-Out-line

(bool) If True, an outline surrounding the fillLevel area is drawn.

fill-Brush

Fill to use when fillLevel is specified. May be any single argument accepted by mkBrush()

step-Mode

(str or None) If “center”, a step is drawn using the x values as boundaries and the giveny values are associated to the mid-points between the boundaries of each step. This iscommonly used when drawing histograms. Note that in this case, len(x) == len(y) + 1 If“left” or “right”, the step is drawn assuming that the y value is associated to the left or rightboundary, respectively. In this case len(x) == len(y) If not passed or an empty string orNone is passed, the step mode is not enabled. Passing True is a deprecated equivalent to“center”. (added in version 0.9.9)


https://pyqtgraph.readthedocs.io/en/latest/functions.html#pyqtgraph.arrayToQPath

https://pyqtgraph.readthedocs.io/en/latest/functions.html#pyqtgraph.mkPen


https://pyqtgraph.readthedocs.io/en/latest/functions.html#pyqtgraph.mkBrush


Point style keyword arguments: (see ScatterPlotItem.setData() for more information)

symbol Symbol to use for drawing points OR list of symbols, one per point. Default is nosymbol. Options are o, s, t, d, +, or any QPainterPath

symbol-Pen

Outline pen for drawing points OR list of pens, one per point. May be any singleargument accepted by mkPen()

symbol-Brush

Brush for filling points OR list of brushes, one per point. May be any single argumentaccepted by mkBrush()

symbol-Size

Diameter of symbols OR list of diameters.

pxMode (bool) If True, then symbolSize is specified in pixels. If False, then symbolSize isspecified in data coordinates.

Optimization keyword arguments:

an-tialias

(bool) By default, antialiasing is disabled to improve performance. Note that in somecases (in particluar, when pxMode=True), points will be rendered antialiased even if thisis set to False.

deci-mate

deprecated.

down-sam-ple

(int) Reduce the number of samples displayed by this value

down-sam-pleMethod

‘subsample’: Downsample by taking the first of N samples. This method is fastest andleast accurate. ‘mean’: Downsample by taking the mean of N samples. ‘peak’: Down-sample by drawing a saw wave that follows the min and max of the original data. Thismethod produces the best visual representation of the data but is slower.

autoDown-sam-ple

(bool) If True, resample the data before plotting to avoid plotting multiple line segmentsper pixel. This can improve performance when viewing very high-density data, but in-creases the initial overhead and memory usage.

clip-ToView

(bool) If True, only plot data that is visible within the X range of the containing ViewBox.This can improve performance when plotting very large data sets where only a fractionof the data is visible at any time.

dy-nam-i-cRange-Limit

(float or None) Limit off-screen positions of data points at large magnification to avoidsdisplay errors. Disabled if None.

iden-tical

deprecated

Meta-info keyword arguments:

name name of dataset. This would appear in a legend





Attributes Summary

color The display color to use for the spectrum.color_changed

data_item The underlying DataItem object.data_unit The unit to use for displaying the flux values in the

underlying Spectrum1D object.data_unit_changed

error_bar_item A PyQtGraph ErrorBarItem to represent the uncer-tainties in the underlying Spectrum1D object.

flux Returns the fluxes of the underlying Spectrum1D ob-ject converted to the current data display units (givenby PlotDataItem.data_unit).

spectral_axis Returns the spectral axis of the underlyingSpectrum1D object converted to the currentspecrtal axis display units (given by PlotDataItem.spectral_axis_unit).

spectral_axis_unit The unit to use for displaying the spectral axis in theunderlying Spectrum1D object.

spectral_axis_unit_changed

uncertainty Returns the uncertainties of the underlyingSpectrum1D object converted to the current datadisplay units (given by PlotDataItem.data_unit).

visibility_changed

visible A boolean value indicating whether the spectrum iscurrently visible.

width The display line width to use for the spectrum.width_changed

zorder A value indicating the order in which plot itemsshould be drawn.

Methods Summary

are_units_compatible(spectral_axis_unit, . . . ) Check whether the specified units are compatiblewith the spectral axis and flux units of the underlyingSpectrum1D object.

getData() Override getData method to ensure that the returnedvalues fit the requirements of the pyqtgraph stepmode: len(x) == len(y) + 1.

is_data_unit_compatible(unit) Check whether the specified unit is compatible withthe flux units of the underlying Spectrum1D object.

is_spectral_axis_unit_compatible(unit) Check whether the specified unit is compatible withthe spectral axis units of the underlying Spectrum1Dobject.














Table 8 – continued from previous pagereset_units() Reset the display units for the spectral axis and the

data to those of the underlying Spectrum1D object.set_data() Sets the spectral_axis and flux.


colorThe display color to use for the spectrum.

color_changed

data_itemThe underlying DataItem object.

data_unitThe unit to use for displaying the flux values in the underlying Spectrum1D object.

data_unit_changed

error_bar_itemA PyQtGraph ErrorBarItem to represent the uncertainties in the underlying Spectrum1D object.

fluxReturns the fluxes of the underlying Spectrum1D object converted to the current data display units (givenby PlotDataItem.data_unit).

spectral_axisReturns the spectral axis of the underlying Spectrum1D object converted to the current specrtal axisdisplay units (given by PlotDataItem.spectral_axis_unit).

spectral_axis_unitThe unit to use for displaying the spectral axis in the underlying Spectrum1D object.


uncertaintyReturns the uncertainties of the underlying Spectrum1D object converted to the current data display units(given by PlotDataItem.data_unit).

If no uncertainties are present, None is returned.

visibility_changed

visibleA boolean value indicating whether the spectrum is currently visible.

widthThe display line width to use for the spectrum.

width_changed

zorderA value indicating the order in which plot items should be drawn.

Larger values indicate items that are drawn later on and therefore will appear in front of other plot items.










https://docs.python.org/3/library/constants.html#None



are_units_compatible(spectral_axis_unit, data_unit)Check whether the specified units are compatible with the spectral axis and flux units of the underlyingSpectrum1D object.

Parameters

spectral_axis_unit[Unit] The spectral axis unit to test

data_unit[Unit] The data unit to test

Returns

boolReturns True if the both the spectral axis and data units are compatble with the underlyingspectrum units, and False otherwise.

getData()Override getData method to ensure that the returned values fit the requirements of the pyqtgraph stepmode: len(x) == len(y) + 1. Necessary for proper performance implementations.

is_data_unit_compatible(unit)Check whether the specified unit is compatible with the flux units of the underlying Spectrum1D object.

Parameters

unit[Unit] The data unit to test

Returns

boolReturns True if the specified data unit is compatible, False otherwise.

is_spectral_axis_unit_compatible(unit)Check whether the specified unit is compatible with the spectral axis units of the underlying Spectrum1Dobject.

Parameters

unit[Unit] The spectral axis unit to test

Returns

boolReturns True if the specified spectral axis unit is compatible, False otherwise.

reset_units()Reset the display units for the spectral axis and the data to those of the underlying Spectrum1D object.

set_data()Sets the spectral_axis and flux. self.flux is called to convert flux units if they had been changed.



https://docs.astropy.org/en/stable/api/astropy.units.Unit.html#astropy.units.Unit


https://docs.python.org/3/library/constants.html#True

https://docs.python.org/3/library/constants.html#False











14.4 specviz.core.models Module

14.4.1 Classes

DataListModel(*args, **kwargs) Base model for all data loaded into specviz.PlotProxyModel([source]) A Qt proxy model that wraps the DataListModel for

use in PlotWidget rendering.

DataListModel

class specviz.core.models.DataListModel(*args, **kwargs)Bases: PyQt5.QtGui.QStandardItemModel

Base model for all data loaded into specviz.

Attributes Summary

data_added

items Retrieves all the DataItem objects in this model.

Methods Summary

add_data(spec, name) Generate and add a DataItem object to the internalQt data model.

clear() Remove all data items.data(index[, role]) Returns information about an item in the model de-

pending on the provided role.item_from_id(identifier) Return a the data item corresponding to a unique

identifier.remove_data(identifier) Removes data given the data item’s UUID.setData(index, value[, role]) This overrides Qt’s setData and automatically up-

dates the name of the item if we are in editing mode.


data_added

itemsRetrieves all the DataItem objects in this model.

14.4. specviz.core.models Module 69



add_data(spec, name)Generate and add a DataItem object to the internal Qt data model.

Parameters

spec[Spectrum1D] The spectrum object containing data about the spectrum.

name[str] Display string of this data item.

clear()Remove all data items.

data(index, role=0)Returns information about an item in the model depending on the provided role.

item_from_id(identifier)Return a the data item corresponding to a unique identifier.

Parameters

identifier[UUID] Assigned id of the DataItem object.

Returns

DataItemThe corresponding data item.

remove_data(identifier)Removes data given the data item’s UUID.

Parameters

identifier[UUID] Assigned id of the DataItem object.

setData(index, value, role=2)This overrides Qt’s setData and automatically updates the name of the item if we are in editing mode.

PlotProxyModel

class specviz.core.models.PlotProxyModel(source=None, *args, **kwargs)Bases: PyQt5.QtCore.QSortFilterProxyModel

A Qt proxy model that wraps the DataListModel for use in PlotWidget rendering. Instances of this classwill be set as the source model for data views in the GUI, and provides extra information from the internalPlotDataItem objects used as wrappers for loaded data items.

Parameters

source[DataListModel] The source data model instance the proxied by this model.






Attributes Summary

items Returns a list of PlotDataItem instances in theproxy model.

Methods Summary

data(index[, role]) Overrides Qt’s data method to provide informationbased on the specified Qt role from either plot dataitems or data items.

item_from_id(identifier) Retrieves a PlotDataItem from the UUID of aDataItem.

item_from_index(index) Given a QModelIndex object, retrieves the sourceDataItem, and from that, the proxy model’sPlotDataItem.

setData(index, value[, role]) Overrides the Qt setData method to define a valuefor a given role.


itemsReturns a list of PlotDataItem instances in the proxy model.


data(index, role=0)Overrides Qt’s data method to provide information based on the specified Qt role from either plot dataitems or data items.

Parameters

index[qtpy.QtCore.QModelIndex] The DataListModel model index for this item.

role[Qt role] The default role for the data retrieval of this item.

Returns

variousThe data requested for the particular role.

item_from_id(identifier)Retrieves a PlotDataItem from the UUID of a DataItem.

Parameters

identifier[uuid.UUID] The UUID of the DataItem.

14.4. specviz.core.models Module 71



Returns

item[PlotDataItem] The PlotDataItem corresponding to the UUID.

item_from_index(index)Given a QModelIndex object, retrieves the source DataItem, and from that, the proxy model’sPlotDataItem.

Parameters

index[QModelIndex] The model index of the desired PlotDataItem.

Returns

item[PlotDataItem] The plot data item corresponding to the given index.

setData(index, value, role=2)Overrides the Qt setData method to define a value for a given role.

Parameters

index[qtpy.QtCore.QModelIndex] The DataListModel model index for this item.

value[various] The value to set the data item for the particular role to.

role[Qt role] The default role for the data that will have its value set.

Returns

boolWhether the role was successfully set.

14.5 specviz.core.plugin Module

14.5.1 Classes

DecoratorRegistry(*args, **kwargs) Base class for any decorator-based registry.Plugin(*args, **kwargs) Decorator for plugin classes.



DecoratorRegistry

class specviz.core.plugin.DecoratorRegistry(*args, **kwargs)Bases: object

Base class for any decorator-based registry.

Attributes Summary

registry Returns the list of registered decorators

Methods Summary

get_action(parent[, level]) Creates nested menu actions depending on the user-created plugin decorator location values.


registryReturns the list of registered decorators


static get_action(parent, level=None)Creates nested menu actions depending on the user-created plugin decorator location values.

Plugin

class specviz.core.plugin.Plugin(*args, **kwargs)Bases: specviz.core.plugin.DecoratorRegistry

Decorator for plugin classes.

For example, to decorate a specific plugin class as well define a tool bar plugin, you would do:

@plugin("Custom Dialog")class MyPlyginDialog(QDialog):

@plugin.tool_bar("Open Custom Dialog", icon=...)def open_dialog(self):

14.5. specviz.core.plugin Module 73

https://docs.python.org/3/library/functions.html#object


Methods Summary

__call__(name[, priority]) Wraps the class and adds the decorated class to theregistry.

mount(workspace[, filt]) Load all the plugins in the registry into the specifiedworkspace.

plot_bar(name[, icon, location, priority]) Generate a decorator for a callback method that canbe triggered by a button in the plot tool bar.

plugin_bar(name, icon[, priority]) Generate a decorator for a callback method that canbe triggered by a tab on the right of the window.

tool_bar(name[, icon, location, priority]) Generate a decorator for a callback method that canbe triggered by a button in the application tool bar.


__call__(name, priority=0)Wraps the class and adds the decorated class to the registry.

Parameters

name[str] Name of plugin.

priority[int] The priority of when this plugin is loaded. Lower == sooner.

Returns

plugin_decorator[func] The function to wrap the decorated class.

mount(workspace, filt=None)Load all the plugins in the registry into the specified workspace.

Parameters

workspace[Workspace] The workspace to load the plugins in.

filt[{None, ‘tool_bar’, ‘plot_bar’}, optional] The type of plugin to load. If not specified, allplugins are loaded.

plot_bar(name, icon=None, location=None, priority=0)Generate a decorator for a callback method that can be triggered by a button in the plot tool bar.

Parameters

name[str] The name of the tool to add

icon[QIcon] The icon for the tool




location[int] If specified, can be used to customize the position of the icon in the tool bar.

priority[int, optional] The priority to use to load in the plugins - a higher value means the pluginwill be loaded sooner.

plugin_bar(name, icon, priority=0)Generate a decorator for a callback method that can be triggered by a tab on the right of the window.

Parameters

name[str] The name of the tab

icon[QIcon, optional] The icon for the tab


tool_bar(name, icon=None, location=None, priority=0)Generate a decorator for a callback method that can be triggered by a button in the application tool bar.

Parameters

name[str] The name of the tool to add

icon[QIcon] The icon for the tool

location[int] If specified, can be used to customize the position of the icon in the tool bar.


14.6 specviz.plugins

14.7 specviz.plugins.arithmetic Package

14.7.1 Functions

Arithmetic A plugin that can show a dialog to allow users to definederived variables.

14.7. specviz.plugins.arithmetic Package 75

Arithmetic

specviz.plugins.arithmetic.Arithmetic = <function Arithmetic>A plugin that can show a dialog to allow users to define derived variables.

14.7.2 Classes

EquationEditor(equation_editor[, label, . . . ]) A Qt dialog where users can enter expressions to calcu-late variables derived from other variables.

EquationEditor

class specviz.plugins.arithmetic.EquationEditor(equation_editor, label=None, equation=None,parent=None)

Bases: PyQt5.QtWidgets.QDialog

A Qt dialog where users can enter expressions to calculate variables derived from other variables.

Dialog where you specify equation names and expressions.

Attributes Summary

placeholder_text

tip_text


placeholder_text = "Type any mathematical expression here - you can include attribute names from the drop-down below by selecting them and clicking 'Insert'."

tip_text = "Note: The spectrum names in the expression should be surrounded by {{ }} brackets (e.g. {{{example1}}}), and you you can use libraries imported in the namespace (numpy, specutils, etc). Objects returned from editor must be type Spectrum1D! Example expressions: - Double the flux of '{example1}': {{{example1}}} * 2 - Add two Spectrum1D objects: {{{example1}}}*2 + {{{example2}}} - Subtract two Spectrum1D objects: {{{example1}}}*2 - {{{example2}}} - Use Spectrum1D API: Spectrum1D(spectral_axis={{{example1}}}.wavelength,flux={{{example1}}}.flux)"

14.8 specviz.plugins.model_editor Package

14.8.1 Functions

ContinuumGenerator Auto-generates a continuum using the specutilsfit_generic_continuum() function.

ModelEditor Qt widget for interacting with the model editor function-ality in SpecViz.


https://specutils.readthedocs.io/en/latest/api/specutils.fitting.fit_generic_continuum.html#specutils.fitting.fit_generic_continuum

ContinuumGenerator

specviz.plugins.model_editor.ContinuumGenerator = <function ContinuumGenerator>Auto-generates a continuum using the specutils fit_generic_continuum() function.

ModelEditor

specviz.plugins.model_editor.ModelEditor = <function ModelEditor>Qt widget for interacting with the model editor functionality in SpecViz. This class is responsible for populatingthe values and handling user interactions such as adding/removing models, accessing the arithmetic editor andallows for parameter editing.

14.9 specviz.plugins.smoothing Package

14.9.1 Functions

SmoothingDialog Widget to handle user interactions with smoothing op-erations.

SmoothingDialog

specviz.plugins.smoothing.SmoothingDialog = <function SmoothingDialog>Widget to handle user interactions with smoothing operations. Allows the user to select spectra, kernel type andkernel size. It utilizes smoothing functions in manipulation. Assigns the smoothing workload to a QTreadinstance.

14.10 specviz.plugins.statistics Package

14.10.1 Functions

StatisticsWidget This widget controls the statistics box.

StatisticsWidget

specviz.plugins.statistics.StatisticsWidget = <function StatisticsWidget>This widget controls the statistics box. It is responsible for calling stats computation functions and updating thestats widget. It only takes the owner workspace’s current data item and selected region for stats computations.The stats box can be updated by calling the update_statistics function.

14.10. specviz.plugins.statistics Package 77

https://specutils.readthedocs.io/en/latest/api/specutils.fitting.fit_generic_continuum.html#specutils.fitting.fit_generic_continuum

https://specutils.readthedocs.io/en/latest/manipulation.html#module-specutils.manipulation

14.11 specviz.plugins.unit_change Package

14.11.1 Functions

UnitChangeDialog A dialog box that allows the user to change units

UnitChangeDialog

specviz.plugins.unit_change.UnitChangeDialog = <function UnitChangeDialog>A dialog box that allows the user to change units

14.12 specviz.plugins.line_labels Package

14.12.1 Functions

LineListsPlugin Top class for the line labels plugin.

LineListsPlugin

specviz.plugins.line_labels.LineListsPlugin = <function LineListsPlugin>Top class for the line labels plugin. This is the class that handles the line lists window, where the user managesand interacts with the line lists.

This class acts as a interface adapter of sorts for the actual class that does the work, LineListsWindow.

14.13 specviz.utils

14.14 specviz.utils.helper_functions Module

14.14.1 Functions

format_float_text(value) Auto-format a floating point value as text, automaticallychoosing scientific or floating-point notation as appro-priate.


format_float_text

specviz.utils.helper_functions.format_float_text(value)Auto-format a floating point value as text, automatically choosing scientific or floating-point notation as appro-priate.

Parameters

value[float or Quantity] The value to format.

Returns

strThe formatted string.

14.15 specviz.widgets

14.16 specviz.widgets.custom Module

14.16.1 Classes

LinearRegionItem(*args, **kwargs) Subclass of pyqtgraph’s LinearRegionItem to provideextra methods for handling events and dealing with se-lection color changes.

TabBarPlus(*args, **kwargs) Tab bar that has a plus button floating to the right of thetabs.

PlotSizeDialog(*args, **kwargs) Displays a modal dialog prompting the user for the ex-ported image dimensions.

LinearRegionItem

class specviz.widgets.custom.LinearRegionItem(*args, **kwargs)Bases: pyqtgraph.graphicsItems.LinearRegionItem.LinearRegionItem

Subclass of pyqtgraph’s LinearRegionItem to provide extra methods for handling events and dealing withselection color changes.

Create a new LinearRegionItem.

14.16. specviz.widgets.custom Module 79

https://docs.python.org/3/library/functions.html#float

https://docs.astropy.org/en/stable/api/astropy.units.Quantity.html#astropy.units.Quantity

https://pyqtgraph.readthedocs.io/en/latest/graphicsItems/linearregionitem.html#pyqtgraph.LinearRegionItem

https://pyqtgraph.readthedocs.io/en/latest/graphicsItems/linearregionitem.html#pyqtgraph.LinearRegionItem


Ar-gu-ments:val-ues

A list of the positions of the lines in the region. These are not limits; limits can be set by specifyingbounds.

ori-en-ta-tion

Options are ‘vertical’ or ‘horizontal’, indicating the The default is ‘vertical’, indicating that the

brush Defines the brush that fills the region. Can be any arguments that are valid for mkBrush. Default istransparent blue.

pen The pen to use when drawing the lines that bound the region.hov-er-Brush

The brush to use when the mouse is hovering over the region.

hov-er-Pen

The pen to use when the mouse is hovering over the region.

mov-able

If True, the region and individual lines are movable by the user; if False, they are static.

boundsOptional [min, max] bounding values for the regionspan Optional [min, max] giving the range over the view to draw the region. For example, with a vertical

line, use span=(0.5, 1) to draw only on the top half of the view.swap-Mode

Sets the behavior of the region when the lines are moved such that their order reverses. “block” meansthe user cannot drag one line past the other. “push” causes both lines to be moved if one would crossthe other. “sort” means that lines may trade places, but the output of getRegion always gives the linepositions in ascending order. None means that no attempt is made to handle swapped line positions.The default is “sort”.

Attributes Summary

name The name of this linear region item.selected

Methods Summary

mouseClickEvent(ev) Intercepts mouse click events.





nameThe name of this linear region item.

Returns

strName of the region.

selected


mouseClickEvent(ev)Intercepts mouse click events.

Parameters

ev[QMouseEvent] The qt event object.

TabBarPlus

class specviz.widgets.custom.TabBarPlus(*args, **kwargs)Bases: PyQt5.QtWidgets.QTabBar

Tab bar that has a plus button floating to the right of the tabs.

Attributes Summary

plusClicked

Methods Summary

movePlusButton() Move the plus button to the correct location.resizeEvent(event) Resize the widget and make sure the plus button is in

the correct location.sizeHint() Return the size of the TabBar with increased width

for the plus button.tabLayoutChange() This virtual handler is called whenever the tab layout

changes.

14.16. specviz.widgets.custom Module 81



plusClicked


movePlusButton()Move the plus button to the correct location.

resizeEvent(event)Resize the widget and make sure the plus button is in the correct location.

sizeHint()Return the size of the TabBar with increased width for the plus button.

tabLayoutChange()This virtual handler is called whenever the tab layout changes. If anything changes make sure the plusbutton is in the correct location.

PlotSizeDialog

class specviz.widgets.custom.PlotSizeDialog(*args, **kwargs)Bases: PyQt5.QtWidgets.QDialog

Displays a modal dialog prompting the user for the exported image dimensions.

14.17 specviz.widgets.delegates Module

14.17.1 Classes

DataItemDelegate(*args, **kwargs) A Qt item delegate class for DataItem.

DataItemDelegate

class specviz.widgets.delegates.DataItemDelegate(*args, **kwargs)Bases: PyQt5.QtWidgets.QStyledItemDelegate

A Qt item delegate class for DataItem.

Methods Summary

paint(painter, option, index) This overrides Qt’s QStyledItemDelegate.paintmethod to customize the appearance of the data item.




paint(painter, option, index)This overrides Qt’s QStyledItemDelegate.paint method to customize the appearance of the data item.

14.18 specviz.widgets.plotting Module

14.18.1 Classes

PlotWindow(model, *args, **kwargs) Displayed plotting subwindow available in theQMdiArea.

PlotWidget([title, model, visible]) The Qt widget housing all aspects of a single plot win-dow.

PlotWindow

class specviz.widgets.plotting.PlotWindow(model, *args, **kwargs)Bases: PyQt5.QtWidgets.QMdiSubWindow

Displayed plotting subwindow available in the QMdiArea.

Attributes Summary

color_changed

current_item The currently selected plot data item.plot_widget Return the embedded plot widgetproxy_model The proxy model defined in the internal plot widget.tool_bar Return the tool bar for the embedded plot widget.width_changed

window_removed

Methods Summary

closeEvent(event) Called by qt when window closes, upon which itemits the window_removed signal.

14.18. specviz.widgets.plotting Module 83



color_changed

current_itemThe currently selected plot data item.

plot_widgetReturn the embedded plot widget

proxy_modelThe proxy model defined in the internal plot widget.

tool_barReturn the tool bar for the embedded plot widget.

width_changed

window_removed


closeEvent(event)Called by qt when window closes, upon which it emits the window_removed signal.

Parameters

event :ignored in this implementation.

PlotWidget

class specviz.widgets.plotting.PlotWidget(title=None, model=None, visible=True, *args, **kwargs)Bases: pyqtgraph.widgets.PlotWidget.PlotWidget

The Qt widget housing all aspects of a single plot window. This includes axes, plot data items, labels, etc.

Upon initialization of a new plot widget, items from the DataListModel are added to the plot. The first item thatis added defines the units for the entire plot. Subsequent data items will attempt to have their units converted.

Parameters

title[str] The title of this particular plot window.

model[DataListModel] The core model for this specviz instance. This will be referenced througha proxy model when used for plotting.

visible[bool, optional] This overrides the individual plot data item visibility on initialization of theplot widget.

Attributes



plot_added[None] Fired when a plot data item has been added to the plot widget.

plot_removed[None] Fired when a plot data item has been removed from the plot widget.

roi_moved[Signal] Fired when region is moved. Delivers the range of region as tuple.

roi_removed[Signal] Fired when region is removed. Delivers the region removed.

mouse_enterexit[Signal] Fired when mouse enters or exits the window. Delivers the event type.

When initializing PlotWidget, parent and background are passed to GraphicsWidget.__init__() and all oth-ers are passed to PlotItem.__init__().

Attributes Summary

data_unit The current data unit used for displaying the spec-trum.

data_unit_changed

mouse_enterexit

plot_added

plot_removed

proxy_model The proxy model being used by this plot widget.roi_moved

roi_removed

selected_region The currently selected region object.selected_region_bounds The bounds of the currently selected region as a tuple

of Quantity objects.spectral_axis_unit The current spectral axis unit used for displaying the

spectrum.spectral_axis_unit_changed

title The title of the widget.




Methods Summary

add_plot([item, index, visible, initialize]) Adds a plot data item given an index in the currentplot sub window’s proxy model, or if given the itemexplicitly.

change_width(size) Change the width of every plot data item rendered onthe plot.

check_plot_compatibility() Checks for unit compatibility between this plot wid-get and all plot data items currently in the proxymodel.

clear_plots() Removes all plots from the plot widget.enterEvent(event) Intercept qt mode enter event and raise event type.initialize_plot([data_unit, spectral_axis_unit]) Routine to re-configure the display settings of the

plot to fit the plotted data and re-assess the physicaltype and unit information of the data.

leaveEvent(event) Intercept qt mode enter event and raise event type.list_all_regions() Get all region items in ploton_item_changed(item) Called when the user clicks the item’s checkbox.remove_plot([item, index, start, end]) Removes a plot data item given an index in the cur-

rent plot sub window’s proxy model.set_data_unit(unit) Sets the data unit and emits a signal telling interested

parties of the change.set_spectral_axis_unit(unit) Sets the spectral axis unit and emits a signal telling

interested parties of the change.


data_unitThe current data unit used for displaying the spectrum.

data_unit_changed

mouse_enterexit

plot_added

plot_removed

proxy_modelThe proxy model being used by this plot widget.

roi_moved

roi_removed

selected_regionThe currently selected region object.

selected_region_boundsThe bounds of the currently selected region as a tuple of Quantity objects.




spectral_axis_unitThe current spectral axis unit used for displaying the spectrum.


titleThe title of the widget.


add_plot(item=None, index=None, visible=True, initialize=False)Adds a plot data item given an index in the current plot sub window’s proxy model, or if given the itemexplicitly.

Parameters

item[PlotDataItem] The item in the proxy model to add to this plot.

index[QModelIndex] The index in the model of the data item associated with this plot.

visible[bool] Sets the initial visibility state of this plot item.

initialize[bool] Whether the plot should re-evaluate axis labels and re-configure axis bounds.

change_width(size)Change the width of every plot data item rendered on the plot. This currently does not include uncertaintyindicators.

Parameters

size[int] The new width of the rendered lines.

Notes

Enabling a width greater than 1 will automatically enable opengl and use the user’s gpu to render the plot.If the user has not set the global pyqtgraph opengl option to true, opengl will be disabled when the userreturns the size to 1.

check_plot_compatibility()Checks for unit compatibility between this plot widget and all plot data items currently in the proxymodel. If an item is not compatible, its state is set to disabled and the user will not be able to plot it in theplot widget.

clear_plots()Removes all plots from the plot widget.

enterEvent(event)Intercept qt mode enter event and raise event type.

Parameters



event[QMouseEvent] The intercepted event.

initialize_plot(data_unit=None, spectral_axis_unit=None)Routine to re-configure the display settings of the plot to fit the plotted data and re-assess the physicaltype and unit information of the data.

Parameters

data_unit[str or Unit] The data unit used for the display of the y axis.

spectral_axis_unit[str or Unit] The spectral axis unit used for the display of the x axis.

leaveEvent(event)Intercept qt mode enter event and raise event type.

Parameters

event[QMouseEvent] The intercepted event.

list_all_regions()Get all region items in plot

on_item_changed(item)Called when the user clicks the item’s checkbox.

remove_plot(item=None, index=None, start=None, end=None)Removes a plot data item given an index in the current plot sub window’s proxy model.

Parameters

item[PlotDataItem] The item in the proxy model to remove from this plot.

index[QModelIndex] The index in the model of the data item associated with this plot.

start[int] The starting index in the model item list.

end[int] The ending index in the model item list.

set_data_unit(unit)Sets the data unit and emits a signal telling interested parties of the change.

Parameters

unit[Unit] The unit to which the data axis will be converted.

set_spectral_axis_unit(unit)Sets the spectral axis unit and emits a signal telling interested parties of the change.

Parameters






unit[Unit] The unit to which the spectral axis will be converted.

14.19 specviz.widgets.workspace Module

14.19.1 Classes

Workspace(*args, **kwargs) A widget representing the primary interaction area for agiven workspace.

Workspace

class specviz.widgets.workspace.Workspace(*args, **kwargs)Bases: PyQt5.QtWidgets.QMainWindow

A widget representing the primary interaction area for a given workspace. This includes the QListView, and theQMdiArea widgets, and associated model information.

Attributes

window_activated[qtpy.QtCore.Signal] Fired when a particular QMainWindow is activated.

window_closed[qtpy.QtCore.Signal] Fired when a sub window is closed.

current_item_changed[qtpy.QtCore.Signal] Fired when the an item in the view has changed.

current_selected_changed: ``qtpy.QtCore.Signal``Fired when the currently selected item in the view has changed.

plot_window_added[qtpy.QtCore.Signal] Fired when a new plot window is added to the workspace.

plot_window_activated[qtpy.QtCore.Signal] Fired when a plto window in the workspace has become active.

Attributes Summary

current_item Get the currently selected PlotDataItem.current_item_changed

current_plot_window Get the current active plot window tab.current_selected_changed

model The data model for this workspace.name The name of this workspace.plot_window_activated


14.19. specviz.widgets.workspace Module 89



Table 40 – continued from previous pageplot_window_added

proxy_model The proxy model of the currently active plot window.selected_region Get the current selected region.selected_region_pos Get the range of the current selected region.window_activated

window_closed

Methods Summary

add_plot_window() Creates a new plot widget sub window and adds it tothe workspace.

closeEvent(a0) Overrides the Qt close event to also emit a signal.display_load_data_error(exp) Display error message box when attempting to load

a data set.event(e) Scrape window events.export_data_item(data_item, filename, fmt) Exports the currently selected data item to an ECSV

file.force_plot(data_item) Enabled checkbox and highlight row of the

PlotDataItem representing the provided data_iteminstance.

load_data_from_file(file_path[, . . . ]) Loads spectral data from a given file path and a fileloader

read_data_file(file_path[, file_loader]) Read spectral data from file given file path andloader.

remove_current_window() Removes the current plot window from theworkspace.

set_embedded(embed) Toggles the visibility of certain parts of the ui tomake it more amenable to being embedded in otherapplications.


current_itemGet the currently selected PlotDataItem.

current_item_changed

current_plot_windowGet the current active plot window tab.

current_selected_changed

modelThe data model for this workspace.



Note: there is always at most one model per workspace.

nameThe name of this workspace.

plot_window_activated

plot_window_added

proxy_modelThe proxy model of the currently active plot window.

selected_regionGet the current selected region.

selected_region_posGet the range of the current selected region. Returns a tuple of Qualities (left, right).

window_activated

window_closed


add_plot_window()Creates a new plot widget sub window and adds it to the workspace.

closeEvent(a0)Overrides the Qt close event to also emit a signal.

Parameters

a0[list] Close even arguments.

display_load_data_error(exp)Display error message box when attempting to load a data set.

Parameters

exp[str] Error text.

event(e)Scrape window events.

export_data_item(data_item, filename, fmt)Exports the currently selected data item to an ECSV file.

Parameters

data_item[PlotDataItem] Data item containing the spectrum to be exported to disk

14.19. specviz.widgets.workspace Module 91


filename[str] Path of the file to be created on export

fmt[str] Format to be used by IO registry for writing Spectrum1D

force_plot(data_item)Enabled checkbox and highlight row of the PlotDataItem representing the provided data_item instance.

Parameters

data_item[DataItem] The data item for which specviz will force render the plot.

load_data_from_file(file_path, file_loader=None, multi_select=True)Loads spectral data from a given file path and a file loader

This is a high-level function that is intended to be used both by GUI functionality, and also programmati-cally if necessary. By default, if the given file contains multiple spectra, a dialog will be presented to theuser to select which spectra to load. If multi_select=False, no dialog will be displayed and all spectrain the file will be loaded.

Parameters

file_path[str] Path to location of the spectrum file.

file_loader[str, or None] Format specified for the astropy io interface. If None, attempts to automati-cally select loader based on file type.

multi_select[bool] If True, displays dialog for choosing spectra to load from file. This only occurs ifthe file loader returns multiple spectra.

read_data_file(file_path, file_loader=None)Read spectral data from file given file path and loader.

Parameters

file_path[str] Path to location of the spectrum file.

file_loader[str] Format specified for the astropy io interface.

Returns

: SpectrumListA SpectrumList instance containing the spectra loaded from the file

remove_current_window()Removes the current plot window from the workspace.

set_embedded(embed)Toggles the visibility of certain parts of the ui to make it more amenable to being embedded in otherapplications.


https://docs.python.org/3/library/stdtypes.html#str

https://docs.python.org/3/library/stdtypes.html#str




https://specutils.readthedocs.io/en/latest/api/specutils.SpectrumList.html#specutils.SpectrumList

https://specutils.readthedocs.io/en/latest/api/specutils.SpectrumList.html#specutils.SpectrumList

PYTHON MODULE INDEX

sspecviz.core.hub, 59specviz.core.items, 62specviz.core.models, 69specviz.core.plugin, 72specviz.plugins.arithmetic, 75specviz.plugins.line_labels, 78specviz.plugins.model_editor, 76specviz.plugins.smoothing, 77specviz.plugins.statistics, 77specviz.plugins.unit_change, 78specviz.utils.helper_functions, 78specviz.widgets.custom, 79specviz.widgets.delegates, 82specviz.widgets.plotting, 83specviz.widgets.workspace, 89

93


94 Python Module Index

INDEX

Symbols__call__() (specviz.core.plugin.Plugin method), 74

Aadd_data() (specviz.core.models.DataListModel

method), 70add_plot() (specviz.widgets.plotting.PlotWidget

method), 87add_plot_window() (specviz.widgets.workspace.Workspace

method), 91append_data_item() (specviz.core.hub.Hub method),

61are_units_compatible()

(specviz.core.items.PlotDataItem method),68

Arithmetic (in module specviz.plugins.arithmetic), 76

Cchange_width() (specviz.widgets.plotting.PlotWidget

method), 87check_plot_compatibility()

(specviz.widgets.plotting.PlotWidget method),87

clear() (specviz.core.models.DataListModel method),70

clear_plots() (specviz.widgets.plotting.PlotWidgetmethod), 87

closeEvent() (specviz.widgets.plotting.PlotWindowmethod), 84

closeEvent() (specviz.widgets.workspace.Workspacemethod), 91

color (specviz.core.items.PlotDataItem attribute), 67color_changed (specviz.core.items.PlotDataItem at-

tribute), 67color_changed (specviz.widgets.plotting.PlotWindow

attribute), 84ContinuumGenerator (in module

specviz.plugins.model_editor), 77current_item (specviz.widgets.plotting.PlotWindow at-

tribute), 84current_item (specviz.widgets.workspace.Workspace

attribute), 90

current_item_changed(specviz.widgets.workspace.Workspace at-tribute), 90

current_plot_window (specviz.widgets.workspace.Workspaceattribute), 90

current_selected_changed(specviz.widgets.workspace.Workspace at-tribute), 90

Ddata() (specviz.core.models.DataListModel method), 70data() (specviz.core.models.PlotProxyModel method),

71data_added (specviz.core.models.DataListModel at-

tribute), 69data_item (specviz.core.hub.Hub attribute), 60data_item (specviz.core.items.PlotDataItem attribute),

67data_items (specviz.core.hub.Hub attribute), 60data_unit (specviz.core.items.PlotDataItem attribute),

67data_unit (specviz.widgets.plotting.PlotWidget at-

tribute), 86data_unit_changed (specviz.core.items.PlotDataItem

attribute), 67data_unit_changed (specviz.widgets.plotting.PlotWidget

attribute), 86DataItem (class in specviz.core.items), 62DataItemDelegate (class in specviz.widgets.delegates),

82DataListModel (class in specviz.core.models), 69DataRole (specviz.core.items.DataItem attribute), 63DecoratorRegistry (class in specviz.core.plugin), 73display_load_data_error()

(specviz.widgets.workspace.Workspacemethod), 91

EenterEvent() (specviz.widgets.plotting.PlotWidget

method), 87EquationEditor (class in specviz.plugins.arithmetic), 76

95


error_bar_item (specviz.core.items.PlotDataItem at-tribute), 67

event() (specviz.widgets.workspace.Workspacemethod), 91

export_data_item() (specviz.widgets.workspace.Workspacemethod), 91

Fflux (specviz.core.items.DataItem attribute), 63flux (specviz.core.items.PlotDataItem attribute), 67force_plot() (specviz.widgets.workspace.Workspace

method), 92format_float_text() (in module

specviz.utils.helper_functions), 79

Gget_action() (specviz.core.plugin.DecoratorRegistry

static method), 73getData() (specviz.core.items.PlotDataItem method), 68

HHub (class in specviz.core.hub), 59

Iidentifier (specviz.core.items.DataItem attribute), 63IdRole (specviz.core.items.DataItem attribute), 63initialize_plot() (specviz.widgets.plotting.PlotWidget

method), 88is_data_unit_compatible()

(specviz.core.items.PlotDataItem method),68

is_spectral_axis_unit_compatible()(specviz.core.items.PlotDataItem method),68

item_from_id() (specviz.core.models.DataListModelmethod), 70

item_from_id() (specviz.core.models.PlotProxyModelmethod), 71

item_from_index() (specviz.core.models.PlotProxyModelmethod), 72

items (specviz.core.models.DataListModel attribute), 69items (specviz.core.models.PlotProxyModel attribute),

71

LleaveEvent() (specviz.widgets.plotting.PlotWidget

method), 88LinearRegionItem (class in specviz.widgets.custom), 79LineListsPlugin (in module

specviz.plugins.line_labels), 78list_all_regions() (specviz.widgets.plotting.PlotWidget

method), 88

load_data_from_file()(specviz.widgets.workspace.Workspacemethod), 92

Mmodel (specviz.core.hub.Hub attribute), 60model (specviz.widgets.workspace.Workspace attribute),

90ModelEditor (in module specviz.plugins.model_editor),

77module

specviz.core.hub, 59specviz.core.items, 62specviz.core.models, 69specviz.core.plugin, 72specviz.plugins.arithmetic, 75specviz.plugins.line_labels, 78specviz.plugins.model_editor, 76specviz.plugins.smoothing, 77specviz.plugins.statistics, 77specviz.plugins.unit_change, 78specviz.utils.helper_functions, 78specviz.widgets.custom, 79specviz.widgets.delegates, 82specviz.widgets.plotting, 83specviz.widgets.workspace, 89

mount() (specviz.core.plugin.Plugin method), 74mouse_enterexit (specviz.widgets.plotting.PlotWidget

attribute), 86mouseClickEvent() (specviz.widgets.custom.LinearRegionItem

method), 81movePlusButton() (specviz.widgets.custom.TabBarPlus

method), 82

Nname (specviz.core.items.DataItem attribute), 63name (specviz.widgets.custom.LinearRegionItem at-

tribute), 81name (specviz.widgets.workspace.Workspace attribute),

91NameRole (specviz.core.items.DataItem attribute), 63

Oon_item_changed() (specviz.widgets.plotting.PlotWidget

method), 88

Ppaint() (specviz.widgets.delegates.DataItemDelegate

method), 83placeholder_text (specviz.plugins.arithmetic.EquationEditor

attribute), 76plot_added (specviz.widgets.plotting.PlotWidget at-

tribute), 86

96 Index


plot_bar() (specviz.core.plugin.Plugin method), 74plot_data_item_from_data_item()

(specviz.core.hub.Hub method), 61plot_item (specviz.core.hub.Hub attribute), 60plot_items (specviz.core.hub.Hub attribute), 60plot_removed (specviz.widgets.plotting.PlotWidget at-

tribute), 86plot_widget (specviz.core.hub.Hub attribute), 60plot_widget (specviz.widgets.plotting.PlotWindow at-

tribute), 84plot_window (specviz.core.hub.Hub attribute), 60plot_window_activated

(specviz.widgets.workspace.Workspace at-tribute), 91

plot_window_added (specviz.widgets.workspace.Workspaceattribute), 91

plot_windows (specviz.core.hub.Hub attribute), 60PlotDataItem (class in specviz.core.items), 63PlotProxyModel (class in specviz.core.models), 70PlotSizeDialog (class in specviz.widgets.custom), 82PlotWidget (class in specviz.widgets.plotting), 84PlotWindow (class in specviz.widgets.plotting), 83Plugin (class in specviz.core.plugin), 73plugin_bar() (specviz.core.plugin.Plugin method), 75plusClicked (specviz.widgets.custom.TabBarPlus at-

tribute), 82proxy_model (specviz.core.hub.Hub attribute), 60proxy_model (specviz.widgets.plotting.PlotWidget

attribute), 86proxy_model (specviz.widgets.plotting.PlotWindow at-

tribute), 84proxy_model (specviz.widgets.workspace.Workspace at-

tribute), 91

Rread_data_file() (specviz.widgets.workspace.Workspace

method), 92region_mask (specviz.core.hub.Hub attribute), 60regions (specviz.core.hub.Hub attribute), 60registry (specviz.core.plugin.DecoratorRegistry at-

tribute), 73remove_current_window()

(specviz.widgets.workspace.Workspacemethod), 92

remove_data() (specviz.core.models.DataListModelmethod), 70

remove_plot() (specviz.widgets.plotting.PlotWidgetmethod), 88

reset_units() (specviz.core.items.PlotDataItemmethod), 68

resizeEvent() (specviz.widgets.custom.TabBarPlusmethod), 82

roi_moved (specviz.widgets.plotting.PlotWidget at-tribute), 86

roi_removed (specviz.widgets.plotting.PlotWidgetattribute), 86

Sselected (specviz.widgets.custom.LinearRegionItem at-

tribute), 81selected_region (specviz.core.hub.Hub attribute), 60selected_region (specviz.widgets.plotting.PlotWidget

attribute), 86selected_region (specviz.widgets.workspace.Workspace

attribute), 91selected_region_bounds (specviz.core.hub.Hub

attribute), 61selected_region_bounds

(specviz.widgets.plotting.PlotWidget attribute),86

selected_region_pos (specviz.widgets.workspace.Workspaceattribute), 91

set_active_plugin_bar() (specviz.core.hub.Hubmethod), 61

set_data() (specviz.core.items.DataItem method), 63set_data() (specviz.core.items.PlotDataItem method),

68set_data_unit() (specviz.widgets.plotting.PlotWidget

method), 88set_embedded() (specviz.widgets.workspace.Workspace

method), 92set_spectral_axis_unit()

(specviz.widgets.plotting.PlotWidget method),88

setData() (specviz.core.models.DataListModelmethod), 70

setData() (specviz.core.models.PlotProxyModelmethod), 72

sizeHint() (specviz.widgets.custom.TabBarPlusmethod), 82

SmoothingDialog (in modulespecviz.plugins.smoothing), 77

spectral_axis (specviz.core.items.DataItem attribute),63

spectral_axis (specviz.core.items.PlotDataItem at-tribute), 67

spectral_axis_unit (specviz.core.items.PlotDataItemattribute), 67

spectral_axis_unit (specviz.widgets.plotting.PlotWidgetattribute), 86

spectral_axis_unit_changed(specviz.core.items.PlotDataItem attribute), 67

spectral_axis_unit_changed(specviz.widgets.plotting.PlotWidget attribute),87

spectral_regions (specviz.core.hub.Hub attribute), 61spectrum (specviz.core.items.DataItem attribute), 63specviz.core.hub

Index 97


module, 59specviz.core.items

module, 62specviz.core.models

module, 69specviz.core.plugin

module, 72specviz.plugins.arithmetic

module, 75specviz.plugins.line_labels

module, 78specviz.plugins.model_editor

module, 76specviz.plugins.smoothing

module, 77specviz.plugins.statistics

module, 77specviz.plugins.unit_change

module, 78specviz.utils.helper_functions

module, 78specviz.widgets.custom

module, 79specviz.widgets.delegates

module, 82specviz.widgets.plotting

module, 83specviz.widgets.workspace

module, 89StatisticsWidget (in module

specviz.plugins.statistics), 77

TTabBarPlus (class in specviz.widgets.custom), 81tabLayoutChange() (specviz.widgets.custom.TabBarPlus

method), 82tip_text (specviz.plugins.arithmetic.EquationEditor at-

tribute), 76title (specviz.widgets.plotting.PlotWidget attribute), 87tool_bar (specviz.widgets.plotting.PlotWindow at-

tribute), 84tool_bar() (specviz.core.plugin.Plugin method), 75

Uuncertainty (specviz.core.items.DataItem attribute), 63uncertainty (specviz.core.items.PlotDataItem at-

tribute), 67UnitChangeDialog (in module

specviz.plugins.unit_change), 78

Vvisibility_changed (specviz.core.items.PlotDataItem

attribute), 67visible (specviz.core.items.PlotDataItem attribute), 67

visible_plot_items (specviz.core.hub.Hub attribute),61

Wwidth (specviz.core.items.PlotDataItem attribute), 67width_changed (specviz.core.items.PlotDataItem at-

tribute), 67width_changed (specviz.widgets.plotting.PlotWindow

attribute), 84window_activated (specviz.widgets.workspace.Workspace

attribute), 91window_closed (specviz.widgets.workspace.Workspace

attribute), 91window_removed (specviz.widgets.plotting.PlotWindow

attribute), 84Workspace (class in specviz.widgets.workspace), 89workspace (specviz.core.hub.Hub attribute), 61

Zzorder (specviz.core.items.PlotDataItem attribute), 67

98 Index

specviz documentationin the above case, the loader registry functionality will attempt to select the...

Documents