diff --git a/doc/_static/fba_plot.inc b/doc/_static/fba_plot.inc new file mode 100644 index 00000000..5028409d --- /dev/null +++ b/doc/_static/fba_plot.inc @@ -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. diff --git a/doc/_static/fba_plot_results.inc b/doc/_static/fba_plot_results.inc deleted file mode 100644 index e75476d9..00000000 --- a/doc/_static/fba_plot_results.inc +++ /dev/null @@ -1,41 +0,0 @@ -.. code-block:: console - - usage: fba_plot_results [-h] --dir DIR [--prefix PREFIX] [--split] [--out OUT] - [--out_prefix OUT_PREFIX] [--out_split] - [--petals PETALS] [--real_shapes] - [--footprint FOOTPRINT] [--tiles TILES] - [--positioners POSITIONERS] [--status STATUS] - [--rundate RUNDATE] - - optional arguments: - -h, --help show this help message and exit - --dir DIR Directory containing fiberassign results. - --prefix PREFIX Prefix of each file (before the .fits). - --split Results are in tile prefix directories. - --out OUT Output directory for plots. Default is the directory - containing the fiberassign output. - --out_prefix OUT_PREFIX - Prefix of each output file. - --out_split Split output into tile prefix directories. - --petals PETALS Comma-separated list of petals to plot (default is all - petals) - --real_shapes Plot the actual positioner shapes. This looks better - but takes much longer and makes bigger files. - Recommended only for plotting limited tiles / petals. - --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. - --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-DD or - YYYY-MM-DDTHH:mm:ss in UTC time. diff --git a/doc/_static/fba_run.inc b/doc/_static/fba_run.inc index ba49159a..a7a85b4e 100644 --- a/doc/_static/fba_run.inc +++ b/doc/_static/fba_run.inc @@ -1,51 +1,63 @@ .. 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.fits). --split Split output into tile prefix directories. @@ -53,17 +65,45 @@ 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) + diff --git a/doc/index.rst b/doc/index.rst index d76829f4..36bb224d 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -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 diff --git a/doc/script_fba_plot.rst b/doc/script_fba_plot.rst new file mode 100644 index 00000000..ecc73d3d --- /dev/null +++ b/doc/script_fba_plot.rst @@ -0,0 +1,6 @@ +.. _script_fba_plot: + +fba_plot +~~~~~~~~~~~~~~~~~~~ + + .. literalinclude:: ../bin/fba_plot diff --git a/doc/script_fba_plot_results.rst b/doc/script_fba_plot_results.rst deleted file mode 100644 index 09d655a1..00000000 --- a/doc/script_fba_plot_results.rst +++ /dev/null @@ -1,9 +0,0 @@ -.. _script_fba_plot_results: - -fba_plot_results -~~~~~~~~~~~~~~~~~~~ - -This file stub was meant to ``literalinclude`` ``../bin/fba_plot_results``, -which no longer exists. Find out what is supposed to go here instead. - -.. .. literalinclude:: ../bin/fba_plot_results diff --git a/doc/usage.rst b/doc/usage.rst index c3116441..a9f20d12 100644 --- a/doc/usage.rst +++ b/doc/usage.rst @@ -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 diff --git a/py/fiberassign/scripts/assign.py b/py/fiberassign/scripts/assign.py index 0c3982d9..48c8c39c 100644 --- a/py/fiberassign/scripts/assign.py +++ b/py/fiberassign/scripts/assign.py @@ -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