### Install fiberassign with setup.py

Source: https://fiberassign.readthedocs.io/en/latest/_sources/install.rst.txt

Installation instructions for fiberassign: clean and install into current environment, or use a custom prefix, or build extensions in place. If something goes wrong, remove the installed directory and start over.

```bash
%> python setup.py clean
%> python setup.py install
```

```bash
%> python setup.py clean
%> python setup.py install --prefix <somewhere>
```

```bash
%> python setup.py clean; python setup.py build_ext --inplace
```

```bash
%> rm -rf ${HOME}/software/desi
```

--------------------------------

### Install fiberassign to custom prefix with setup.py

Source: https://fiberassign.readthedocs.io/en/latest/install.html

Install fiberassign to a custom location. After installation, update PATH and PYTHONPATH to use this copy.

```shell
%> python setup.py clean
%> python setup.py install --prefix <somewhere>

```

--------------------------------

### Install fiberassign from local checkout with setup.py

Source: https://fiberassign.readthedocs.io/en/latest/install.html

Install fiberassign from a local git checkout into the active conda/virtualenv environment.

```shell
%> python setup.py clean
%> python setup.py install

```

--------------------------------

### fiberassign.utils.Timer.start()

Source: https://fiberassign.readthedocs.io/en/latest/genindex.html

Starts a timer.

```APIDOC
## Timer.start()

### Description
Starts a timer.

### Method
start()

### Parameters
None

### Returns
None
```

--------------------------------

### Install fiberassign for user via pip from GitHub

Source: https://fiberassign.readthedocs.io/en/latest/_sources/install.rst.txt

Install fiberassign directly from GitHub for users not planning to modify the code. Requires the DESI packages desiutil, desimodel, and desitarget to be installed beforehand.

```bash
> pip install git+https://github.com/desihub/fiberassign.git@master#egg=fiberassign
```

--------------------------------

### Install fiberassign via pip from GitHub

Source: https://fiberassign.readthedocs.io/en/latest/install.html

Install the latest fiberassign from GitHub into the current conda/virtualenv environment.

```shell
%> pip install git+https://github.com/desihub/fiberassign.git@master#egg=fiberassign

```

--------------------------------

### fiberassign.utils.GlobalTimers.start()

Source: https://fiberassign.readthedocs.io/en/latest/genindex.html

Starts a global timer.

```APIDOC
## GlobalTimers.start()

### Description
Starts a global timer.

### Method
start()

### Parameters
None

### Returns
None
```

--------------------------------

### Install DESI packages for Developer via setup.py

Source: https://fiberassign.readthedocs.io/en/latest/_sources/install.rst.txt

For developers with existing git checkouts of desiutil, desimodel, desitarget, update checkouts and install each package into the conda env or virtualenv. Ensure DESIMODEL environment variable points to the desimodel data.

```bash
> python setup.py clean
> python setup.py install
```

--------------------------------

### Install DESI packages with pip from GitHub

Source: https://fiberassign.readthedocs.io/en/latest/install.html

Install desiutil, desimodel, and desitarget directly from GitHub using pip. This is for users who do not need a persistent git checkout of the code.

```shell
%> pip install git+https://github.com/desihub/desiutil.git@master#egg=desiutil
%> pip install git+https://github.com/desihub/desimodel.git@master#egg=desimodel
%> pip install git+https://github.com/desihub/desitarget.git@master#egg=desitarget

```

--------------------------------

### Data directory for large DR7 example

Source: https://fiberassign.readthedocs.io/en/latest/_sources/examples.rst.txt

Path to the large DR7 data files used in the example.

```text
/project/projectdirs/desi/target/fiberassign/dr7.1/0.10.3-dark
```

--------------------------------

### Install DESI packages for DESI User via pip and svn

Source: https://fiberassign.readthedocs.io/en/latest/_sources/install.rst.txt

Install the required DESI packages (desiutil, desimodel, desitarget) directly from GitHub for the 'DESI User' scenario. Also install the desimodel data by exporting DESIMODEL and using svn export. Ensure $DESIMODEL is set before running fiberassign.

```bash
> pip install git+https://github.com/desihub/desiutil.git@master#egg=desiutil
> pip install git+https://github.com/desihub/desimodel.git@master#egg=desimodel
> pip install git+https://github.com/desihub/desitarget.git@master#egg=desitarget
```

```bash
> export DESIMODEL=${HOME}/software/desi
> svn export https://desi.lbl.gov/svn/code/desimodel/trunk/data \
 ${DESIMODEL}/data
```

--------------------------------

### Set up DESI Python stack with virtualenv and pip

Source: https://fiberassign.readthedocs.io/en/latest/_sources/install.rst.txt

Create and activate a Python3 virtualenv for DESI, then install numpy, scipy, astropy, matplotlib, and the fitsio package. Use this if you prefer virtualenv and pip over Anaconda.

```bash
> virtualenv -p python3 ${HOME}/software/desi
> source ${HOME}/software/desi/bin/activate
```

```bash
> pip install numpy scipy astropy matplotlib
> pip install --no-binary :all: fitsio
```

--------------------------------

### Set environment variables for large example

Source: https://fiberassign.readthedocs.io/en/latest/_sources/examples.rst.txt

Set up environment variables for the large run.
OMP_NUM_THREADS is set to 32, DESI_LOGLEVEL to DEBUG,
and targetdir points to the data directory.

```bash
%> export OMP_NUM_THREADS=32
%> export DESI_LOGLEVEL=DEBUG
%> export \
   targetdir=/project/projectdirs/desi/target/fiberassign/dr7.1/0.10.3-dark
```

--------------------------------

### Merge results with fba_merge_results

Source: https://fiberassign.readthedocs.io/en/latest/_sources/usage.rst.txt

Post-processes the raw output from fba_run to include additional information from the original target catalog. Continues the minimal example, using the same target files and raw output directory, and writes merged results to out_merged.

```console
%> fba_merge_results \
       --targets mtl.fits standards.fits sky.fits other_targets.fits \
       --dir out_raw \
       --out out_merged
```

--------------------------------

### Run fiber assignment with fba_run

Source: https://fiberassign.readthedocs.io/en/latest/_sources/examples.rst.txt

Run fiber assignment with fba_run on the large DR7 examples.
Uses about half the RAM on a Cori haswell node and takes about one hour
(half of that is writing output files).

```bash
%> time fba_run \
--footprint ${targetdir}/input_tiles.fits \
--targets ${targetdir}/mtl_large.fits \
${targetdir}/std_large.fits \
${targetdir}/sky_large.fits \
--dir out_dr7.1_dark | tee log_dr7.1_dark
```

--------------------------------

### Remove local DESI installation to restart

Source: https://fiberassign.readthedocs.io/en/latest/install.html

Remove the local DESI software directory to start over after a failed or corrupted installation.

```shell
%> rm -rf ${HOME}/software/desi

```

--------------------------------

### fiberassign --help command line options

Source: https://fiberassign.readthedocs.io/en/latest/usage.html

Running `fiberassign --help` prints the full set of command line options for the legacy compatibility wrapper. The output lists required arguments (--mtl, --sky, --stdstar, --fibstatusfile) and optional arguments such as --footprint, --positioners, --surveytiles, --telra, --teldec, --tileid, --tileobsconditions, --outdir, --starmask, --rundate, --gfafile, --nstarpetal, --nskypetal, and --nocleanup.

```text
usage: fiberassign [-h] --mtl MTL --sky SKY --stdstar STDSTAR
                 --fibstatusfile FIBSTATUSFILE
                 [--footprint FOOTPRINT]
                 [--positioners POSITIONERS] [--surveytiles SURVEYTILES]
                 [--telra TELRA] [--teldec TELDEC] [--tileid TILEID]
                 [--tileobsconditions TILEOBSCONDITIONS] [--outdir OUTDIR]
                 [--starmask STARMASK] [--rundate RUNDATE]
                 [--gfafile GFAFILE] [--nstarpetal NSTARPETAL]
                 [--nskypetal NSKYPETAL] [--nocleanup]

optional arguments:
-h, --help            show this help message and exit
--mtl MTL             input targets (FITS file)
--sky SKY             input sky positions (FITS file)
--stdstar STDSTAR     input std stars (FITS file)
--fibstatusfile FIBSTATUSFILE
                      list of positioners and its status (ECSV file)
--footprint FOOTPRINT
                      input footprint (FITS file)
--positioners POSITIONERS
                      input positioners (FITS file)
--surveytiles SURVEYTILES
                      input survey tiles (FITS file)
--telra TELRA         telescope pointing RA (degrees)
--teldec TELDEC       telescope pointing DEC (degrees)
--tileid TILEID       tile ID to assign
--tileobsconditions TILEOBSCONDITIONS
                      observing conditions for this tile
--outdir OUTDIR       output directory for all products
--starmask STARMASK   input mask for standard stars (FITS file)
--rundate RUNDATE    date of the run (YYYY-MM-DD)
--gfafile GFAFILE     input guide/focus/alignment targets (FITS file)
--nstarpetal NSTARPETAL
                      number of petals to use for standard stars
--nskypetal NSKYPETAL number of petals to use for sky fibers
--nocleanup           do```json
{
  
```

--------------------------------

### run_assign_init(): Load hardware and tiles

Source: https://fiberassign.readthedocs.io/en/latest/_modules/fiberassign/scripts/assign.html

Loads hardware properties and tile data, optionally selecting tiles from a file by parsing the first column as integers.

```python
    # Read hardware properties
    hw = load_hardware(rundate=args.rundate, add_margins=args.margins)

    # Read tiles we are using
    tileselect = None
    if args.tiles is not None:
        tileselect = list()
        with open(args.tiles, "r") as f:
            for line in f:
                # Try to convert the first column to an integer.
                try:
                    tileselect.append(int(line.split()[0]))
                except ValueError:
                    pass
    tiles = load_tiles(tiles_file=args.footprint, select=tileselect,
        obstime=args.obsdate, obstheta=args.fieldrot, obsha=args.ha,
        obsthetacorr=args.fieldrot_corr)
```

--------------------------------

### Extract DTVER from FAARGS header and generate main tiles table

Source: https://fiberassign.readthedocs.io/en/latest/_modules/fiberassign/utils.html

These code blocks appear in the documentation as part of the source code for the `fiberassign.utils` module. The first block is the implementation of a function that retrieves the `--dtver` value from the FAARGS header of a fiberassign file, with a fallback to '-'. The second block is an example of how to generate the table stored in `data/tiles-main-dtver-1.0.0.ecsv`, using multiprocessing to get DTVER values for a list of tile IDs.

```python
    # AR default svn folder
    if svndir is None:
        svndir = os.path.join(os.getenv("DESI_TARGET"), "fiberassign", "tiles", "trunk")

    tileidpad = "{:06d}".format(tileid)
    fn = os.path.join(svndir, tileidpad[:3], "fiberassign-{}.fits.gz".format(tileidpad))
    if os.path.isfile(fn):
        faargs = fitsio.read_header(fn, 0)["FAARGS"].split()
        return [faargs[i+1] for i in range(len(faargs)-1) if faargs[i] == "--dtver"][0]
    else:
        return "-"
```

```python
        d = Table.read("/global/cfs/cdirs/desi/survey/ops/surveyops/trunk/ops/tiles-main.ecsv")
        pool = multiprocessing.Pool(processes=256)
        with pool:
            dtvers = np.array(pool.map(get_main_dtver, d["TILEID"]))
        sel = dtvers == "1.0.0"
        d = d[sel]["TILEID", "PASS", "RA", "DEC", "PROGRAM", "IN_DESI", "EBV_MED"]
        d.write("tiles-main-dtver-1.0.0.ecsv")
```

--------------------------------

### run_qa(args)

Source: https://fiberassign.readthedocs.io/en/latest/_modules/fiberassign/scripts/qa.html

Runs QA using previously parsed options. Loads hardware and tiles, then executes the QA process.

```APIDOC
## run_qa(args)

### Description
Runs QA using the parsed arguments. Loads hardware and tiles, then calls qa_tiles to perform the QA.

### Method
Function

### Signature
run_qa(args)

### Parameters
- **args** (namespace) - The parsed arguments from parse_qa.

### Returns
- None

### Example
```
from fiberassign.scripts.qa import parse_qa, run_qa
args = parse_qa()
run_qa(args)
```
```

--------------------------------

### Set up environment variables for fiberassign reference run

Source: https://fiberassign.readthedocs.io/en/latest/_sources/examples.rst.txt

Set up environment variables needed for the fiberassign reference run on cori.nersc.gov. This includes setting the number of OpenMP threads, the DESI log level, and the target directory path.

```bash
export OMP_NUM_THREADS=32
export DESI_LOGLEVEL=DEBUG
export \
   targetdir=/project/projectdirs/desi/datachallenge/reference_runs/19.10/targets
```

--------------------------------

### Run the Small Reference Run Workflow

Source: https://fiberassign.readthedocs.io/en/latest/examples.html

Set up an interactive compute node, exports required environment variables and paths, then runs fiberassign's fba_run, fba_plot_results, and fba_merge_results commands in sequence to produce a small reference run.

```bash
%> salloc -N 1 -C haswell -A desi --qos=interactive -t 04:00:0
```

```bash
%> export OMP_NUM_THREADS=32
%> export DESI_LOGLEVEL=DEBUG
%> export \
   targetdir=/project/projectdirs/desi/datachallenge/reference_runs/19.10/targets
```

```bash
%> time fba_run \
    --targets ${targetdir}/mtl-dark.fits \
    ${targetdir}/sky.fits \
    --dir out_ref_19.10 | tee log_ref_19.10
```

```bash
%> time fba_plot_results --dir out_ref_19.10
```

```bash
%> time fba_merge_results \
--targets ${targetdir}/mtl-dark.fits \
${targetdir}/sky.fits --dir out_ref_19.10
```

--------------------------------

### fiberassign.hardware.load_hardware()

Source: https://fiberassign.readthedocs.io/en/latest/genindex.html

Loads the hardware configuration from a file or default settings.

```APIDOC
## Function: load_hardware()

### Description
Loads the hardware configuration for the FiberAssign system.

### Module
fiberassign.hardware
```

--------------------------------

### Install DESI Python dependencies with pip

Source: https://fiberassign.readthedocs.io/en/latest/install.html

Installs the required Python dependencies (numpy, scipy, astropy, matplotlib) and fitsio using pip inside the virtualenv created earlier.

```bash
%> pip install numpy scipy astropy matplotlib
%> pip install --no-binary :all: fitsio

```

--------------------------------

### run_assign_init(): Load target and sky files

Source: https://fiberassign.readthedocs.io/en/latest/_modules/fiberassign/scripts/assign.html

Loads target files from args.targets, optionally forcing the target type (e.g., comma-separated type), then loads sky target files forcing them to the survey type of the previously loaded targets.

```python
    # Append each input target file.  These target files must all be of the
    # same survey type, and will set the Targets object to be of that survey.

    for tgarg in args.targets:
        tgprops = tgarg.split(",")
        tgfile = tgprops[0]
        typeforce = None
        if len(tgprops) > 1:
            # we are forcing the target type for this file
            typeforce = str_to_target_type(tgprops[1])
        load_target_file(tgs, tagalong, tgfile, typeforce=typeforce,
                         typecol=args.mask_column,
                         sciencemask=args.sciencemask,
                         stdmask=args.stdmask,
                         skymask=args.skymask,
                         safemask=args.safemask,
                         excludemask=args.excludemask,
                         gaia_stdmask=args.gaia_stdmask,
                         rundate=args.rundate)
    # Now load the sky target files.  These are main-survey files that we will
    # force to be treated as the survey type of the other target files.
    survey = tgs.survey()
    for tgarg in args.sky:
        load_target_file(tgs, tagalong, tgarg, survey=survey, typeforce=typeforce,
                         typecol=args.mask_column,
                         sciencemask=args.sciencemask,
                         stdmask=args.stdmask,
                         skymask=args.skymask,
                         safemask=args.safemask,
                         excludemask=args.excludemask,
                         gaia_stdmask=args.gaia_stdmask)
```

--------------------------------

### run_assign_init(): Set FIBERASSIGN_USE_FABS from args

Source: https://fiberassign.readthedocs.io/en/latest/_modules/fiberassign/scripts/assign.html

Sets the FIBERASSIGN_USE_FABS environment variable from args.fba_use_fabs, logging a warning if it overwrites an existing value, and logs the variable usage.

```python
    # AR fba_use_fabs
    if args.fba_use_fabs is not None:
        if os.getenv("FIBERASSIGN_USE_FABS") is not None:
            if os.getenv("FIBERASSIGN_USE_FABS") != str(args.fba_use_fabs):
                msg = "already defined environment variable FIBERASSIGN_USE_FABS={} will be overwritten by args.fba_use_fabs={}".format(
                    os.getenv("FIBERASSIGN_USE_FABS"),
                    args.fba_use_fabs
                )
                log.warning(msg)
        os.environ["FIBERASSIGN_USE_FABS"] = str(args.fba_use_fabs)

    for env_var in ["FIBERASSIGN_USE_FABS"]:
        log.info("run_assign_init(): use {}={}".format(env_var, os.getenv(env_var)))
```

--------------------------------

### Install desimodel data with svn export

Source: https://fiberassign.readthedocs.io/en/latest/install.html

Sets the DESIMODEL environment variable to ${HOME}/software/desi and exports the desimodel data directory from the DESI SVN repository into that location. Required after installing the desimodel package so the data files are available.

```shell
%> export DESIMODEL=${HOME}/software/desi
%> svn export https://desi.lbl.gov/svn/code/desimodel/trunk/data \
 ${DESIMODEL}/data

```

--------------------------------

### fiberassign CLI help and minimal invocation

Source: https://fiberassign.readthedocs.io/en/latest/_sources/usage.rst.txt

The first block is the output of the fiberassign script when invoked with --help, listing all command-line options and their defaults. The second block is a minimal invocation that requires only the four essential files: mtl.fits, std.fits, sky.fits, and fiberstatus.ecsv, with an output directory. The script maintains backward compatibility with previous fiberassign versions by translating old options into the newer scripts' arguments.

```text
usage: fiberassign [-h] --mtl MTL --sky SKY --stdstar STDSTAR
                   --fibstatusfile FIBSTATUSFILE
                   [--footprint FOOTPRINT]
                   [--positioners POSITIONERS] [--surveytiles SURVEYTILES]
                   [--telra TELRA] [--teldec TELDEC] [--tileid TILEID]
                   [--tileobsconditions TILEOBSCONDITIONS] [--outdir OUTDIR]
                   [--starmask STARMASK] [--rundate RUNDATE]
                   [--gfafile GFAFILE] [--nstarpetal NSTARPETAL]
                   [--nskypetal NSKYPETAL] [--nocleanup]

optional arguments:
  -h, --help            show this help message and exit
  --mtl MTL             input targets (FITS file)
  --sky SKY             input sky positions (FITS file)
  --stdstar STDSTAR     input std stars (FITS file)
  --fibstatusfile FIBSTATUSFILE
                        list of positioners and its status (ECSV file)
  --footprint FOOTPRINT
                        list of tiles defining the footprint (FITS file)
  --positioners POSITIONERS
                        list of positioners on the focal plane (FITS file)
  --surveytiles SURVEYTILES
                        set of tiles to run fiberassign on (text file)
  --telra TELRA         Right Ascension of arbitrary pointing - overrides
                        --surveytiles
  --teldec TELDEC       Declination of arbitrary pointing - overrides
                        --surveytiles
  --tileid TILEID       Integer ID of arbitrary pointing - overrides
                        --surveytiles
  --tileobsconditions TILEOBSCONDITIONS
                        Mask describing observing program (DARK:1, GRAY:2,
                        BRIGHT:4) - overrides --surveytiles
  --outdir OUTDIR       output directory (default = ./)
  --starmask STARMASK   integer mask defining standard stars
  --rundate RUNDATE     run date [YYYY-MM-DD]
  --gfafile GFAFILE     GFA file (FITS tile)
  --nstarpetal NSTARPETAL
                        number of standard stars per petal (default=10)
  --nskypetal NSKYPETAL
                        number of sky fibers per petal (default=40)
  --nocleanup

```

```text
fiberassign  --mtl mtl.fits --stdstar std.fits --sky sky.fits
  --fibstatusfile fiberstatus.ecsv --outdir $SCRATCH/temp/
```

--------------------------------

### Create conda environment for DESI Python stack

Source: https://fiberassign.readthedocs.io/en/latest/_sources/install.rst.txt

Create and activate a new conda environment under ${HOME}/software/desi)Skip this if you already have a Python stack for DESI. Requires Anaconda installed. Installs numpy, scipy, astropy, matplotlib, and the fitsio package using pip with no binary packages.

```bash
> conda create --copy -m -p ${HOME}/software/desi
> conda activate ~/software/desi
> conda install numpy scipy astropy matplotlib
> pip install --no-binary :all: fitsio
```

--------------------------------

### Get Git version

Source: https://fiberassign.readthedocs.io/en/latest/_modules/fiberassign/utils.html

Returns the git describe output for the current repository, or 'unknown' if not a git repository.

```python
def get_fa_gitversion():
    """
    Returns `git describe --tags --dirty --always`, or "unknown" if not a git repo

    Notes:
        Copied (and slightly edited) from desitarget.io.gitversion()
    """
    #
    origdir = os.getcwd()
    os.chdir(os.path.dirname(__file__))
    try:
        p = subprocess.Popen(["git", "describe", "--tags", "--dirty", "--always"], stdout=subprocess.PIPE, stderr=subprocess.STDOUT)
    except EnvironmentError:
        return "unknown"
    #
    os.chdir(origdir)
    out = p.communicate()[0]
    if p.returncode == 0:
        # - avoid py3 bytes and py3 unicode; get native str in both cases
        return str(out.rstrip().decode("ascii"))
    else:
        return "unknown"
```

--------------------------------

### fiberassign.hardware.load_hardware

Source: https://fiberassign.readthedocs.io/en/latest/reference.html

Function to create a Hardware instance representing telescope properties.

```APIDOC
## fiberassign.hardware.load_hardware

### Description
Create a hardware class representing properties of the telescope.

### Method
Function call

### Endpoint
fiberassign.hardware.load_hardware(focalplane=None, rundate=None, add_margins={}, get_time_range=False)

### Parameters
- **focalplane** (tuple) - Optional - Override the focalplane model. If not None, this should be a tuple of the same data types returned by desimodel.io.load_focalplane().
- **rundate** (str) - Optional - ISO 8601 format time stamp as a string in the format YYYY-MM-DDTHH:MM:SS+-zz:zz. If None, uses current time.
- **add_margins** (dict) - Optional - Additional margins to add around positioners, GFAs, and petals. Dict with keys "pos", "gfa", "petal" and values of millimeters.
- **get_time_range** (bool) - Optional - If True, return (hw, time_lo, time_hi), where time_lo and time_hi are datetime objects corresponding to the first and last dates when the hardware was in this state.

### Returns
- If get_time_range is True: (hardware, time_lo, time_hi)
- Else: hardware (Hardware object)

### Return Type
- Hardware (if get_time_range is False)
- tuple (if get_time_range is True)
```

--------------------------------

### Get SVN revisions and dates

Source: https://fiberassign.readthedocs.io/en/latest/_modules/fiberassign/utils.html

Queries SVN logs for a list of subfolders to return revision numbers and dates.

```python
def get_revs_dates(svndir, subdirs):
    """
    Returns the list of svn revisions (and dates) for a list of subfolders.

    Args:
        svndir: full path to a svn checkout (e.g. "$DESI_TARGET/fiberassign/tiles/trunk") (str)
        subdirs: comma-separated list of subfolders in svndir (e.g. "000,001,080") (str)

    Returns:
        revs: list of revisions (np array of int)
        dates: list of the dates of the revisions (YYYY-MM-DD) (np array of str)

    Notes:
        This function queries the server ("svn log"), so do not run in parallel!
    """
    revs, dates = [], []
    for subdir in subdirs.split(","):
        start = time()
        ps = subprocess.Popen(
            ["svn", "log", os.path.join(svndir, subdir)], stdout=subprocess.PIPE
        )
        output = subprocess.check_output(
            ["grep", "^r[1-9]"],
            stdin=ps.stdout,
        )
        output = output.strip().decode()
        ps.stdout.close()
        lines = output.split("\n")
        revs += [int(line.split("|")[0][1:]) for line in lines]
        dates += [line.split("|")[2].split()[0] for line in lines]
        dt = time() - start
        log.info("subdir={}\tnrev={}\t(dt={:.1f}s)".format(subdir, len(lines), dt))
        # AR protect from overloading the server
        sleep(0.5)
    revs, ii = np.unique(revs, return_index=True)
    dates = np.array(dates)[ii]
    return revs, dates
```

--------------------------------

### Plot fiber assignment results

Source: https://fiberassign.readthedocs.io/en/latest/_sources/examples.rst.txt

Runs fba_plot_results on a date-stamped output directory to generate plots. The example uses the directory 'out_fiberassign_2018-11-24T11:09:48'.

```bash
fba_plot_results \
   --dir "out_fiberassign_2018-11-24T11:09:48"
```

--------------------------------

### Get SVN revision number

Source: https://fiberassign.readthedocs.io/en/latest/_modules/fiberassign/utils.html

Retrieves the SVN revision number for a given directory path, supporting environment variable expansion.

```python
def get_svn_version(svn_dir):
    """
    Gets the SVN revision number of an SVN folder.

    Args:
        svn_dir: SVN folder path (string)

    Returns:
        svnver: SVN revision number of svn_dir, or "unknown" if not an svn checkout

    Notes:
        `svn_dir` can contain environment variables to expand, e.g. "$DESIMODEL/data"
    """
    cmd = ["svn", "info", os.path.expandvars(svn_dir)]
    try:
        svn_ver = (
            subprocess.check_output(cmd, stderr=subprocess.DEVNULL).strip().decode()
        )
        # search for "Last Changed Rev: " line and parse out revision number.  Recent versions
        # of svn have a --show-item argument that does this in a less fragile way,
        # but the svn installed at KPNO is old and doesn't support this option.
        searchstr = 'Last Changed Rev: '
        svn_ver = [line[len(searchstr):] for line in svn_ver.split('\n')
                   if searchstr in line][0]
    except subprocess.CalledProcessError:
        svn_ver = "unknown"

    return svn_ver
```

--------------------------------

### fba_run_qa script entry point

Source: https://fiberassign.readthedocs.io/en/latest/script_fba_run_qa.html

This is the main script for fba_run_qa. It imports parse_qa and run_qa from fiberassign.scripts.qa, parses command-line arguments, and runs the QA process. The script is intended to be executed directly.

```python
#!/usr/bin/env python
"""
Create fiber assignment QA results.
"""

from fiberassign.scripts.qa import parse_qa, run_qa


def main():
    args = parse_qa()
    run_qa(args)
    return


if __name__ == "__main__":
    main()

```

--------------------------------

### fiberassign.scripts.qa.run_qa

Source: https://fiberassign.readthedocs.io/en/latest/_sources/reference.rst.txt

Run the QA.

```APIDOC
## fiberassign.scripts.qa.run_qa

### Description
Run the QA.

### Method
N/A (Python function)

### Endpoint
N/A

### Parameters
#### Input
- **args** - Required - Parsed arguments from parse_qa.

### Returns
- None

### Example
```python
from fiberassign.utils import option_list
from fiberassign.scripts.qa import (parse_qa, run_qa)
opts = {"dir": "out_raw"}
optlist = option_list(opts)
args = parse_qa(optlist)
run_qa(args)
```
```

--------------------------------

### Load plate scale in fiberassign.hardware

Source: https://fiberassign.readthedocs.io/en/latest/_modules/fiberassign/hardware.html

Loads the plate scale data used for coordinate transformations later in the setup. This simple call fetches the required plate scale table.

```python
    # Get the plate scale
    platescale = dmio.load_platescale()
```

--------------------------------

### run_assign_init(): Check for pre-existing output files

Source: https://fiberassign.readthedocs.io/en/latest/_modules/fiberassign/scripts/assign.html

Checks for pre-existing output files and exits with an error if they exist and the --overwrite flag is not set.

```python
    # Before doing significant calculations, check for pre-existing files
    if not args.overwrite:
        for tileid in tiles.id:
            outfile = result_path(tileid, dir=args.dir,
                                  prefix=args.prefix, split=args.split)
            if os.path.exists(outfile):
                outdir = os.path.split(outfile)[0]
                log.error("Output files already exist in {}".format(outdir))
                log.error("either remove them or use --overwrite")
                sys.exit(1)
```

--------------------------------

### option_list()

Source: https://fiberassign.readthedocs.io/en/latest/reference.html

Returns a list of command-line options for the fiberassign command-line interface.

```APIDOC
## option_list()

### Description
Returns a list of command-line options for the fiberassign command-line interface.

### Method
N/A (function)

### Endpoint
N/A

### Parameters
None

### Request Example
N/A

### Response
#### Success Response
- **options** (list) - List of command-line option strings.

#### Response Example
```
['--output', '--overwrite', ...]
```
```

--------------------------------

### Debug log output for tile 1149, location 6525

Source: https://fiberassign.readthedocs.io/en/latest/_sources/examples.rst.txt

Example debug log output showing available targets for tile 1149, location 6525. The eventual choice has ID 288230398385721102, but it was not the initial assignment because it didn't have the highest priority.

```text
DEBUG: targets avail:  tile 1149, location 6525 append ID 288230398385719030 (type=1), total priority 3000.42
DEBUG: targets avail:  tile 1149, location 6525 append ID 288230398385719269 (type=1), total priority 3000.37
DEBUG: targets avail:  tile 1149, location 6525 append ID 288230398385719156 (type=1), total priority 3000.29
DEBUG: targets avail:  tile 1149, location 6525 append ID 288230398385719119 (type=1), total priority 3000.12
DEBUG: targets avail:  tile 1149, location 6525 append ID 288230398385719090 (type=1), total priority 3000.02
DEBUG: targets avail:  tile 1149, location 6525 append ID 288230398385721102 (type=3), total priority 1500.58
DEBUG: targets avail:  tile 1149, location 6525 append ID 288230398385720982 (type=1), total priority 1400.95
DEBUG: targets avail:  tile 1149, location 6525 append ID 288230398385720952 (type=1), total priority 1400.32
```

--------------------------------

### load_hardware()

Source: https://fiberassign.readthedocs.io/en/latest/reference.html

Loads hardware properties from a file or default.

```APIDOC
## load_hardware()

### Description
Loads hardware properties from a file or default.

### Method
N/A (function)

### Endpoint
N/A

### Parameters
- **filename** (str) - Optional - Path to hardware file.

### Request Example
```python
hw = load_hardware('hardware.fits')
```

### Response
#### Success Response
- **Hardware** (Hardware) - Hardware object.

#### Response Example
```python
<Hardware object>
```
```

--------------------------------

### Define radec2xy signature and docstring

Source: https://fiberassign.readthedocs.io/en/latest/_modules/fiberassign/hardware.html

Defines the radec2xy function stub that projects RA/Dec to X/Y mm using the provided hardware object, with a docstring listing all parameters and the return type. The current body contains commented-out code and the start of imports from astropy.time, desimeter.fiberassign, and inspect.

```python
def radec2xy(hw, tile_ra, tile_dec, tile_obstime, tile_obstheta, tile_obsha,
             ra, dec, use_cs5, threads=0, use_hardcoded_polmis_rotmat=True):
    '''
    For the tile pointed at (tilera, tiledec), project the (ra, dec)
    value into X/Y mm.

    Args:
      hw: Hardware object
      tile_ra (float): Tile RA
      tile_dec (float): Tile Dec
      tile_obstime (string): Tile observation time, YYYY-MM-DDTHH:MM:SS / Astropy "isot" format.
      tile_obstheta (float): Tile "fieldrot" rotation angle.
      tile_obsha (float): Tile designed Hour Angle, in degrees.
      ra (numpy array): RA to project, in degrees
      dec (numpy array): Dec to project, in degrees
      use_CS5 (bool):  If True, return CS5 coordinates, else curved.
      threads=0 (int): currently unused; for backward compatibility.

    Returns:
      x, y: numpy arrays: the (X, Y) projected locations.
    '''
    #xy = hw.radec2xy_multi(
    #    tile_ra, tile_dec, tile_obstheta, ra, dec, use_cs5, threads=0
    #)
    #x = np.array([x for x,y in xy])
    #y = np.array([y for x,y in xy])
    from astropy.time import Time
    from desimeter.fiberassign import fiberassign_radec2xy_cs5, fiberassign_radec2xy_flat
    from inspect import getfullargspec
```

--------------------------------

### Define run_assign_init function with docstring

Source: https://fiberassign.readthedocs.io/en/latest/_modules/fiberassign/scripts/assign.html

Defines the run_assign_init function that initializes assignment inputs using previously parsed options `args`. When called, it returns a tuple of (Hardware, Tiles, Targets) needed for assignment; the function body is not shown in the source.

```python
def run_assign_init(args, plate_radec=True):
    """Initialize assignment inputs.

    This uses the previously parsed options to load the input files needed.

    Args:
        args (namespace): The parsed arguments.

    Returns:
        (tuple):  The (Hardware, Tiles, Targets) needed to run assignment.
    """
```

--------------------------------

### Plot QA results with fba_plot_qa

Source: https://fiberassign.readthedocs.io/en/latest/_sources/usage.rst.txt

Make a crude visualization of QA for the entire footprint from the JSON file generated by fba_run_qa. When plotting only a few tiles, the plot is less useful; you can get the numbers directly from the JSON. Use the --labels option to see tile IDs on the plot.

```console
%> fba_plot_qa --qafile "out_raw/qa.json"
```

--------------------------------

### fiberassign.hardware module source: get_default_exclusion_margins, expand_closed_curve, and get_exclusions

Source: https://fiberassign.readthedocs.io/en/latest/_modules/fiberassign/hardware.html

The complete source code for the fiberassign.hardware module, as displayed on the page. It includes imports (desimodel.io, astropy.table, numpy, scipy.interpolate), the get_default_exclusion_margins function returning the default margins in millimeters, and the expand_closed_curve function implementing the polygon expansion geometry. Also defines the global cache _cache_shape_to_excl and begins the get_exclusions function, which fetches an exclusion region from a data file. Page content is truncated at the start of get_exclusions, so only the visible portion is included.

```python
# Licensed under a 3-clause BSD style license - see LICENSE.rst
# -*- coding: utf-8 -*-
"""
fiberassign.hardware
=======================

Functions for loading information about the telescope hardware.

"""
from __future__ import absolute_import, division, print_function

from datetime import datetime, timezone

import numpy as np

from scipy.interpolate import interp1d
import astropy.table

import desimodel.io as dmio

from .utils import Logger

from ._internal import (
    Hardware,
    FIBER_STATE_OK,
    FIBER_STATE_UNASSIGNED,
    FIBER_STATE_STUCK,
    FIBER_STATE_BROKEN,
    FIBER_STATE_RESTRICT,
    Circle,
    Segments,
    Shape,
)

def get_default_exclusion_margins():
    '''
    We add an additional margin around the exclusion zones in the hardware descriptions.
    This function returns the defaults used by the fiberassign scripts.

    Returns:
    margins (dict): with keys "pos", "gfa" and "petal", to floating-point margins in millimeters.
    '''
    return dict(pos=0.05,
                petal=0.4,
                gfa=0.4)

def expand_closed_curve(xx, yy, margin):
    '''
    For the --margin-{pos,petal,gfa} options, we can add a buffer zone
    around the positioner keep-out polygons.  This function implements
    the geometry to achieve this.

    Given a RIGHT-HANDED closed polygon xx,yy and margin, returns new
    x,y coordinates expanded by a margin of `margin`.

    (By right-handed, I mean that the points are listed
    counter-clockwise, and if you walk the boundary, the inside of the
    shape is to the left; the expanded points will be to the right.)

    If the order of the polygon is reversed, the "expanded" points
    will actually be on the *inside* of the polygon.  Setting the
    margin negative counteracts this.

    Note that we strictly require a closed curve.  Collinear polygon
    segments will cause problems!

    '''
    ex, ey = [],[]

    # These are closed curves (last point = first point)
    # (this isn't strictly required by the fundamental algorithm, but is assumed
    # in the way we select previous and next points in the loop below.)
    if (xx[0] != xx[-1]) or (yy[0] != yy[-1]):
        log = Logger.get()
        log.warning('Expected exclusion polygons to be closed curves; got x, y = %s, %s' % (str(xx), str(yy)))
        return xx, yy
    assert(xx[0] == xx[-1])
    assert(yy[0] == yy[-1])

    N = len(xx)

    for j in range(N):
        # We go through the points, and for each point we consider the previous
        # and next point.  The "expanded" point will be defined according to the
        # two edges (vector) coming from the point.
        i = j - 1
        if i == -1:
            # wrap around, skipping repeated point
            i = N-2
        k = j + 1
        if k == N:
            k = 1

        x1 = xx[i]
        y1 = yy[i]
        x2 = xx[j]
        y2 = yy[j]
        x3 = xx[k]
        y3 = yy[k]

        # Vectors to and from the central point.
        vx1 = x2 - x1
        vy1 = y2 - y1
        vx2 = x3 - x2
        vy2 = y3 - y2
        # We can't handle repeated points!
        assert(not(vx2 == 0. and vy2 == 0.))

        # Get the angle between the vectors -- our expanded point is going to
        # be halfway between these two vectors.
        cross1 = vx1 * vy2 - vx2 * vy1
        vv1 = np.hypot(vx1,vy1)
        vv2 = np.hypot(vx2,vy2)
        theta = np.arcsin(np.clip(cross1 / (vv1 * vv2), -1., 1.))
        # Detect sharp (>90 degree) turns
        dot = vx1*vx2 + vy1*vy2
        # the angle of the expanded point is relative to vector 1
        a = np.arctan2(vy1, vx1)
        if dot < 0:
            # sharp turn -- the theta=arcsin aliases the angle, which is outside
            # the range of [-pi/2, +pi/2]; adjust theta to the aliased angle.
            if theta > 0:
                theta =  np.pi - theta
            else:
                theta = -np.pi - theta
        da = np.pi/2. + theta/2.
        # This places the point further from the original keeps the vectors parallel to their originals
        stretch = 1./np.cos(theta/2.)
        dx = -margin * stretch * np.cos(a + da)
        dy = -margin * stretch * np.sin(a + da)

        ex.append(x2 + dx)
        ey.append(y2 + dy)

    return ex, ey

# Global cache of exclusions.  (exclusions are geometric regions describing the keep-out
# areas around positioners, GFAs, and petal edges)
_cache_shape_to_excl = dict()

def get_exclusions(exclude, exclname, margins, local_cache=None):
    '''
    Fetches an exclusion region from a data file, applying additional margins as required.

    A "local_cache", valid for a single "exclude" file, can be passed in.

    '''
```

--------------------------------

### fba_run: Main fiber assignment entry point (Python)

Source: https://fiberassign.readthedocs.io/en/latest/script_fba_run.html

Main entry point for fiber assignment. Calls freeze_iers to freeze IERS data, then parses command-line arguments and runs either by-tile or full assignment based on the --by-tile flag.

```python
#!/usr/bin/env python
"""
Main fiber assignment entry point
"""

from desiutil.iers import freeze_iers
from fiberassign.scripts.assign import (parse_assign, run_assign_full,
                                        run_assign_bytile)


def main():

    # AR freeze_iers
    freeze_iers()

    args = parse_assign()
    if args.by_tile:
        run_assign_bytile(args)
    else:
        run_assign_full(args)
    return


if __name__ == "__main__":
    main()

```

--------------------------------

### run_assign_full(): Set FIBERASSIGN_USE_FABS from args

Source: https://fiberassign.readthedocs.io/en/latest/_modules/fiberassign/scripts/assign.html

Sets the FIBERASSIGN_USE_FABS environment variable from args.fba_use_fabs, logging a warning if it overwrites an existing value, and logs the variable usage within run_assign_full().

```python
    log = Logger.get()

    # AR fba_use_fabs
    if args.fba_use_fabs is not None:
        if os.getenv("FIBERASSIGN_USE_FABS") is not None:
            if os.getenv("FIBERASSIGN_USE_FABS") != str(args.fba_use_fabs):
                msg = "already defined environment variable FIBERASSIGN_USE_FABS={} will be overwritten by args.fba_use_fabs={}".format(
                    os.getenv("FIBERASSIGN_USE_FABS"),
                    args.fba_use_fabs
                )
                log.warning(msg)
        os.environ["FIBERASSIGN_USE_FABS"] = str(args.fba_use_fabs)

    for env_var in ["FIBERASSIGN_USE_FABS"]:
        log.info("run_assign_full(): use {}={}".format(env_var, os.getenv(env_var)))
```

--------------------------------

### Run QA with fba_run_qa

Source: https://fiberassign.readthedocs.io/en/latest/_sources/usage.rst.txt

Compute per-tile counts for different target types and write them to a JSON file, by default named "qa.json" in the output directory.

```console
%> fba_run_qa --dir out_raw
```

--------------------------------

### Compile fiberassign in place with build_ext

Source: https://fiberassign.readthedocs.io/en/latest/install.html

Compile fiberassign extension modules in the source tree. Update PATH and PYTHONPATH to use this source build.

```shell
%> python setup.py clean; python setup.py build_ext --inplace

```