| Version: | 1.4.1 | 
| Title: | DATRAS Trawl Survey Database Web Services | 
| Imports: | utils | 
| Suggests: | icesVocab | 
| Description: | R interface to access the web services of the ICES (International Council for the Exploration of the Sea) DATRAS trawl survey database https://datras.ices.dk/WebServices/Webservices.aspx. | 
| License: | GPL-2 | GPL-3 [expanded from: GPL (≥ 2)] | 
| URL: | https://datras.ices.dk/WebServices/Webservices.aspx, https://github.com/ices-tools-prod/icesDatras | 
| BugReports: | https://github.com/ices-tools-prod/icesDatras/issues | 
| RoxygenNote: | 7.2.3 | 
| Encoding: | UTF-8 | 
| NeedsCompilation: | no | 
| Packaged: | 2023-05-08 09:23:53 UTC; colin | 
| Author: | Colin Millar [aut, cre], Cecilia Kvaavik [aut], Adriana Villamor [aut], Scott Large [aut], Arni Magnusson [aut], Vaishav Soni [ctb] | 
| Maintainer: | Colin Millar <colin.millar@ices.dk> | 
| Repository: | CRAN | 
| Date/Publication: | 2023-05-08 09:40:05 UTC | 
DATRAS Trawl Survey Database Web Services
Description
R interface to access the web services of the ICES DATRAS trawl survey database.
Details
Exchange data:
| getHHdata | haul data | 
| getHLdata | length-based data | 
| getCAdata | age-based data | 
| getDATRAS | exchange data | 
Catch weights:
| getCatchWgt | catch weights | 
Survey indices:
| getIndices | survey indices | 
Overview of available data:
| getSurveyList | surveys | 
| getSurveyYearList | years | 
| getSurveyYearQuarterList | quarters | 
| getDatrasDataOverview | surveys, years, and quarters | 
Basic queries (thin web service wrappers):
getCAdata,
getHHdata,
getHLdata,
getIndices,
getSurveyList,
getSurveyYearList,
getSurveyYearQuarterList
Derived queries (combining web services with R computations):
getCatchWgt,
getDatrasDataOverview,
getDATRAS
Author(s)
Colin Millar, Scott Large, and Arni Magnusson.
References
ICES DATRAS database: http://datras.ices.dk.
ICES DATRAS web services: https://datras.ices.dk/WebServices/Webservices.aspx.
Check that a survey name is in the database
Description
Checks a survey name against a list of all survey names in the DATRAS database. If the name is not matched it puts up a message showing the available survey names.
Usage
checkSurveyOK(survey)
Arguments
| survey | the survey acronym, e.g. NS-IBTS. | 
Value
logical.
See Also
checkSurveyYearOK and getSurveyYearQuarterList
also perform checks against the DATRAS database.
icesDatras-package gives an overview of the package.
Examples
## Not run: 
checkSurveyOK(survey = "ROCKALL")
checkSurveyOK(survey = "NOTALL")
## End(Not run)
Check that a survey and year combination is in the database
Description
Checks a year and/or survey name against a list of all survey year combinations in the DATRAS database. If the combination is not matched it puts up a message showing the available options.
Usage
checkSurveyYearOK(survey, year, checksurvey = TRUE)
Arguments
| survey | the survey acronym, e.g. NS-IBTS. | 
| year | the year of the survey, e.g. 2010. | 
| checksurvey | logical, should the survey name also be checked. | 
Value
logical.
See Also
checkSurveyOK and checkSurveyYearQuarterOK
also perform checks against the DATRAS database.
icesDatras-package gives an overview of the package.
Examples
## Not run: 
checkSurveyYearOK(survey = "ROCKALL", 2015)
checkSurveyYearOK(survey = "ROCKALL", 2000)
checkSurveyYearOK(survey = "NOTALL", 2000)
## End(Not run)
Check that a survey, year and quarter combination is in the database
Description
Checks a quarter and/or year and/or survey name against a list of all survey year quarter combinations in the DATRAS database. If the combination is not matched it puts up a message showing the available options.
Usage
checkSurveyYearQuarterOK(
  survey,
  year,
  quarter,
  checksurvey = TRUE,
  checkyear = TRUE
)
Arguments
| survey | the survey acronym, e.g. NS-IBTS. | 
| year | the year of the survey, e.g. 2010. | 
| quarter | the quarter of the year the survey took place, i.e. 1, 2, 3 or 4. | 
| checksurvey | logical, should the survey name also be checked. | 
| checkyear | logical, should the year also be checked. | 
Value
logical.
See Also
checkSurveyOK and checkSurveyYearOK
also perform checks against the DATRAS database.
icesDatras-package gives an overview of the package.
Examples
## Not run: 
checkSurveyYearQuarterOK(survey = "ROCKALL", 2015, 3)
checkSurveyYearQuarterOK(survey = "ROCKALL", 2015, 1)
checkSurveyYearQuarterOK(survey = "ROCKALL", 2000, 1)
checkSurveyYearQuarterOK(survey = "NOTALL", 2000, 1)
# be careful of unexpected results with checksurvey and checkyear!
checkSurveyYearQuarterOK(survey = "NOTALL", 2000, 1, checksurvey=FALSE)
## End(Not run)
Get Age-Based Data
Description
Get age-based data such as sex, maturity, and age counts per length of sampled species.
Usage
getCAdata(survey, year, quarter)
Arguments
| survey | the survey acronym, e.g. NS-IBTS. | 
| year | the year of the survey, e.g. 2010. | 
| quarter | the quarter of the year the survey took place, i.e. 1, 2, 3 or 4. | 
Value
A data frame.
Author(s)
Colin Millar.
See Also
getDATRAS supports querying many years and quarters in one function call.
getHHdata and getHLdata get haul data and
length-based data.
icesDatras-package gives an overview of the package.
Examples
## Not run: 
cadata <- getCAdata(survey = "ROCKALL", year = 2002, quarter = 3)
str(cadata)
## End(Not run)
Get CPUE per Age per Haul per Hour for a given Survey, year and Quarter
Description
Get CPUE per Age per Haul per Hour for a given Survey, year and Quarter
Usage
getCPUEAge(survey, year, quarter)
Arguments
| survey | the survey acronym, e.g. NS-IBTS. | 
| year | the year of the survey, e.g. 2010. | 
| quarter | the quarter of interest, e.g. 1 | 
Value
A data frame.
Author(s)
Adriana Villamor.
See Also
getHHdata and getCAdata get haul data and
age-based data., and
getIndices, and
getCPUELength.
icesDatras-package gives an overview of the package.
Examples
## Not run: 
getCPUEperAge(survey = "NS-IBTS", year = 2018, quarter = 1)
## End(Not run)
Get CPUE per Length per Haul per Hour for a given Survey, year and Quarter
Description
Get CPUE per Length per Haul per Hour for a given Survey, year and Quarter
Usage
getCPUELength(survey, year, quarter)
Arguments
| survey | the survey acronym, e.g. NS-IBTS. | 
| year | the year of the survey, e.g. 2010. | 
| quarter | the quarter of interest, e.g. 1 | 
Value
A data frame.
Author(s)
Adriana Villamor.
See Also
getHHdata and getCAdata get haul data and
age-based data., and
getIndices, and
getCPUEAge.
icesDatras-package gives an overview of the package.
Examples
## Not run: 
getCPUELength(survey = "NS-IBTS", year = 2018, quarter = 1)
## End(Not run)
Get Catch Weights
Description
Calculate the total reported catch weight by species and haul.
Usage
getCatchWgt(survey, years, quarters, aphia)
Arguments
| survey | the survey acronym e.g. NS-IBTS. | 
| years | a vector of years of the survey, e.g. c(2010, 2012) or 2005:2010. | 
| quarters | a vector of quarters of the year the survey took place, e.g. c(1, 4) or 1:4. | 
| aphia | a vector of Aphia species codes defined in the WoRMS database, e.g. c(126436, 1264374). | 
Value
A data frame.
Note
The icesVocab package provides findAphia, a function to look up Aphia species codes.
See Also
getSurveyYearList, getSurveyYearQuarterList, and
getDatrasDataOverview also list available data.
icesDatras-package gives an overview of the package.
Examples
## Not run: 
getCatchWgt(survey = "ROCKALL", years = 2002, quarters = 3, aphia = 126437)
# look up specific species
aphia <- icesVocab::findAphia(c("cod", "haddock"))
cwt <- getCatchWgt(survey = "ROCKALL", years = 2002, quarters = 3, aphia = aphia)
## End(Not run)
Get Any DATRAS Data
Description
This function combines the functionality of getHHdata, getHLdata, and getCAdata. It supports querying many years and quarters in one function call.
Usage
getDATRAS(record = "HH", survey, years, quarters)
Arguments
| record | the data type required: "HH" haul data, "HL" length-based data, "CA" age-based data. | 
| survey | the survey acronym e.g. NS-IBTS. | 
| years | a vector of years of the survey, e.g. c(2010, 2012) or 2005:2010. | 
| quarters | a vector of quarters of the year the survey took place, i.e. c(1, 4) or 1:4. | 
Value
A data frame.
Author(s)
Scott Large and Colin Millar.
See Also
getHHdata, getHLdata, and getCAdata
get haul data, length-based data, and age-based data.
icesDatras-package gives an overview of the package.
Examples
## Not run: 
hhdata <- getDATRAS(record = "HH", survey = "ROCKALL", years = 2002, quarters = 3)
hldata <- getDATRAS(record = "HL", survey = "ROCKALL", years = 2002, quarters = 3)
cadata <- getDATRAS(record = "CA", survey = "ROCKALL", years = 2002, quarters = 3)
## End(Not run)
Summarize Data Availability
Description
Evaluate a presence-absence table for each survey with '1' where there is data and '0' (printed as '.') otherwise.
Usage
getDatrasDataOverview(surveys = NULL, long = TRUE)
Arguments
| surveys | a vector of survey names, or  | 
| long | whether tables should have year as row names (default) or column names. | 
Value
A list of tables.
See Also
getSurveyList, getSurveyYearList, and
getSurveyYearQuarterList also list available data.
icesDatras-package gives an overview of the package.
Examples
## Not run: 
getDatrasDataOverview(surveys = "ROCKALL", long = FALSE)
## End(Not run)
Get Flex File
Description
Get all information in HH plus estimates of Door Spread, Wing Spread and Swept Area per square km. Only available for NS-IBTS survey.
Usage
getFlexFile(survey, year, quarter)
Arguments
| survey | the survey acronym, e.g. NS-IBTS. | 
| year | the year of the survey, e.g. 2010. | 
| quarter | the quarter of the year the survey took place, i.e. 1, 2, 3 or 4. | 
Value
A data frame.
Author(s)
Adriana Villamor.
See Also
getDATRAS supports querying many years and quarters in one function call.
getHHdata get haul data
icesDatras-package gives an overview of the package.
Examples
## Not run: 
flex <- getFlexFile(survey = "NS-IBTS", year = 2020, quarter = 1)
str(flex)
# error checking examples:
flex <- getFlexFile(survey = "NS_IBTS", year = 2016, quarter = 1)
flex <- getFlexFile(survey = "NS-IBTS", year = 2030, quarter = 1)
flex <- getFlexFile(survey = "NS-IBTS", year = 2016, quarter = 6)
## End(Not run)
Get Haul Data
Description
Get haul data such as position, depth, sampling method, etc.
Usage
getHHdata(survey, year, quarter)
Arguments
| survey | the survey acronym, e.g. NS-IBTS. | 
| year | the year of the survey, e.g. 2010. | 
| quarter | the quarter of the year the survey took place, i.e. 1, 2, 3 or 4. | 
Value
A data frame.
Author(s)
Colin Millar.
See Also
getDATRAS supports querying many years and quarters in one function call.
getHLdata and getCAdata get length-based data and
age-based data.
icesDatras-package gives an overview of the package.
Examples
## Not run: 
hhdata <- getHHdata(survey = "ROCKALL", year = 2002, quarter = 3)
str(hhdata)
# error checking examples:
hhdata <- getHHdata(survey = "NS_IBTS", year = 2016, quarter = 1)
hhdata <- getHHdata(survey = "NS-IBTS", year = 2030, quarter = 1)
hhdata <- getHHdata(survey = "NS-IBTS", year = 2016, quarter = 6)
## End(Not run)
Get Length-Based Data
Description
Get length-based information such as measured length, individual counts, and sub-factors of sampled species.
Usage
getHLdata(survey, year, quarter)
Arguments
| survey | the survey acronym, e.g. NS-IBTS. | 
| year | the year of the survey, e.g. 2010. | 
| quarter | the quarter of the year the survey took place, i.e. 1, 2, 3 or 4. | 
Value
A data frame.
See Also
getDATRAS supports querying many years and quarters in one function call.
getHHdata and getCAdata get haul data and
age-based data.
icesDatras-package gives an overview of the package.
Examples
## Not run: 
hldata <- getHLdata(survey = "ROCKALL", year = 2002, quarter = 3)
str(hldata)
## End(Not run)
Get Survey Indices
Description
Get age based indices of abundance by species, survey and year.
Usage
getIndices(survey, year, quarter, species)
Arguments
| survey | the survey acronym, e.g. NS-IBTS. | 
| year | the year of the survey, e.g. 2010. | 
| quarter | the quarter of the year the survey took place, i.e. 1, 2, 3 or 4. | 
| species | the aphia species code for the species of interest. | 
Value
A data frame.
Note
The icesAdvice package provides findAphia, a function to look up Aphia species codes.
See Also
getDATRAS supports querying many years and quarters in one function call.
getHHdata and getCAdata get haul data and
age-based data.
icesDatras-package gives an overview of the package.
Examples
## Not run: 
haddock_aphia <- icesVocab::findAphia("haddock")
index <- getIndices(survey = "NS-IBTS", year = 2002, quarter = 3, species = haddock_aphia)
str(index)
## End(Not run)
Get Litter assessment output
Description
Get Litter assessment output by survey, year and quarter. The raw data are also included in this file.
Usage
getLTassessment(survey, year, quarter)
Arguments
| survey | the survey acronym, e.g. NS-IBTS. | 
| year | the year of the survey, e.g. 2010. | 
| quarter | the quarter of the year the survey took place, i.e. 1, 2, 3 or 4. | 
Value
A data frame.
Note
The icesAdvice package provides findAphia, a function to look up Aphia species codes.
See Also
getDATRAS supports querying many years and quarters in one function call.
getHHdata and getCAdata get haul data and
age-based data.
icesDatras-package gives an overview of the package.
Examples
## Not run: 
index <- getLTassessment(survey = "NS-IBTS", year = 2002, quarter = 3)
str(index)
## End(Not run)
Get a List of All Surveys
Description
Get a list of all survey acronyms.
Usage
getSurveyList()
Value
A character vector.
Author(s)
Colin Millar.
See Also
getSurveyYearList, getSurveyYearQuarterList, and
getDatrasDataOverview also list available data.
icesDatras-package gives an overview of the package.
Examples
## Not run: 
getSurveyList()
## End(Not run)
Get a List of Survey Years
Description
Get a list of all data years for a given survey.
Usage
getSurveyYearList(survey)
Arguments
| survey | the survey acronym, e.g. NS-IBTS. | 
Value
A numeric vector.
Author(s)
Colin Millar.
See Also
getSurveyList, getSurveyYearQuarterList, and
getDatrasDataOverview also list available data.
icesDatras-package gives an overview of the package.
Examples
## Not run: 
getSurveyYearList(survey = "ROCKALL")
## End(Not run)
Get a List of Quarters
Description
Get a list of quarters available for a given survey and year.
Usage
getSurveyYearQuarterList(survey, year)
Arguments
| survey | the survey acronym, e.g. NS-IBTS. | 
| year | the year of the survey, e.g. 2010. | 
Value
A numeric vector.
Author(s)
Colin Millar.
See Also
getSurveyYearList, getSurveyYearQuarterList, and
getDatrasDataOverview also list available data.
icesDatras-package gives an overview of the package.
Examples
## Not run: 
getSurveyYearQuarterList(survey = "ROCKALL", year = 2002)
## End(Not run)