Frequently Asked Questions

 

Using the Advanced Reporting system you can create and save custom queries of PIT tag data, which can then be set up to run on a schedule. The results can be emailed to one or more email addresses or exported to a file that will be available via the PTAGIS Web API.

See the tutorial video How to Subscribe to a Report for instructions on creating an email or file subscription in Advanced Reporting.

A few additional endpoints that provide direct, limited access to PIT tag data are also available via the PTAGIS web API and described in section titled API Data Endpoints below.

API Access to Advanced Reporting Exports

API access is the only way to programmatically download exported data from the reporting system as of February 2023.

NOTE: Manual download of exported files is available by logging in to the PTAGIS website and clicking on the MicroStrategy Exports link on the dashboard home page. From there, clicking on a file link will initiate a download via the browser to your local file system.

Programmatically, the report exports can be accessed by making a call to the PTAGIS Web API.

• https://api.ptagis.org/reporting/reports/[UserName] will return a list of available files for the specified user name
• https://api.ptagis.org/reporting/reports/[UserName]/file/[FileName] will return the specified file
• [UserName] equals the user name you use to log in to the PTAGIS website and [FileName] equals the full filename.

The following URLs are examples of the two calls above that will work in a browser but can also be used programmatically.

• https://api.ptagis.org/reporting/reports/ntancreto
• https://api.ptagis.org/reporting/reports/ntancreto/file/Complete%20Tag%20History.csv

Please see the Reporting section of the PTAGIS API documentation page for more details about these endpoints.

API Data Endpoints

In addition to retrieving custom query exports from the advanced reporting system, several endpoints with limited data querying are available. Please see the Data section of the PTAGIS API documentation page for more information.

PTAGIS uses the File Name as a key to identify a distinct set of unique PIT tag records. If two files with different File Names containing the same PIT tag records are loaded, this will generate duplicate records and one of the files will need to be removed in order to clear up the duplicate records. If you need to change a File Name for any reason, you will need to first remove the original file and then submit the new file. If you submit the new file without first removing the original file, this will result in duplicate records.

To remove a file from PTAGIS for any reason, submit an empty version of the file to PTAGIS as a Correction. An empty file is one in which all PIT tag records have been deleted or dotted out. We also recommend that the Session Message be updated to say something like "Empty file, contents now reported in NewFileName.xml."

If you need to update the File Name, but have not yet done so, do the following:

1. Make a copy of the original file with the incorrect File Name in P4.
2. Dot out or delete all PIT tag records in the original incorrect version of the file.
3. Update the Session Message to say something like "Empty file, contents now reported in NewFileName.xml."
4. Submit the incorrect, now empty file as a Correction. This will disown all Mark records and delete Recapture and Recovery records in that file.
5. Edit the copy of the file in P4 to correct the File Name.
6. Once the original incorrect file has been processed, submit the new file with the correct File Name as a Load. All the disowned records from step #4 will now be updated with the information in the new correct file.

If you have updated and submitted a file with a new File Name before removing the original file, resulting in duplicate records, do the following:

1. If you no longer have the original incorrect file in P4, log in to the PTAGIS website and download it from the Data Files > MRR Files section of the dashboard, and import it into P4. If you still have it in P4, go to step #2.
2. Dot out or delete all PIT tag records in the original incorrect version of the file.
3. Update the Session Message to say something like "Empty file, contents now reported in NewFileName.xml."
4. Submit the empty version of the incorrect file as a Correction. This will disown all Mark records and delete Recapture and Recovery records in that file.
5. Once the incorrect empty file has been processed, resubmit the file with the correct File Name as a Correction. This will clear the duplicate records and allow them to take over the disowned records from step #4.

 

When starting up P4, if you receive an error message that says "Unable to connect to the database. Database service is not running" it means that the SQL Server database service either did not start up or has stopped running. To fix this error, do the following:

1. Type Services in the Windows search panel to open Services
2. Look for the service called SQL Server (P4_SQLEXPRESS)
3. If the Status does not say Running, then right-click the service and select Start
4. If Startup Type is not set to Automatic, right-click the service and select Properties, and change the Startup type to Automatic

You may not be able to start the service or change the settings, and in those cases you should consult with your IT department for assistance.

 

Some limited PIT tag data can be exported without logging in by using the Complete Tag History or Observations reports. To build, save and export custom queries using the Advanced Reporting system, you will need to create an account and log in. The Advanced Reporting system provides more options for both building and exporting the results set you need. Data can be exported to Excel, CSV, Plain text, HTML, and PDF formats. There are two general methods for exporting from the advanced reporting system: interactive and subscription. See the reporting tutorials for more information on how to build, save, and export custom queries.

Excel files are exported using the Excel 2007 format (xlsx); CSV files are exported with comma delimiters and the fields are surrounded by double quotes; TXT files can be exported with any delimiter and the fields are not surrounded with double quotes.

Excel files are always exported using UTF-8 encoding and TXT files are always exported using UTF-16 encoding. Files exported to CSV, however, have different encoding depending on the method used to export them.

	Excel	CSV	TXT
Format Details	Excel 2007	Comma delimited Fields double-quoted	Delimiter specified by user Fields not quoted
Encoding with interactive export	UTF-8	UTF-8	UTF-16
Encoding with subscription export	UTF-8	UTF-16	UTF-16

Interactive exporting is done manually after you have run a report and are looking at the results set in your browser by going to Report Home / Export and selecting the desired export format. This will immediately export the current results set to the selected format and prompt you to download or open the resulting file.

Subscription exporting allows you to set up a schedule for your saved report to run and export the results to a file retrievable through the API or send them as an attachment to email.
You can also run a report and send the results to your history list so that when you log in to advanced reporting it is ready to view and does not need to execute against the database.

See this FAQ for more information about programmatically downloading data from PTAGIS.

During the smolt transportation season, fish collected from the juvenile bypass systems at Lower Granite, Little Goose, Lower Monumental, and McNary dams are either trucked or barged to an in-river release point below Bonneville Dam. PTAGIS maintains PIT tag interrogation equipment in these facilities with site codes of GRJ, GOJ, LMJ, and MCJ, respectively. The following information is pertinent only to these four sites. Note: No fish have been transported from McNary Dam since 2012. All fish passing through juvenile bypass systems at other hydroelectric facilities are returned to the river by default. All fish passing through juvenile bypass systems at other hydroelectric facilities are returned to the river by default.

At the four transportation facilities, the juvenile fish pass through a size and/or debris separator and are then routed into the collection facility. Adult salmon “fallbacks” are diverted from the separator and returned to the dam’s tailrace. During transportation season, fish are generally routed into the collection facility’s raceways where they are held until loaded onto a barge or tanker truck. Under some circumstances, the fish are direct-loaded to a barge as soon as they pass over the separator. A sample portion of the fish exiting the separator are routed to the facility’s lab, where biologists determine the species composition and densities of the group(s) of fish to be transported. Sample fish are also transported.

Beginning in 1993, PIT-tagged fish exiting the separator at these four sites have been bypassed directly back to the river by default. In 1996 this capability was expanded to allow the automatic segregation of specific PIT-tagged fish. This selective segregation of PIT-tagged fish is called Separation by Code (SbyC).  Separation by Code can be used to override the default bypassing of fish back to the river, or to collect a target group of fish for further hands-on sampling.

PTAGIS maintains PIT tag detectors in all of the routes through the smolt collection facilities, providing the means to track the movement of each fish through the facility. With this information it is possible to determine which PIT-tagged fish have been bypassed back to the river with high confidence, and to infer (but not confirm) which fish have been transported.

Using Last Antenna Group to Infer Disposition

The Interrogation Summary report, available through Query Builder 2 in the Advanced Reporting system,  returns a single record for each PIT tag code detected at a detection site. It also provides the time stamp and antenna group name of the tag’s first and last detection at the site. The Last Antenna Group attribute can be used to determine which PIT-tagged fish were bypassed back to the tailrace and to infer which fish were transported from the facility (see Caveats).

 

Last Antenna Group Name	Detection Time	Disposition
FULL FLOW BYPASS ADULT FISH RETURN DIVERSION RIVER EXIT SBYC RIVER EXIT RIVER-1 EXIT RIVER-2EXIT BYPASS RIVER EXIT	Any	Bypassed
If the name contains: RACEWAY or SAMPLE or SUBSAMPLE or BARGE	During transportation season	Probably Transported
If the name contains: RACEWAY and (EXIT or BARGE)	Outside of transportation season	Probably Bypassed
DIVERSION GATE SBYC GATE	Any	Not Transported but may not have been returned to the river
At LMJ: A-EXIT B-EXIT	During transportation season	Transported (direct-loaded) Or Bypassed -contact Corps’ site biologist for more information about these operations
Any other name	Any	Unknown – last detected at some intermediate point in the facility

 

Caveats

1. The transportation season at a site may be shorter than the collection season. Fish may be collected (passed through the separator) for monitoring purposes prior to the start of the transportation season. PTAGIS has attempted to record the dates when collection for transportation started and ended each year in each site’s Event Log, but these dates should be confirmed by Corps personnel.
2. McNary Dam had a “Spread the Risk” policy implemented for a number of years that called for the bypass of most fish during the spring, and transportation of most fish during Summer-like conditions. During the spring, only PIT-tagged fish marked for the Corps of Engineer’s Smolt Transportation Evaluation study were targeted for transportation; all other PIT-tagged fish were routed back to the tailrace and bypassed. No fish have been transported from McNary since 2012. Contact the site biologist for more information about these operations.
3. During the transportation season, not all fish at a “Raceway” antenna group are transported. On occasion, raceways are intentionally emptied to the river. If the fish in these raceways are routed through a pipe without a PIT tag monitor, or pass through a monitored pipe at a high density, they may exit the facility without a last “River” detection.
4. If a gate below a “Raceway” monitor leaks or fails, then fish may be routed out to the barge loading dock and dropped into the river, rather than loaded onto a barge and transported.

PTAGIS recommends that you contact the Corps’ site biologist to confirm transportation season dates and to inquire about any possible operational anomalies that may have occurred during the years in which you are interested.

PTAGIS no longer accepts tagging or interrogation data by email.

If you have never ordered PIT tags before, you will need to register for a PTAGIS account if you don't already have one and contact us or your BPA COR to be added as a PIT tag requester for your Fish and Wildlife project. Once you are a requester, you can do the following to request tags:

1. Log in to the website and navigate to Tag Distribution > Requests in the left navigation pane on the website dashboard.
2. Click the Request New PIT Tags link in the upper right corner of the page.
3. Choose your Fish and Wildlife project number in the FWP Project Number field.
4. Enter the earliest date and latest dates you would like the tags shipped to you.
5. Enter a number for each type of tag, all fields must be completed. For example, if you want 1000 standard 12mm tags only, enter 1000 into the Standard 12mm Tags field and zeroes in the other three Tag fields. Tags must be purchased in units of 100.
6. Complete the Recipient information. This is where the tags will be shipped.
7. Click the Save Request button.
8. Review the request details on the next page and if all looks good click the Submit Request button.
9. You will receive an email confirmation that your request has been submitted to BPA for review. You will also receive email notifications when the request has been approved and when the tags are shipped.

Event Sites and Release Sites are collectively referred to as MRR Sites. There are two main types of MRR sites in PTAGIS - stream and fixed locations. A stream location is definition for an entire stream or stream segment and can be used for multiple release sites on a stream by specifying the release river kilometer. A fixed location can be defined for a permanent man-made structure or prominent geographic feature, such as an acclimation pond, an island, a lake, or a trap.

To make a request for a new MRR site, please do the following:

1. Log in to the PTAGIS website and navigate to Validation Codes > MRR Sites in the left menu navigation.
2. Click Create Request.
3. Select the type of MRR site you would like to add.
4. Complete the form and click the Save Request button.
5. You should now see your request in a list on the main page.
6. Click the Submit link and review your request and then click the Submit Request button to submit it for review.

You will receive an automated email notification upon successful submission, approval and implementation of the new validation code. Once the code has been implemented, you will need to update the validation codes in P4 to make it available from the pick list.

 

With the increased variety of PIT tags available to Columbia Basin researchers, it is important to recognize not all PIT tags have the same performance characteristics. Performance characteristics of PIT tags can impact your projects and the projects of other researchers using PIT tag infrastructure in the Columbia Basin. If a tag has less of a chance of being detected, then research results could be skewed. If a tag is too powerful and overwhelms tags already in the system, it could affect others’ research.

The PIT Tag Steering Committee and PTAGIS strongly recommends tag performance be evaluated before researchers decide to purchase and release new PIT tags in the Columbia Basin.

Some organizations that purchase large amounts of PIT tags every year have contracted with PSMFC-PTAGIS to conduct rigorous testing of candidate PIT tags to inform the procurement process. The most recent Comprehensive PIT Tag Evaluations (CPTE) were conducted in 2011, 2014 and 2017. The tags that were selected for purchase as result of these CPTEs are listed in the table below, which is updated as new CPTEs are completed.

Standard Tags
General Tag Size	Tag Model Selected for Purchase	CPTE Test Year
12mm x 2mm	Biomark APT12	2017
12mm x 2mm	Biomark HPT12	2014
12mm x 2mm	Destron-Fearing/Biomark SST-1	2011
9mm x 2mm	Biomark HPT9	2017
9mm x 2mm	RFID Solutions PT300-1	2011

Specialty (Skinny) Tags*
General Tag Size	Tag Model Selected for Purchase	CPTE Test Year
10mm x 1.4mm	Biomark MiniHPT10	2017
10mm x 1.4mm	EID/Trovan ID-0162A10	2017
10mm x 1.4mm	EID/Trovan ID-1162A10	2017

*Specialty tags are occasionally evaluated during CPTE testing. Specialty tags are not typically purchased and stocked. Of the specialty tags tested these are the top performers. Specialty tags, while having characteristics that make them desirable in particular research applications, might not have the readability of standard tags.

These are not the only tags in use in the Columbia Basin, and it is not required that you use one of these tags. It is recommended that you carefully select a tag that meets your project needs and will perform well in current PTAGIS infrastructure.

If you are interested in working with PSMFC-PTAGIS to conduct CPTEs for your procurement process, please contact Don Warf at dlwarf@psmfc.org.

If you elect to purchase and use a tag that is new to the Columbia Basin, please be aware that you will need to request that the new tag mask be added to the PTAGIS tag mask validation codes. The tag mask validation codes are used to screen misreads and spurious tags from the reporting system. Please see article # 7 in the June 2014 PTAGIS newsletter for more information about tag mask validation in PTAGIS.

(Updated 02/09/2018)

 

An Unknown or Invalid Tag Mask error in P4 or after submitting data to PTAGIS or after searching for a tag in the Complete Tag History report indicates that the tag is not one of the tags known to be in use in the Columbia Basin PTAGIS infrastructure, or that the P4 Validation Codes need to be updated to download newly added Tag Masks to the local installation. 

The Tag Mask is made up of the first three characters before the period (e.g. 3D9, also known as the manufacturer code) and the next four characters after the period (e.g. 1D59), such as 3D9.1D59. PTAGIS keeps a set of validation codes just for Tag Masks to help prevent records with misreads and transcription errors from getting loaded into the database. It also helps to know what kind of tags are being used in the Columbia Basin, as the quality of tags can affect not only the detection probability of those tags, but all other tags in the system as well. To learn more about the validation PTAGIS uses to check Tag Masks, see article number 7 in the June 2014 newsletter.

When a PIT tag is scanned into P4, you may see an invalid tag mask error. Tag Mask validation can be enabled or disabled in the Profile configuration tool and is enabled by default. If you see this error, you should check the list of known tag masks. If your tags match any of the valid tag masks, then you likely just need to update the Validation Codes in P4. If your tags do not match any of the valid tag masks, then you will want to make a request to add the new Tag Mask to the official set of PTAGIS validation codes. See the last two paragraphs of this FAQ for more information.

When an MRR or Observation record is submitted with a tag mask that is not on the list of known masks, the record is loaded into the database, but categorized as Unknown. All Unknown records are filtered out of the reporting system automatically, so you will not see those records when querying the database or running a Complete Tag History, though it will let you know if records exist in PTAGIS for an Unknown tag and you can contact us for more information.

You can request that the Tag Mask be added to the PTAGIS validation codes. We strongly recommended that you check the quality of tags before purchasing them and if you still want to go with PIT tags that are new to PTAGIS, that you request to add the Tag Mask before you use any of them.

To request to add a new Tag Mask to the validation codes, the researcher who is planning to use the tags will need to complete a request by logging in to the website and navigating to Validation Codes > Tag Masks on the dashboard. Your request will then be reviewed by a member of the PIT Tag Steering Committee, and if approved implemented for use in PTAGIS.

The project coordinator can add or remove submitters from a PTAGIS MRR project by following these steps:

1. Log in to the PTAGIS website.
2. Navigate to MRR Project Admin > Manage Submitters in the dashboard left navigation menu.
3. Find the MRR Project you wish to update by searching for the code or scrolling through the pages.
4. Click the Details link for that MRR Project.
5. Click Add Submitter in the upper right to add a new submitter.
6. Click Edit next an existing submitter to review details and revoke access to the project.

Only the project coordinator can edit the list of authorized submitters.

 

Log in to the PTAGIS website and navigate to Interrogation Sites > Request Site. Complete all the required sections and then submit the request to the PTSC for review. An automated email will confirm that your request has been submitted and identify the PTSC member responsible for reviewing it. Another automated email will inform you when the request has been approved, or if more information is required. Once approved, PTAGIS will implement the new interrogation site and you will receive another email letting you know that it is registered in the system.

The PIT Tag Steering Committee (PTSC) requests that tagging data be tied to a project, rather than an individual. Each MRR Project has a 3-character code, project name and short description of the scope and/or geographic area of the PIT tag data collected and submitted to PTAGIS. There will be one coordinator, who is the person ultimately responsible for the quality of data submitted to PTAGIS. The coordinator’s contact information will be available on the PTAGIS website so data users can contact the coordinator with any questions about data collection methods or other context. The coordinator can change over time, so that as personnel retire or transfer positions, the project can continue under the same 3-character code.

MRR Projects must be based in the Columbia River Basin (CRB), unless there is a reasonable chance that fish tagged or detected by the project will intermingle with fish tagged in the CRB.

To request a new tag data project:

1. Log in to the PTAGIS website.
2. On the Dashboard left menu navigate to the Validation Codes > MRR Projects.
3. Click Create Request.
4. Enter a 3-character MRR Project Code, a Project Name, a Description of the scope and/or geographic area and type of tagging you will be doing, and the Reason you want to create this project in PTAGIS.
5. Click Save Request.
6. Review the project request details on the next page and click Submit Request.

You will receive an email confirming your request submission. The PTSC member responsible for reviewing your request will also be notified. After your request is reviewed and approved, PTAGIS will implement the new project code and you will be notified when it is ready to use.

Orphan records are created when a PIT tag is detected at any registered interrogation site or recaptured or recovered, but marking information has not yet been submitted for that tag code. Orphan records are indicated by the value ORPHAN in the Mark Site, Release Site and Tag File attributes. The Mark Date and Release Date attributes have values of 01/01/1900. An orphan record will be updated with marking information when a tag file is successfully loaded into PTAGIS that contains that PIT tag code as a mark record.

Disowned records are created when a previously loaded mark record is dotted out or changed from a mark event to a recapture or recovery event. Disowned records are indicated by the value DISOWN in the Mark Site, Release Site and Tag File attributes. The Mark Date is set to 01/01/1900 and the Release Date is set to 01/01/2100. Similar to an orphan record, a disowned record will be updated with marking information when a tag file is successfully loaded that contains that PIT tag code as a mark record.

Interrogation and MRR site location can be downloaded in several formats from the Map page:

• geodatabase download
• ESRI spatial data REST service endpoint
• CSV file download

Without logging in you can view the complete tag history for a single PIT tag using the Complete Tag History report.

In the Advanced Reporting tool, you can build custom queries to view information about many PIT tags at a time. See the reporting tutorials for more information.