stips 2.2.2__tar.gz → 2.3.1__tar.gz

{stips-2.2.2 → stips-2.3.1}/.github/workflows/ci_workflows.yml

@@ -14,21 +14,21 @@ jobs:
       matrix:
         include:
 
-          - name: Python 3.10
+          - name: Python 3.11
             os: ubuntu-latest
-            python: "3.10"
+            python: "3.11"
 
-          - name: Python 3.11
+          - name: Python 3.13
             os: ubuntu-latest
-            python: 3.11
+            python: 3.13
 
-          - name: Python 3.11 Mac
+          - name: Python 3.13 Mac
             os: macos-latest
-            python: 3.11
+            python: 3.13
 
           - name: Python Long
             os: ubuntu-latest
-            python: 3.11
+            python: 3.13
 
     steps:
     - name: Checkout code
@@ -72,7 +72,7 @@ jobs:
       with:
         activate-environment: stips
         environment-file: environment.yml
-        python-version: 3.11
+        python-version: 3.13
         auto-activate-base: false
 
     - name: Build Docs

{stips-2.2.2 → stips-2.3.1}/.rtd-environment.yml

@@ -2,12 +2,9 @@ name: stips
 
 channels:
   - conda-forge
-  - astropy
-  - http://ssb.stsci.edu/astroconda
-  - defaults
 
 dependencies:
-  - python>=3.7
+  - python>=3.10
   - astropy
 
   # Docs

{stips-2.2.2 → stips-2.3.1}/CHANGES.rst

@@ -5,13 +5,39 @@ Release Notes
 Version History and Change Log
 ------------------------------
 
+Version 2.3.1
+=============
+- Fixed a bug with unit conversion for Pandeia backgrounds
+- Fixed a bug that prevented use of cached PSFs with STPSF v2.0.0, slowing ``fast_galaxy`` simulations
+- Added FITS header outputs for original input X and Y positions alongside those for the PSF interpolation
+- Implemented dynamic calculation of zeropoints based on WFI throughput files from the user's local Pandeia reference data
+- Imposed and documented photon and electron unit equivalence since STIPS assumes a quantum efficiency of 1
+- Added documentation about the now uneditable 3x3 ``psf_grid_size``
+- Added documentation about installing STIPS with alternate package managers
+- Updated pandeia version to be >= 2025.9 and utilities infrastructure to handle new reference data in 2026.1
+- Allowed newer versions of poppy >= 1.0.3
+- Updated contact information for Roman Help Desk
+
+Version 2.3.0
+=============
+- Added support for F213 filter.
+- Updated constants for PHOTPLAM (pivot wavelength) and mirror area.
+- Allowed users to specify ``psf_cache_location`` in ``addCatalogue`` function.
+- Transitioned detector naming convention from 'SCANN' to 'WFINN' to match other Roman SOC simulation tools.
+- Fixed bug with reading Internal tables.
+- Updated pandeia version to be >= 2024.12
+- Updated WebbPSF to STPSF and constrained version to be >= 2.0.0
+- Updated documentation to reflect that STIPS creates an intermediate product between L2 and L3 images.
+- Added documentation on (non-physical) gaps in the Phoenix grid.
+- Added citation to STIPS paper.
+
 Version 2.2.2
 =============
 - Updated pandeia.engine version to be >= 3.1 instead of == 3.1
 
 Version 2.2.1
 =============
-- Fixed a bug on the version of STIPS in __init__.py
+- Fixed a bug on the version of STIPS in ``__init__.py``
 - Updated WebbPSF version to be >= 1.1.1 instead of == 1.1.1
 - Updated synphot>=1.1.1 and stsynphot>=1.1.0 from forced to specific version.
 
@@ -32,7 +58,6 @@ Version 2.1.0
 
 Version 2.0.0
 =============
-
 - STIPS now uses an ePSF, and calculates source appearance on a per-source basis
 - Dropped support for python 2, and python <= 3.7
 - Dropped support for HST and JWST instruments
@@ -48,13 +73,13 @@ Version 1.0.8
 
 **STIPS Improvements**
 
-- PSFs generated with `webbpsf` are now PSF grids. [:pr:``, :user:`york-stsci`]
-- STIPS has the option to keep all data in memory. [:pr:``, :user:`york-stsci`]
+- PSFs generated with ``webbpsf`` are now PSF grids. [:pr:`77`, :user:`york-stsci`]
+- STIPS has the option to keep all data in memory. [:pr:`77`, :user:`york-stsci`]
 - Data files have been removed from the repo to allow STIPS to be uploaded to PyPi (pip). The data has been migrated to a STScI box folder. Users can now download the data and set their `stips_data` to allow access to the data that once lived in the repository. [:pr:`59`, :user:`york-stsci`]
 - Travis was setup to run and pass tests. Outdated tests have been removed to allow Travis to pass. [:pr:`65`, :user:`robelgeda`]
 - Test data has been moved to a STScI box folder. [:pr:`64`, :user:`robelgeda`]
-- `dev` folder added for any developer related tools. [:pr:`69`, :user:`robelgeda`]
-- Frozen environments saved at `dev/conda_envs`. [:pr:`69`, :user:`robelgeda`]
+- ``dev`` folder added for any developer related tools. [:pr:`69`, :user:`robelgeda`]
+- Frozen environments saved at ``dev/conda_envs``. [:pr:`69`, :user:`robelgeda`]
 
 Version 1.0.7
 =============
@@ -67,7 +92,7 @@ Version 1.0.7
 - environment.yml added for easy conda env build. [:pr:`42`, :user:`robelgeda`]
 - Read the Docs documentation established. [:pr:`55`, :user:`robelgeda`]
 - F062 filter added to Roman WFI. [:pr:`51`, :user:`york-stsci`]
-- Update STIPS to use WbbPSF 0.9.0. [:pr:`51`, :user:`york-stsci`]
+- Update STIPS to use WebbPSF 0.9.0. [:pr:`51`, :user:`york-stsci`]
 - Travis CI initiated for unit and regression testing. [:pr:`40`, :user:`robelgeda`]
 - Python version set to 3.7 [:pr:`40`, :user:`robelgeda`]
 - Licenses updated [:pr:`40`, :user:`robelgeda`]
@@ -76,8 +101,8 @@ Version 1.0.7
 
 - Updated astro_image.py to use a PC matrix rather than a CD matrix for the image WCS, which hopefully will result in astropy actually giving you a correctly formatted FITS WCS. [:pr:`46`, :user:`york-stsci`]
 - Adding WCS information to PSF files. PSF files will now have the following:
+
     - RA equal to the observation RA at which they were produced
     - DEC equal to the observation DEC at which they were produced
     - PA equal to the observation PA at which they were produced
-    - CDELT keywords equal to the PIXELSCL keyword, but adjusted to degrees rather than arcsec.
-    - [:pr:`47`, :user:`york-stsci`]
+    - CDELT keywords equal to the PIXELSCL keyword, but adjusted to degrees rather than arcsec. [:pr:`47`, :user:`york-stsci`]

stips-2.3.1/CITATION.cff

@@ -0,0 +1,41 @@
+cff-version: 1.2.0
+message: "If you use this software, please cite it as below."
+authors:
+- name: "STIPS Development Team"
+- family-names: "Gomez"
+  given-names: "Sebastian"
+  orcid: "https://orcid.org/0000-0001-6395-6702"
+- family-names: "Bellini"
+  given-names: "Andrea"
+  orcid: "https://orcid.org/0000-0003-3858-637X"
+- family-names: "Al-Kowsi"
+  given-names: "Hanna"
+- family-names: "Desjardins"
+  given-names: "Tyler"
+  orcid: "https://orcid.org/0000-0001-6905-1859"
+- family-names: "Geda"
+  given-names: "Robel"
+  orcid: "https://orcid.org/0000-0003-1509-9966"
+- family-names: "Han"
+  given-names: "Eunkyu"
+  orcid: "https://orcid.org/0000-0001-9797-0019"
+- family-names: "Otor"
+  given-names: "O. Justin"
+  orcid: "https://orcid.org/0000-0002-4679-5692"
+- family-names: "Riedel"
+  given-names: "Adric"
+  orcid: "https://orcid.org/0000-0003-1645-8596"
+- family-names: "Ryan"
+  given-names: "Russell"
+  orcid: "https://orcid.org/0000-0003-0894-1588"
+- family-names: "Spitzer"
+  given-names: "Isaac"
+- family-names: "York"
+  given-names: "Brian"
+title: "STIPS"
+version: 2.3.1
+doi: https://doi.org/10.5281/zenodo.15232587
+date-released: 2026-05-08
+url: "https://github.com/spacetelescope/STScI-STIPS"
+
+# see a full list of contributors here: https://github.com/spacetelescope/STScI-STIPS/graphs/contributors

{stips-2.2.2 → stips-2.3.1}/Dockerfile

@@ -1,5 +1,4 @@
 FROM continuumio/miniconda3
-MAINTAINER Space Telescope Science Institute <help@stsci.edu>
 
 #########
 # Setup #

{stips-2.2.2/stips.egg-info → stips-2.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: stips
-Version: 2.2.2
+Version: 2.3.1
 Summary: STIPS is the Space Telescope Imaging Product Simulator.
 Home-page: https://github.com/spacetelescope/STScI-STIPS
 Author: Space Telescope Science Institute
@@ -12,8 +12,9 @@ Requires-Dist: scipy
 Requires-Dist: photutils
 Requires-Dist: synphot>=1.1.1
 Requires-Dist: stsynphot>=1.1.0
-Requires-Dist: webbpsf>=1.1.1
-Requires-Dist: pandeia.engine>=3.1
+Requires-Dist: stpsf>=2.0.0
+Requires-Dist: poppy>=1.0.3
+Requires-Dist: pandeia.engine>=2025.9
 Requires-Dist: montage-wrapper
 Requires-Dist: pyyaml
 Requires-Dist: soc_roman_tools

{stips-2.2.2 → stips-2.3.1}/README.md

@@ -2,6 +2,7 @@
 
 [![Build Status](https://github.com/spacetelescope/STScI-STIPS/actions/workflows/ci_workflows.yml/badge.svg?branch=main)](https://github.com/spacetelescope/STScI-STIPS/actions/workflows/ci_workflows.yml?query=branch:main)
 [![STScI](https://img.shields.io/badge/powered%20by-STScI-blue.svg?colorA=707170&colorB=3e8ddd&style=flat)](http://www.stsci.edu)
+[![DOI](https://zenodo.org/badge/94350619.svg)](https://zenodo.org/badge/latestdoi/94350619)
 
 For documentation and installation instructions please visit https://stips.readthedocs.io
 
@@ -21,8 +22,10 @@ It does not include instrument saturation effects.
 
 ## Why use STIPS?
 
-STIPS is intended to produce quick simulations of Level 2 (L2) images, and is provided for
-cases where [Pandeia](https://pypi.org/project/pandeia.engine) does not
+STIPS is intended to produce quick simulations that are corrected for distortion, but not mosaicked.
+We note there is no equivalent flight product, since Roman Level 3 (L3) files are both distortion
+corrected and mosaicked, while Level 2 (L2) files are neither. STIPS is ideal for
+cases where `Pandeia <https://pypi.org/project/pandeia.engine/>`_ does not
 provide a large enough simulation area (e.g., full-detector or multiple-detector
 observations). STIPS obtains its Roman instrument and filter values from
 Pandeia, so it should produce output within 10% of output produced by Pandeia.
@@ -43,3 +46,27 @@ developed by Andrea Bellini ([@AndreaBellini](https://github.com/AndreaBellini))
 
 ![Alt text](docs/roman_figures/stips_demo.png?raw=true "Roman WFI Image of a Star Cluster and Background Galaxies")
 
+## Citation
+
+If you use STIPS, please cite the [STIPS PASP Paper](https://ui.adsabs.harvard.edu/abs/2024PASP..136l4502S/abstract) that describes the code.
+
+```
+@ARTICLE{2024PASP..136l4502S,
+       author = {{Stips Development Team} and {Gomez}, Sebastian and {Bellini}, Andrea and {Al-Kowsi}, Hanna and {Desjardins}, Tyler and {Geda}, Robel and {Han}, Eunkyu and {Otor}, O. Justin and {Riedel}, Adric and {Ryan}, Russell and {Spitzer}, Isaac and {York}, Brian},
+        title = "{STIPS: The Nancy Grace Roman Space Telescope Imaging Product Simulator}",
+      journal = {\pasp},
+     keywords = {Astronomical techniques, Telescopes, Astronomical methods, 1684, 1689, 1043, Astrophysics - Instrumentation and Methods for Astrophysics},
+         year = 2024,
+        month = dec,
+       volume = {136},
+       number = {12},
+          eid = {124502},
+        pages = {124502},
+          doi = {10.1088/1538-3873/ad9524},
+archivePrefix = {arXiv},
+       eprint = {2411.11978},
+ primaryClass = {astro-ph.IM},
+       adsurl = {https://ui.adsabs.harvard.edu/abs/2024PASP..136l4502S},
+      adsnote = {Provided by the SAO/NASA Astrophysics Data System}
+}
+```

{stips-2.2.2 → stips-2.3.1}/docs/basic_tutorial.rst

@@ -29,7 +29,7 @@ an output set of the following form:
 
     Pandeia version a.b.c with Data Version a.b.c. at /Some/Path/To/pandeia_refdata
 
-    Webbpsf Version d.e.f with Data Version d.e.f at /Some/Path/To/webbpsf_data_path
+    STPSF Version d.e.f with Data Version d.e.f at /Some/Path/To/stpsf_data_path
 
 
 Setting Up Some Basics

{stips-2.2.2 → stips-2.3.1}/docs/bugs.rst

@@ -14,9 +14,11 @@ removed from this list as they are addressed in future STIPS updates.
 * The flux measurements of sources are only validated in the absence of noise/background.
   As such, the net flux of the image may be inaccurate.
 
-* STIPS interpolates nine PSFs generated by WebbPSF across the detector to the location of the
+* STIPS interpolates nine PSFs generated by STPSF across the detector to the location of the
   source being placed. However, there is currently a known offset of 20 pixels (in both the
   X and Y directions) between the location at which the PSF is interpolated, and the
+  location at which the target is displayed. The header of the output image lists both of these locations:
+  'x' and 'y' for the location at which the PSF is interpolated and 'x_input' and 'y_input' for the
   location at which the target is displayed.
 
   .. note::
@@ -26,7 +28,7 @@ removed from this list as they are addressed in future STIPS updates.
     (x, y) but the interpolated PSF shape will be the shape of the PSF at location (x+20, y+20).
     Because the WFI PSF shape does not vary strongly over this distance, the effect is
     minimal and should not be a concern for most science cases. If ultra-precise PSF models
-    are required, the user should generate them directly with WebbPSF at the desired pixel
+    are required, the user should generate them directly with STPSF at the desired pixel
     location.
 
 * Bright sources will have large diffraction spikes that are visible beyond 22 pixels away

{stips-2.2.2 → stips-2.3.1}/docs/conf.py

@@ -67,6 +67,7 @@ extensions = [
     'sphinx.ext.mathjax',
     'sphinx.ext.viewcode',
     'sphinx_rtd_theme',
+    'sphinx_issues'
 ]
 
 numpydoc_show_class_members = False
@@ -186,4 +187,4 @@ if eval(setup_cfg.get('edit_on_github')):
     edit_on_github_doc_root = "docs"
 
 # -- Resolving issue number to links in changelog -----------------------------
-github_issues_url = 'https://github.com/{0}/issues/'.format(setup_cfg['github_project'])
+issues_default_group_project = setup_cfg['github_project']  # for sphinx_issues

{stips-2.2.2 → stips-2.3.1}/docs/examples.rst

@@ -47,7 +47,6 @@ scene with the Roman WFI F129 filter offset by 0.5 degrees in RA and rotated by
             'filters': ['F129'],
             'detectors': 1,
             'distortion': False,
-            'oversample': 5,
             'pupil_mask': '',
             'background': 'avg',
             'observations_id': 1,

stips-2.3.1/docs/help.rst

@@ -0,0 +1,9 @@
+****
+Help
+****
+
+For assistance with STIPS, please visit the
+`Roman Help Desk <https://stsci.service-now.com/roman>`_. After logging in to
+your account, select "Get Help" and then the "Simulators and Tools" category.
+Mention STIPS in the subject line and include relevant details in the
+description of the resulting form.

{stips-2.2.2 → stips-2.3.1}/docs/index.rst

@@ -1,10 +1,6 @@
 Documentation
 =============
 
-.. note::
-
-  As of version 2.0, STIPS no longer offers support for HST or JWST.
-
 Overview
 --------
 STIPS is the Space Telescope Imaging Product Simulator. It is designed to create
@@ -14,9 +10,15 @@ instrumental distortion (if available) as well as calibration residuals from fla
 dark currents, and cosmic rays. It automatically includes Poisson noise and readout noise.
 It does not include instrument saturation effects.
 
+.. note::
+
+  As of version 2.0, STIPS no longer offers support for HST or JWST.
+
 Why use STIPS?
 --------------
-STIPS is intended to produce quick simulations of Level 2 (L2) images, and is provided for
+STIPS is intended to produce quick simulations that are corrected for distortion, but not mosaicked.
+We note there is no equivalent flight product, since Roman Level 3 (L3) files are both distortion
+corrected and mosaicked, while Level 2 (L2) files are neither. STIPS is ideal for
 cases where `Pandeia <https://pypi.org/project/pandeia.engine/>`_ does not
 provide a large enough simulation area (e.g., full-detector or multiple-detector
 observations). STIPS obtains its Roman instrument and filter values from

{stips-2.2.2 → stips-2.3.1}/docs/installation.rst

@@ -9,18 +9,14 @@ in this section along with instructions.
 STIPS Requirements
 ##################
 
-* ``pandeia>=3.1``: Exposure time calculator.
+* ``pandeia>=2025.9``: Exposure time calculator.
 
-* ``webbpsf>=1.1.1``: Nancy Grace Roman PSF calculator. STIPS also requires that ``poppy``, a
-  support package used by WebbPSF, have version ``>=1.0.3``.
+* ``stpsf>=2.0.0``: Nancy Grace Roman PSF calculator. STIPS also requires that ``poppy``, a
+  support package used by STPSF (Formerly WebbPSF), have version ``>=1.0.3``.
 
-* ``astropy``: STIPS uses Astropy in order to:
-
-    * Read and write FITS files.
-
-    * Read and write ASCII tables (specifically in the IPAC format).
-
-    * Generate Sersic profile models (if any are in the generated scene).
+* ``astropy``: STIPS uses Astropy in order to read and write ASCII tables
+  (specifically in the IPAC format) and FITS files, as well as to generate
+  Sersic profile models (if any are in the generated scene).
 
 * ``montage_wrapper``: STIPS uses ``montage`` to generate mosaics. It is
   only imported if STIPS is asked to generate a multi-detector image.
@@ -49,14 +45,18 @@ STIPS Requirements
 Finally, STIPS requires a set of data files whose location is marked by setting the
 environment variable ``stips_data``, which will be installed as part of these instructions.
 
-Installing Using Conda and Source Code
-######################################
+Installing Using a Package Manager and Source Code
+##################################################
 
-STIPS can be installed using the source code and a Conda environment file.
-If you do not have Anaconda or Miniconda installed, please visit the
-`Anaconda docs <https://docs.anaconda.com/anaconda/install/>`_ for installation instructions.
-We have included a Conda environment file for easily installing or updating Conda packages
-to meet STIPS requirements.  Please follow the steps below to install STIPS:
+STIPS can be installed using one of the YAML files provided in its source code.
+These YAML files define an environment that a package manager like
+`Micromamba <https://mamba.readthedocs.io/en/latest/installation/micromamba-installation.html>`_,
+`Mamba <https://mamba.readthedocs.io/en/latest/installation/mamba-installation.html>`_,
+`Conda <https://docs.anaconda.com/anaconda/install/>`_, or another can read and
+install on your machine.
+(If you don't have a package manager, follow any of the preceding links for
+installation instructions.) The YAML files include all packages required by
+STIPS. Please follow the steps below to install STIPS.
 
 .. _installing-as-a-user:
 
@@ -74,15 +74,19 @@ Installing as a User
 
 #. The environment file can be used in two ways:
 
-   * To create a new Conda environment named ``stips``::
+   * To create a new environment named ``stips``::
 
         conda env create -f environment.yml
         conda activate stips
 
 
-   * Or, to install to or update an existing Conda environment::
+   * Or, to install to or update an existing environment::
+
+        conda env update --name <EXISTING-ENV> --file environment.yml
 
-        conda env update --name EXISTING-ENV --file environment.yml
+(If you are using mamba, substitute it for ``conda`` in the commands above.
+If you are using micromamba, substitute it for ``conda`` and also remove
+``env`` in the commands above.)
 
 Installing as a Developer
 *************************
@@ -94,10 +98,17 @@ Installing as a Developer
 
 .. _downloading-required-ref-data:
 
+Installing with pip
+*******************
+
+While it is possible to install STIPS with ``pip`` instead of a package manager,
+we recommend the latter due to the aforementioned warning about using ``pip``
+with the ``esutil`` package.
+
 Downloading Required Reference Data
 ************************************
 
-STIPS, Pandeia, and WebbPSF need the reference datasets.
+STIPS, Pandeia, and STPSF require additional reference datasets.
 You will need to download the data and add them to your environmental path.
 
 1. Add the following paths to your bash environmental path. It is recommended that you add the path to your ``.bash_profile`` file:
@@ -105,9 +116,12 @@ You will need to download the data and add them to your environmental path.
 .. code-block:: text
 
 	export stips_data="<absolute_path_to_this_folder>/ref_data/stips_data"
-	export WEBBPSF_PATH="<absolute_path_to_this_folder>/ref_data/webbpsf-data"
+	export STPSF_PATH="<absolute_path_to_this_folder>/ref_data/stpsf-data"
 	export PYSYN_CDBS="<absolute_path_to_this_folder>/ref_data/grp/redcat/trds"
-	export pandeia_refdata="<absolute_path_to_this_folder>/ref_data/pandeia_data-x.x.x_roman"
+	export pandeia_refdata="<absolute_path_to_this_folder>/ref_data/pandeia_data-xxxx.x_roman"
+
+  # if your Pandeia installation is 2026.1 or higher, add the following:
+  export PSF_DIR="<absolute_path_to_this_folder>/ref_data/pandeia_psfs-xxxx.x_roman"
 
 .. note::
 
@@ -115,19 +129,25 @@ You will need to download the data and add them to your environmental path.
 
 2. ``cd`` into the ``ref_data`` directory in your ``STScI-STIPS`` clone.
 
-3. Run the following code (after ensuring your ``stips`` Conda environment is active)::
+3. Run the following code (after ensuring your package manager's ``stips`` environment is active)::
 
 		python retrieve_stips_data.py
 
+.. caution::
+
+  Running ``retrieve_stips_data.py`` will fetch the latest versions of each
+  package's reference data. If you have manually configured your software
+  environment to use other versions of any of these packages, download their
+  reference data separately and configure your environment variables
+  appropriately to avoid confusion.
 
 Testing Installation
 *********************
 
 To test if all the required files have been installed, please import STIPS in Python::
 
-    bash-3.2$ python
-    Python 3.11.9 | packaged by conda-forge | (main, Apr 19 2024, 18:45:13)
-    [Clang 16.0.6 ] on darwin
+    bash-3.2$ python3
+    Python 3.11.15 | packaged by conda-forge | (main, Mar  5 2026, 16:58:53) [Clang 19.1.7 ] on darwin
     Type "help", "copyright", "credits" or "license" for more information.
 
     >>> import stips
@@ -138,13 +158,13 @@ You should receive an output of the following form:
 
 .. code-block:: text
 
-  STIPS Version x.y.z with Data Version x.y.z at /Some/Path/To/stips_data
+  STIPS Version x.y.z with Data Version a.b.c at /Some/Path/To/stips_data.
 
-  STIPS Grid Generated with x.y.z
+  STIPS Grid Generated with STIPS Version x.y.z.
 
-  Pandeia version a.b.c with Data Version a.b.c. at /Some/Path/To/pandeia_refdata
+  Pandeia Version YYYY.n with Data Version YYYY.n at /Some/Path/To/pandeia_refdata.
 
-  Webbpsf Version d.e.f with Data Version d.e.f at /Some/Path/To/webbpsf_data_path
+  STPSF Version d.e.f with Data Version d.e.f at /Some/Path/To/stpsf_data_path.
 
 
 Ignore the following warning message if it appears:

{stips-2.2.2 → stips-2.3.1}/docs/release.rst

@@ -2,9 +2,41 @@
 Developer Release Instructions
 ******************************
 
-This page offers a complete walkthrough on how to prepare and release a new
-version of STIPS on GitHub and PyPI, as well as how to sync the ReadTheDocs
-documentation with the new release.
+This page offers a complete walkthrough on how to update the STIPS reference
+data, prepare and release a new version of STIPS on GitHub and PyPI, and sync
+the ReadTheDocs documentation with the new release.
+
+Reference data
+==============
+
+**Not every release will require an update to the reference data.** If one is
+necessary, begin by incrementing the version number in ``VERSION.txt`` at the
+base of the reference data directory.
+
+Next, regenerate the Phoenix grid by running ``stips/data/CreatePhoenixGrid.py``
+from the STIPS GitHub repository. (The file may run for an extended period.)
+Save the results to the reference data directory's ``grid/`` folder. There
+should be a ``.npy`` file for each WFI imaging filter, a coordinates file
+(``input.pkl``), and a grid-specific version file.
+
+Copy existing files from the ``test/`` folder and, if necessary, add any that
+are needed to run new tests added to the GitHub codebase during the development
+cycle. The ``.db`` files and ``residual_files`` folder at the base of the
+reference data directory can be copied as they are.
+
+Add notes on any oddities or adjustments to the reference data in ``NOTES.txt``
+at the base of the reference data directory. Finally, use the following command
+to compress the files while making sure that they will have the name STIPS
+expects (``stips_data``) when they are unzipped. Don't accidentally delete the carat (^):
+
+.. code-block:: text
+
+    tar -czvf stips_data-X.Y.Z.tgz -s /^YOUR-DIR-NAME/stips_data/ YOUR-DIR-NAME
+
+Upload the zipped reference data file to Box with the name
+``stips_data-X.Y.Z.tgz``, substituting in the version numbers selected in the
+first paragraph. **Wait to update** ``stips_data_current.tgz`` until you've
+completed the software release on GitHub.
 
 Pre-merge instructions
 ======================
@@ -24,7 +56,9 @@ intended for a release:
     * ``environment.yml``
     * ``environment_dev.yml``
     * ``docs/installation.rst``
-    * ``ret_data/retrieve_stips_data.py``
+    * ``docs/requirements.txt``
+    * ``ref_data/retrieve_stips_data.py``
+    * ``utilities/utilities.py`` (if any reference data links have changed)
 
 * Are you able to install the new version of STIPS locally with ``pip`` and ``conda``?
 
@@ -32,6 +66,8 @@ intended for a release:
 
 * Has ``CHANGES.rst`` been updated to include the current release and its associated updates at the top?
 
+* Has ``CITATION.cff`` been updated with the relevant values in its ``version`` and ``date-released`` fields?
+
 * Are all CI tests in the release's pull request passing?
 
 * Has at least one developer given the pull request an official approval on GitHub?
@@ -45,6 +81,17 @@ Post-merge instructions
 Tagging the merge commit
 ------------------------
 
+On your machine, check out the branch that tracks the official ``main`` branch
+on the ``spacetelescope`` remote. Rebase it so it includes the newly merged pull
+request. (If your local names for that branch or the ``spacetelescope`` remote
+are different than the defaults – ``main`` and ``origin``, respectively – be
+sure to substitute them in below.)
+
+.. code-block:: text
+
+    git checkout origin main
+    git rebase origin/main
+
 Apply a tag to the merge commit, substituting in the proper version number.
 
 .. code-block:: text
@@ -58,9 +105,7 @@ Apply a tag to the merge commit, substituting in the proper version number.
    and `adding it to your account <https://docs.github.com/en/authentication/managing-commit-signature-verification/adding-a-gpg-key-to-your-github-account>`_
    if you don't have one.
 
-Next, push the tag online. (If your remote that points to ``spacetelescope``'s
-online version of the repository is not named ``origin``, be sure to substitute
-its name in below.)
+Push the tag online.
 
 .. code-block:: text
 
@@ -76,7 +121,7 @@ manually create a new release in the ``spacetelescope/STScI-STIPS`` GitHub repos
 #. Press the "Draft a new release" button above the list of releases.
 #. Press "Choose a tag" and select the one you just pushed online. The target branch should already be selected as ``main``.
 #. Press "Generate release notes" to list the commits included in this release.
-#. In the "Release title" textbox, type ``Release X.Y.Z``, substituting in the proper version number.
+#. In the "Release title" textbox, type ``STIPS Version X.Y.Z``, substituting in the proper version number.
 #. Above the list of commits in the larger textbox for comments, write a single-sentence summary of the release's major updates.
 #. Press "Publish" to complete this section.
 
@@ -131,12 +176,18 @@ Finally, upload them to PyPI:
 
 .. code-block:: text
 
-    python setup.py sdist bdist_wheel
+    python -m twine upload dist/*
 
 Note that PyPI uploads now require an API token.
 `Refer to their instructions <https://pypi.org/help/#apitoken>`_ if you haven't
 yet set one up.
 
+
+.. note::
+
+  If you updated the reference data, now is the proper time to update
+  ``stips_data_current.tgz`` on Box.
+
 While the official release is now complete, keep reading for instructions on
 updating the documentation on ReadTheDocs.
 
@@ -152,8 +203,14 @@ commit will be the repository's current latest commit, so both versions should
 be identical for the moment.
 
 The versions of the documentation that should be visible to the public and
-marked as "Active" on their "Edit" pages are ``latest`` and the new release,
-``vX.Y.Z``. In the future, we may make past versions visible, too.
+marked as "Active" on their "Edit" pages are ``main``, ``latest``, and the new
+release, ``vX.Y.Z``. On `the "Versions" page <https://readthedocs.org/projects/stips/versions/>`_,
+press "Edit" beside any other publicly visible versions and select the "Hidden"
+checkbox for them. In the future, we may make past versions visible, too.
+
+Finally, go to the "Admin" tab, make sure you're in the "Settings" section, and
+change the "Default branch" to the new ``vX.Y.Z``. (Note that this is different
+from the "Default version" setting further down the page, which should be ``latest``.)
 
 Troubleshooting: webhooks
 -------------------------

stips-2.3.1/docs/requirements.txt

@@ -0,0 +1,8 @@
+stsci_rtd_theme
+numpy >= 1.13
+matplotlib
+Cython
+astropy
+sphinx-astropy
+sphinx_issues
+poppy >= 1.0.3