Skip to content

[WIP] Update documentation to reflect API changes #489

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
dylanagreen wants to merge 3 commits into
base: main
Choose a base branch
from
Draft

[WIP] Update documentation to reflect API changes #489

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
92dea40
Update name of fba_plot script in docs.
Sep 8, 2025
9201b09
Update documentation of fba_run to match script.
Sep 8, 2025
d918f63
Update documentation of fba_plot in usage.
Sep 8, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 17 additions & 0 deletions doc/_static/fba_plot.inc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
.. code-block:: console

usage: fba_plot [-h] [--out_dir OUT_DIR] [--petals PETALS] [--simple]
[--serial] files [files ...]

positional arguments:
files

options:
-h, --help show this help message and exit
--out_dir OUT_DIR Output directory for all plots.
--petals PETALS Comma-separated list of petals to plot (default is all
petals)
--simple Plot simple lines for the positioner arms and no
exclusion zones. This is less informative, but faster.
--serial Disable the use of multiprocessing. Needed by some
unit tests to avoid issues with matplotlib.
41 changes: 0 additions & 41 deletions doc/_static/fba_plot_results.inc
View file
Open in desktop

This file was deleted.

118 changes: 79 additions & 39 deletions doc/_static/fba_run.inc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,69 +1,109 @@
.. code-block:: console

usage: fba_run [-h] --targets TARGETS [TARGETS ...] [--gfafile GFAFILE]
[--footprint FOOTPRINT] [--tiles TILES]
[--positioners POSITIONERS] [--status STATUS]
[--rundate RUNDATE] [--dir DIR] [--prefix PREFIX] [--split]
usage: fba_run [-h] --targets TARGETS [TARGETS ...] [--sky SKY [SKY ...]]
[--gfafile GFAFILE] [--footprint FOOTPRINT] [--tiles TILES]
[--rundate RUNDATE] [--obsdate OBSDATE] [--ha HA]
[--fieldrot FIELDROT] [--fieldrot_corr FIELDROT_CORR]
[--dir DIR] [--prefix PREFIX] [--split]
[--standards_per_petal STANDARDS_PER_PETAL]
[--sky_per_petal SKY_PER_PETAL] [--write_all_targets]
[--overwrite] [--sciencemask SCIENCEMASK] [--stdmask STDMASK]
[--sky_per_petal SKY_PER_PETAL]
[--sky_per_slitblock SKY_PER_SLITBLOCK]
[--margin-pos MARGIN_POS] [--margin-petal MARGIN_PETAL]
[--margin-gfa MARGIN_GFA] [--write_all_targets] [--overwrite]
[--mask_column MASK_COLUMN] [--sciencemask SCIENCEMASK]
[--stdmask STDMASK] [--gaia_stdmask GAIA_STDMASK]
[--skymask SKYMASK] [--safemask SAFEMASK]
[--excludemask EXCLUDEMASK]
[--excludemask EXCLUDEMASK] [--by_tile] [--no_redistribute]
[--no_zero_obsremain] [--lookup_sky_source {ls,gaia}]
[--fafns_for_stucksky FAFNS_FOR_STUCKSKY]
[--fba_use_fabs FBA_USE_FABS]

optional arguments:
options:
-h, --help show this help message and exit
--targets TARGETS [TARGETS ...]
Input file with targets of any type. This argument can
be specified multiple times (for example if standards
/ skies / science targets are in different files). By
default, the DESI_TARGET column and bitfield values
defined in desitarget are used to determine the type
of each target. Each filename may be optionally
followed by comma separated values that will be passed
to the arguments of the load_target_file() function.
See docs for details.
Input file with targets of any type. This argument
can be specified multiple times (for example if
standards / skies / science targets are in different
files). By default, the '--mask_column' (default
DESI_TARGET) column and bitfield values defined in
desitarget are used to determine the type of each
target. Each filename may be optionally followed by
comma and then one of the strings 'science',
'standard', 'sky' or 'safe' to force all targets in
that file to be treated as a fixed target type.
--sky SKY [SKY ...] Input file with sky or 'bad sky' targets. This option
exists in order to treat main-survey sky target files
as valid for other survey types. If you are running a
main survey assignment, you can just pass the sky file
to the --targets list.

exists in order to treat main-survey sky target files
as valid for other survey types. If you are running
a main survey assignment, you can just pass the sky
file to the --targets list.
--gfafile GFAFILE Optional GFA targets FITS file
--footprint FOOTPRINT
Optional FITS file defining the footprint. If not
specified, the default footprint from desimodel is
used.
--tiles TILES Optional text file containing a subset of the tile IDs
to use in the footprint, one ID per line. Default uses
all tiles in the footprint.
--positioners POSITIONERS
Optional FITS file describing the fiber positioner
locations. Default uses the file from desimodel.
--status STATUS Optional fiber status file in astropy ECSV format.
Default treats all fibers as good.
to use in the footprint, one ID per line.
Default uses all tiles in the footprint.
--rundate RUNDATE Optional date to simulate for this run of fiber
assignment, used with the fiber status file to
determine which fibers currently have problems.
Default uses the current date. Format is YYYY-MM-
DDTHH:mm:ss in UTC time.
assignment, used to load the correct focalplane
properties and state from desimodel. Default uses the
current date. Format is YYYY-MM-DDTHH:mm:ss+-zz:zz.
--obsdate OBSDATE Plan field rotations for this date (YEARMMDD, or
ISO 8601 YEAR-MM-DD with or without time);
default=2022-07-01 or rundate+1yr, according to rundate
--ha HA Design for the given Hour Angle in degrees.
--fieldrot FIELDROT Override obsdate and use this field rotation for
all tiles (degrees counter clockwise in CS5)
--fieldrot_corr FIELDROT_CORR
apply correction to computed fieldrot (default:
False if args.fieldrot is provided or if
args.rundate<rundate_cutoff, True else)
--dir DIR Output directory.
--prefix PREFIX Prefix of each file (before the <tile>.fits).
--split Split output into tile prefix directories.
--standards_per_petal STANDARDS_PER_PETAL
Required number of standards per petal
--sky_per_petal SKY_PER_PETAL
Required number of sky targets per petal
--sky_per_slitblock SKY_PER_SLITBLOCK
Required number of sky targets per fiber slitblock
--margin-pos MARGIN_POS, --margin_pos MARGIN_POS
Add margin (in mm) around positioner keep-out polygons
--margin-petal MARGIN_PETAL, --margin_petal MARGIN_PETAL
Add margin (in mm) around petal-boundary keep-out polygons
--margin-gfa MARGIN_GFA, --margin_gfa MARGIN_GFA
Add margin (in mm) around GFA keep-out polygons
--write_all_targets When writing target properties, write data for all
available targets, not just those which are assigned.
This is convenient, but increases the write time and
the file size.
This is convenient, but increases the write time
and the file size.
--overwrite Overwrite any pre-existing output files
--mask_column MASK_COLUMN
FITS column to use for applying target masks
--sciencemask SCIENCEMASK
Default DESI_TARGET mask to use for science targets
--stdmask STDMASK Default DESI_TARGET mask to use for stdstar targets
--gaia_stdmask GAIA_STDMASK
Default MWS_TARGET mask to use for Gaia stdstar targets
(for BACKUP program)
--skymask SKYMASK Default DESI_TARGET mask to use for sky targets
--safemask SAFEMASK Default DESI_TARGET mask to use for safe backup
targets
--safemask SAFEMASK Default DESI_TARGET mask to use for safe backup targets
--excludemask EXCLUDEMASK
Default DESI_TARGET mask to exclude from any
assignments
Default DESI_TARGET mask to exclude from any assignments
--by_tile Do assignment one tile at a time. This disables
redistribution.
--no_redistribute Disable redistribution of science targets.
--no_zero_obsremain Disable oversubscription of science targets with
leftover fibers.
--lookup_sky_source {ls,gaia}
Source for the look-up table for sky positions for
stuck fibers: 'ls': uses $SKYBRICKS_DIR;
'gaia': uses $SKYHEALPIXS_DIR (default=ls)
--fafns_for_stucksky FAFNS_FOR_STUCKSKY
csv list of fiberassign-TILEID.fits.gz files;
if set, fiberassign will use this fiberassign file
to know which stuck fibers are usable for sky
--fba_use_fabs FBA_USE_FABS
value to determine the cpp behavior,
see PR470 (default: based on the rundate)

2 changes: 1 addition & 1 deletion doc/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ Welcome to fiberassign's documentation!
changes.rst
script_fba_merge_results.rst
script_fba_plot_qa.rst
script_fba_plot_results.rst
script_fba_plot.rst
script_fba_run_qa.rst
script_fba_run.rst

Expand Down
6 changes: 6 additions & 0 deletions doc/script_fba_plot.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
.. _script_fba_plot:

fba_plot
~~~~~~~~~~~~~~~~~~~

.. literalinclude:: ../bin/fba_plot
9 changes: 0 additions & 9 deletions doc/script_fba_plot_results.rst
View file
Open in desktop

This file was deleted.

22 changes: 9 additions & 13 deletions doc/usage.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -56,23 +56,19 @@ JSON file (by default named "qa.json" in the output directory):
It is also frequently useful to plot the results of the assignment. There are
many customized plotting options possible using the low-level tools, but there
is also a command-line script to create a PDF format plot of each tile. By
default, this script plots all petals of all tiles using a "simple"
representation of each positioner (two lines). Running
:ref:`script_fba_plot_results` in this way will require several minutes per
default, this script plots all petals of all tiles in a fiber assignment run
using a detailed representation of each positioner. Running
:ref:`script_fba_plot` in this way will require several minutes per
tile, but multiple processes will be used to plot tiles in parallel:

.. include:: _static/fba_plot_results.inc
.. include:: _static/fba_plot.inc

**EXAMPLE:** In our example, let's plot only one tile and use options to plot
the full positioner geometry. Notice how we made a text file with just one
tile ID to use::
**EXAMPLE:** In our example, let's plot the full positioner gemoetry
for the fiber assignment we already ran::

%> cat plot_tiles.txt
11108
%> fba_plot_results \
--tiles plot_tiles.txt \
--dir out_raw \
--real_shapes
%> fba_plot \
out_raw/fba-11108.fits \
--out_dir out_raw

.. image:: _static/plot_assign.png

Expand Down
2 changes: 1 addition & 1 deletion py/fiberassign/scripts/assign.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -113,7 +113,7 @@ def parse_assign(optlist=None):
default=None,
help="apply correction to computed fieldrot "
"(default: False if args.fieldrot is provided or "
"if args.rundate<rundate_cutoff, True else")
"if args.rundate<rundate_cutoff, True else)")

parser.add_argument("--dir", type=str, required=False, default=None,
help="Output directory.")
Expand Down