| Title: | Data Analysis and Visualization for Skyscape Archaeology |
|---|---|
| Description: | Data reduction, visualization and statistical analysis of measurements of orientation of archaeological structures, following Silva (2020) <doi:10.1016/j.jas.2020.105138>. |
| Authors: | Silva Fabio [aut, cre], Reijs Victor [ctb], Gautschy Rita [ctb] |
| Maintainer: | Silva Fabio <[email protected]> |
| License: | GPL (>= 2) |
| Version: | 1.1-240925 |
| Built: | 2024-10-25 06:23:02 UTC |
| Source: | https://github.com/f-silva-archaeo/skyscaper |
This function returns the declination of the sun when it is at the anti-zenith for a given location with corrected average parallax. If this phenomena does not occur at given location (i.e. if location is outside the tropical band) the function returns a NULL value.
antizenith(loc, parallax = 0.00224, altitude = 0)antizenith(loc, parallax = 0.00224, altitude = 0)
loc |
This can be either the latitude of the location, or a skyscapeR.horizon object. |
parallax |
(Optional) Average parallax value for the sun. Defaults to 0.00224. |
altitude |
(Optional) Altitude of the sun. Defaults to 0 degrees. |
jS, dS, eq,
zenith, spatial.equinox, parallax.corr
# Anti-zenith sun declination for Mexico City: antizenith(19.419) # There is no anti-zenith sun phenomena in London: antizenith(51.507)# Anti-zenith sun declination for Mexico City: antizenith(19.419) # There is no anti-zenith sun phenomena in London: antizenith(51.507)
Convert discrete azimuth measurements into probability distributions
az.pdf( pdf = "normal", az, unc, name, verbose = T, .cutoff = 1e-04, .res = 0.01 )az.pdf( pdf = "normal", az, unc, name, verbose = T, .cutoff = 1e-04, .res = 0.01 )
pdf |
(Optional) String describing the probability distribution to be used. At the moment only normal and uniform are supported. Default is normal |
az |
An array of azimuths |
unc |
Azimuth uncertainties as either an array of the same length as az or a single value to be applied to all measurements |
name |
(Optional) An array of names to identify each measurement |
verbose |
(Optional) Boolean to control whether or not to display text. Default is TRUE. |
.cutoff |
(Optional) Value of probability distribution(s) at which point it will be cutoff to save on memory. Default is 1e-4 |
.res |
(Optional) Azimuth resolution with which to output probability distribution(s). Default is 0.01 degrees. |
Silva, F (2020) A probabilistic framework and significance test for the analysis of structural orientations in skyscape archaeology Journal of Archaeological Science 118, 105138. <doi:10.1016/j.jas.2020.105138>
test <- az.pdf(az=c(87,93,90,110), unc=3) plot(test)test <- az.pdf(az=c(87,93,90,110), unc=3) plot(test)
This function calculates the declination corresponding to an
orientation , i.e. an azimuth. The altitude can either be given
or, alternatively, if a skyscapeR.horizon object is provided,
the corresponding horizon altitude will be automatically retrieved.
This function is a wrapper for function swe_azalt_rev
of package swephR.
az2dec( az, loc, alt, refraction = skyscapeR.env$refraction, atm = skyscapeR.env$atm, temp = skyscapeR.env$temp )az2dec( az, loc, alt, refraction = skyscapeR.env$refraction, atm = skyscapeR.env$atm, temp = skyscapeR.env$temp )
az |
Azimuth(s) for which to calculate declination(s). See examples below. |
loc |
Location, can be either a skyscapeR.horizon object or, alternatively, an array of latitude values. |
alt |
(Optional) Altitude of orientation. If left empty and a skyscapeR.horizon
is provided then this is will automatically retrieved from the horizon data via |
refraction |
(Optional) Whether atmospheric refraction is to be taken into account.
If not given the value set by |
atm |
(Optional) Atmospheric pressure for refraction calculation.
If not given the value set by |
temp |
(Optional) Atmospheric temperature for refraction calculation.
If not given the value set by |
dec <- az2dec(az=92, loc=35, alt=2) dec <- az2dec(az=c(92,89,102), loc=35, alt=c(0,2,4)) # flat horizon with 2 degrees of altitude hor <- createHor(az=c(0,360), alt=c(2,2), loc=c(35,-8,25)) dec <- az2dec(92, loc=hor) # Can also be used for an array of azimuths: decs <- az2dec(az=c(87,92,110), loc=hor)dec <- az2dec(az=92, loc=35, alt=2) dec <- az2dec(az=c(92,89,102), loc=35, alt=c(0,2,4)) # flat horizon with 2 degrees of altitude hor <- createHor(az=c(0,360), alt=c(2,2), loc=c(35,-8,25)) dec <- az2dec(92, loc=hor) # Can also be used for an array of azimuths: decs <- az2dec(az=c(87,92,110), loc=hor)
Converts year number (epoch) to calendar year
BC.AD(year)BC.AD(year)
year |
year number |
BC.AD(100) BC.AD(0) BC.AD(-1) BC.AD(-99) BC.AD(-100)BC.AD(100) BC.AD(0) BC.AD(-1) BC.AD(-99) BC.AD(-100)
This function allows one to calculate the probability of having r structures out of n, orientated towards a target with probability p.
bernoulli.trial(n, p, r, type = "tail")bernoulli.trial(n, p, r, type = "tail")
n |
Total number of structures |
p |
Probability of target (e.g. ratio of azimuths) |
r |
Number of structures orientated towards target (hits) |
type |
(Optional) Type of probability to output. Possibilities are: (a) single in which case the result of a single Bernoulli trial is reported; or (b) tail in which case it calculates Bernoulli trials for all hit values between 1 and (r-1) and then outputs 1 minus the calculated probability. The latter is effectively a p-value. Default is tail |
Ruggles, C (1999) Astronomy in Prehistoric Britain and Ireland. Yale University Press.
# probability of having at least 10 out of 30 structures # aligned to targets covering 20% of the horizon bernoulli.trial(30, 0.2, 10)# probability of having at least 10 out of 30 structures # aligned to targets covering 20% of the horizon bernoulli.trial(30, 0.2, 10)
This function calculates the geocentric or topocentric declination and right ascension of solar
system bodies at a given time. It is a wrapper for function
swe_calc_ut of package swephR.
body.position( obj = "sun", time, timezone, calendar, dec, loc = NULL, refraction, atm, temp, verbose = T )body.position( obj = "sun", time, timezone, calendar, dec, loc = NULL, refraction, atm, temp, verbose = T )
obj |
(Optional) String containing name of the solar system body of interest. Can be any of the planets (inc. Pluto), the Moon, the Sun or the Ecliptic. Defaults to 'sun'. |
time |
Either a string containing the date and time in the format "YYYY/MM/DD HH:MM:SS"
(see |
timezone |
(Optional) Timezone of input either as a known acronym (e.g. "GMT", "CET") or
a string with continent followed by country capital (e.g. "Europe/London"). See
timezones for details. Only needed if time is a string. #' If not given the value set
by |
calendar |
(Optional) Calendar used in parameter time. G for gregorian and J for julian.
Only needed if time is a string. If not given the value set by |
dec |
(Optional) Output declination: geo for the geocentric, or topo for the topocentric
frame of reference. If not given the value set by |
loc |
(Optional) Location, only needed if output is in topocentric declination. |
refraction |
(Optional) Whether atmospheric refraction is to be taken into account.
If not given the value set by |
atm |
(Optional) Atmospheric pressure for refraction calculation.
If not given the value set by |
temp |
(Optional) Atmospheric temperature for refraction calculation.
If not given the value set by |
verbose |
(Optional) Boolean to control whether or not to display text. Default is TRUE. |
swe_calc_ut, timestring, time2jd
# Position of the sun at noon GMT on Christmas day 2018: body.position('sun', '2018/12/25 12:00:00', timezone='GMT') # Declination of the moon at same time body.position('moon', '2018/12/25 12:00:00', timezone='GMT')$equatorial$Dec# Position of the sun at noon GMT on Christmas day 2018: body.position('sun', '2018/12/25 12:00:00', timezone='GMT') # Declination of the moon at same time body.position('moon', '2018/12/25 12:00:00', timezone='GMT')$equatorial$Dec
Coordinate-transform azimuth prob distributions into declination prob distributions
coordtrans(pdf, hor, xrange, refraction, atm, temp, verbose = T, .res = 0.1)coordtrans(pdf, hor, xrange, refraction, atm, temp, verbose = T, .res = 0.1)
pdf |
A skyscapeR.pdf object created with |
hor |
A skyscapeR.horizon object created with |
xrange |
(Optional) Array of values (min and max) for SPD when transforming a skyscapeR.spd object. |
refraction |
(Optional) Whether atmospheric refraction is to be taken into account.
If not given the value set by |
atm |
(Optional) Atmospheric pressure for refraction calculation.
If not given the value set by |
temp |
(Optional) Atmospheric temperature for refraction calculation.
If not given the value set by |
verbose |
(Optional) Boolean to control whether or not to display text. Default is TRUE. |
.res |
(Optional) Declination resolution with which to output probability distribution(s). Default is 0.1 degrees. |
Silva, F (2020) A probabilistic framework and significance test for the analysis of structural orientations in skyscape archaeology Journal of Archaeological Science 118, 105138. <doi:10.1016/j.jas.2020.105138>
Az <- az.pdf(az=c(87,93,90,110), unc=3) hor <- createHor(az=c(0,360), alt=c(0,0), loc=c(35,-8,25)) # flat horizon with 0 degrees of altitude Dec <- coordtrans(Az, hor) plot(Dec)Az <- az.pdf(az=c(87,93,90,110), unc=3) hor <- createHor(az=c(0,360), alt=c(0,0), loc=c(35,-8,25)) # flat horizon with 0 degrees of altitude Dec <- coordtrans(Az, hor) plot(Dec)
This function creates a skyscapeR.horizon object from measurements of azimuth and altitude.
createHor(az, alt, alt.unc = 0.5, loc, name = "", smooth = F, .scale = 1000)createHor(az, alt, alt.unc = 0.5, loc, name = "", smooth = F, .scale = 1000)
az |
Array of azimuth values |
alt |
Array of altitude values. |
alt.unc |
(Optional) Either a single value or an array of altitude uncertainty. |
loc |
Location, a vector containing the latitude, longitude and elevation of the location, in this order. |
name |
Name of site. |
smooth |
Boolean to control whether to smooth horizon profile using rolling mean. Defaults to FALSE |
.scale |
Rolling mean window for smoothing. See |
# Create a skyscapeR.horizon from 5 measurements: az <- c(0,90,180,270,360) alt <- c(0,5,5,0,0) hor <- createHor(az, alt, 0.1, c(40.1,-8), 'Test') plot(hor)# Create a skyscapeR.horizon from 5 measurements: az <- c(0,90,180,270,360) alt <- c(0,5,5,0,0) hor <- createHor(az, alt, 0.1, c(40.1,-8), 'Test') plot(hor)
This function send a data request to HeyWhatsThat, for the creation of a horizon profile for a give Lat/Lon and elevation. It then downloads the data and saves it as a skyscapeR.horizon object.
createHWT(lat, lon, elevation = 1.6, name, src = "skyscapeR", verbose = T)createHWT(lat, lon, elevation = 1.6, name, src = "skyscapeR", verbose = T)
lat |
The latitude of the location. |
lon |
The longitude of the location. |
elevation |
(Optional) The elevation of the observer above ground level in meters. Default is 1.6 meters (eye level). |
name |
(Optional) Name for horizon. |
src |
(Optional) Request source ID for HeyWhatsThat. Default is 'skyscapeR'. Only change this if you have been given a source ID by the creator of HeyWhatsThat. |
verbose |
(Optional) Boolean switch to control output. Default is TRUE. |
## Not run: # Create and retrieve horizon data for the London Mithraeum: hor <- createHWT(lat=ten(51,30,45), lon=ten(0,5,26.1), name='London Mithraeum') ## End(Not run)## Not run: # Create and retrieve horizon data for the London Mithraeum: hor <- createHWT(lat=ten(51,30,45), lon=ten(0,5,26.1), name='London Mithraeum') ## End(Not run)
This function no longer works. Please use spd of density instead.
curvigram()curvigram()
This function downloads previously created horizon data from HeyWhatsThat, given its ID, and saves it as a skyscapeR.horizon object.
downloadHWT(HWTID)downloadHWT(HWTID)
HWTID |
This is the 8 character ID attributed by HeyWhatsThat.com |
## Not run: # Retrieve horizon data for \href{https://www.heywhatsthat.com/?view=HIFVTBGK}{Liverpool Cathedral}: hor <- downloadHWT('HIFVTBGK') ## End(Not run)## Not run: # Retrieve horizon data for \href{https://www.heywhatsthat.com/?view=HIFVTBGK}{Liverpool Cathedral}: hor <- downloadHWT('HIFVTBGK') ## End(Not run)
This function calculates the declination of the sun at December Solstice for a given year, based upon obliquity estimation and corrected average parallax.
dS( year = skyscapeR.env$cur.year, loc = FALSE, parallax = 0.00224, altitude = 0, verbose = TRUE )dS( year = skyscapeR.env$cur.year, loc = FALSE, parallax = 0.00224, altitude = 0, verbose = TRUE )
year |
Year for which to calculate the declination. Defaults to present year as given by Sys.Date. |
loc |
(Optional) This can be either the latitude of the location, or a skyscapeR.horizon object. If missing or FALSE, function will output geocentric declination. |
parallax |
(Optional) Average parallax value for the sun. Defaults to 0.00224. |
altitude |
(Optional) Altitude of the sun. Defaults to 0 degrees. |
verbose |
(Optional) Boolean to control output of warnings and messages. Defaults to TRUE. |
obliquity, jS, eq,
zenith, antizenith, spatial.equinox,
parallax.corr
# December Solstice geocentric declination for year 4001 BC: dS(-4000) # Topocentric declination for same year and latitude of 50 degrees N: dS(-4000, loc=50)# December Solstice geocentric declination for year 4001 BC: dS(-4000) # Topocentric declination for same year and latitude of 50 degrees N: dS(-4000, loc=50)
This function calculates the date, rise/set times, azimuth and declination for sun and moon on the days of the Spring Full Moon (SFM) and Autumn Full Moon (AFM), for a given year and location.
EFM( season = "spring", rise = T, year, loc, min.phase = 0.99, refraction, atm, temp, timezone, calendar )EFM( season = "spring", rise = T, year, loc, min.phase = 0.99, refraction, atm, temp, timezone, calendar )
season |
(Optional) Either 'spring' or 'autumn'. Default is 'spring. |
rise |
(Optional) Boolean to choose whether to calculate Equinoctial Full Moon rises or sets. Defaults to TRUE. |
year |
Epoch(s) for which to do calculations. Can be either a single value (the year), two values (range of years), or a vector of years. |
loc |
This can be either a skyscapeR.horizon object, or a vector with the latitude, longitude and elevation of the site, in this order. |
min.phase |
(Optional) Minimum lunar phase (between 0 and 1) for which a moon is considered to be full. Defaults to 0.99. |
refraction |
(Optional) Boolean for whether or not atmospheric refraction should be taken into account. Defaults to TRUE. |
atm |
(Optional) Atmospheric pressure (in mbar). Only needed if refraction is set to TRUE. Default is 1013.25 mbar. |
temp |
(Optional) Atmospheric temperature (in Celsius). Only needed if refraction is set to TRUE. Default is 15 degrees. |
timezone |
(Optional) Timezone for output of rising and setting time either as a known acronym (e.g. "GMT", "CET") or a string with continent followed by country capital (e.g. "Europe/London"). See timezones for details. Defaults to system timezone. |
calendar |
(Optional) Calendar used to output dates. G for gregorian and J for julian. Defaults to Gregorian. |
# Spring Full Moon from a location in Portugal in the year 2018 EFM(year=2018, loc=c(35,-8,100)) # Autumn Full Moons in the last three years ## Not run: EFM(season='autumn', year=c(2019,2021), loc=c(35,-8,100)) ## End(Not run)# Spring Full Moon from a location in Portugal in the year 2018 EFM(year=2018, loc=c(35,-8,100)) # Autumn Full Moons in the last three years ## Not run: EFM(season='autumn', year=c(2019,2021), loc=c(35,-8,100)) ## End(Not run)
This function calculates the declination of the sun at the astronomical equinox with corrected average parallax.
eq(loc = FALSE, parallax = 0.00224, altitude = 0, verbose = TRUE)eq(loc = FALSE, parallax = 0.00224, altitude = 0, verbose = TRUE)
loc |
(Optional) This can be either the latitude of the location, or a skyscapeR.horizon object. If missing or FALSE, function will output geocentric declination. |
parallax |
(Optional) Average parallax value for the sun. Defaults to 0.00224. |
altitude |
(Optional) Altitude of the sun. Defaults to 0 degrees. |
verbose |
(Optional) Boolean to control output of warnings and messages. Defaults to TRUE. |
obliquity, jS, eq,
zenith, antizenith, spatial.equinox, parallax.corr
# Equinoctial geocentric declination: eq() # Topocentric declination for same year and latitude of 50 degrees N: eq(loc=50)# Equinoctial geocentric declination: eq() # Topocentric declination for same year and latitude of 50 degrees N: eq(loc=50)
This function exports any skyscapeR.horizon object into the landscape format of Stellarium, ready to be imported.
exportHor(hor, name, author = "skyscapeR", description, ground_col, hor_col)exportHor(hor, name, author = "skyscapeR", description, ground_col, hor_col)
hor |
Horizon data in skyscapeR.horizon format. |
name |
Horizon name to be displayed in Stellarium, if different from one in skyscapeR.horizon object. |
author |
(Optional) Author, to be included in landscape.ini file. |
description |
(Optional) Description, to be included in landscape.ini file. |
ground_col |
Color of ground. Defaults to Stellarium's default. |
hor_col |
Color of horizon line. Defaults to Stellarium's default. |
Stellarium: a free open source planetarium
createHor, downloadHWT, plot.skyscapeR.horizon
# Downloads horizon data from HeyWhatsThat and exports it into Stellarium: ## Not run: hor <- downloadHWT('HIFVTBGK') exportHor(hor, name='Test', description='Test horizon export to Stellarium') ## End(Not run)# Downloads horizon data from HeyWhatsThat and exports it into Stellarium: ## Not run: hor <- downloadHWT('HIFVTBGK') exportHor(hor, name='Test', description='Test horizon export to Stellarium') ## End(Not run)
Find celestial targets within declination and time ranges
findTargets( decrange, timerange, max.mag = 2.5, loc = FALSE, calendar = skyscapeR.env$calendar )findTargets( decrange, timerange, max.mag = 2.5, loc = FALSE, calendar = skyscapeR.env$calendar )
decrange |
Range of declination to consider. |
timerange |
Temporal range to consider |
max.mag |
(Optional) Maximum magnitude of stars to consider. Defaults to 2.5 |
loc |
Location, either a skyscapeR.object or a vector containing the latitude, longitude and elevation of location, in this order. Defaults to FALSE, thus checking only geocentric declination. |
calendar |
(Optional) Calendar used in parameter time. G for gregorian and J for julian.
If not given the value set by |
## Not run: findTargets(c(-25,-17.5), c(-2500,-1750)) # if a location is given then the zenith and anti-zenith sun will also be looked at: findTargets(c(3,12), c(-2500,-1750), loc=c(8.6, 7.3, 200)) # if a horizon profile is given then the spatial equinox will also be looked at: hor <- downloadHWT('J657KVEV') findTargets(c(-7,2), c(-2500,-1750), loc=hor) ## End(Not run)## Not run: findTargets(c(-25,-17.5), c(-2500,-1750)) # if a location is given then the zenith and anti-zenith sun will also be looked at: findTargets(c(3,12), c(-2500,-1750), loc=c(8.6, 7.3, 200)) # if a horizon profile is given then the spatial equinox will also be looked at: hor <- downloadHWT('J657KVEV') findTargets(c(-7,2), c(-2500,-1750), loc=hor) ## End(Not run)
This function retrieves the horizon altitude for a given azimuth from a previously created skyscapeR.horizon object via spline interpolation.
hor2alt(hor, az, return.unc = F)hor2alt(hor, az, return.unc = F)
hor |
A skyscapeR.horizon object from which to retrieve horizon altitude. |
az |
Array of azimuth(s) for which to retrieve horizon altitude(s). |
return.unc |
(Optional) Boolean switch control where to output altitude uncertainty. Default is FALSE. |
hor <- downloadHWT('HIFVTBGK') hor2alt(hor, 90)hor <- downloadHWT('HIFVTBGK') hor2alt(hor, 90)
Retrieves maximum declination for a given horizon
hor2max.dec(hor, alt = 0, range = 25)hor2max.dec(hor, alt = 0, range = 25)
hor |
Either a skyscapeR.horizon object or the latitude of the place. |
alt |
(Optional) Altitude of the horizon at northernmost point. Only necessary if no skyscapeR.horizon object is provided. Default is 0. |
range |
(Optional) Range of azimuths to check for maximum declination. Default is 25 degrees either side of North. |
hor <- downloadHWT('HIFVTBGK') hor2max.dec(hor)hor <- downloadHWT('HIFVTBGK') hor2max.dec(hor)
Retrieves minimum declination for a given horizon
hor2min.dec(hor, alt = 0, range = 25)hor2min.dec(hor, alt = 0, range = 25)
hor |
Either a skyscapeR.horizon object or the latitude of the place. |
alt |
(Optional) Altitude of the horizon at southernmost point. Only necessary if no skyscapeR.horizon object is provided. Default is 0. |
range |
(Optional) Range of azimuths to check for maximum declination. Default is 25 degrees either side of South |
hor <- downloadHWT('HIFVTBGK') hor2min.dec(hor)hor <- downloadHWT('HIFVTBGK') hor2min.dec(hor)
Returns the high-density region of a probability distribution
hpdi(x, mass = 0.954)hpdi(x, mass = 0.954)
x |
A skyscapeR.spd or skyscapeR.pdf object. |
mass |
(Optional) Probability mass of the region. Default is 0.954. |
Converts Julian date and time (in any timezone) to julian date
jd2time(jd, timezone, calendar, verbose = F)jd2time(jd, timezone, calendar, verbose = F)
jd |
Julian date in numeric format |
timezone |
(Optional) Desired timezone for output either as a known acronym (e.g. "GMT", "CET") or
a string with continent followed by country capital (e.g. "Europe/London"). See
|
calendar |
(Optional) Calendar used in parameter time. G for gregorian and J for julian. Only needed if time is a string. Defaults to Gregorian. |
verbose |
(Optional) Controls whether messages should be displayed. Default is FALSE. |
swe_julday, as.POSIXlt, timezones
jd <- time2jd('2018/12/25 12:00:00', 'GMT') # Julian date at noon GMT on Christmas day 2018 jd2time(jd, 'CET') # converts julian date to Central European timezonejd <- time2jd('2018/12/25 12:00:00', 'GMT') # Julian date at noon GMT on Christmas day 2018 jd2time(jd, 'CET') # converts julian date to Central European timezone
This function calculates the declination of the sun at June Solstice for a given year, based upon obliquity estimation and corrected average parallax.
jS( year = skyscapeR.env$cur.year, loc = FALSE, parallax = 0.00224, altitude = 0, verbose = TRUE )jS( year = skyscapeR.env$cur.year, loc = FALSE, parallax = 0.00224, altitude = 0, verbose = TRUE )
year |
Year for which to calculate the declination. Defaults to present year as given by Sys.Date. |
loc |
(Optional) This can be either the latitude of the location, or a skyscapeR.horizon object. If missing or FALSE, function will output geocentric declination. |
parallax |
(Optional) Average parallax value for the sun. Defaults to 0.00224. |
altitude |
(Optional) Altitude of the sun. Defaults to 0 degrees. |
verbose |
(Optional) Boolean to control output of warnings and messages. Defaults to TRUE. |
obliquity, dS, eq,
zenith, antizenith, spatial.equinox,
parallax.corr
# June Solstice geocentric declination for year 4001 BC: jS(-4000) # Topocentric declination for same year and latitude of 50 degres N: jS(-4000, loc=50)# June Solstice geocentric declination for year 4001 BC: jS(-4000) # Topocentric declination for same year and latitude of 50 degres N: jS(-4000, loc=50)
Converts day-month in 'MM-DD' format to a more readable format
long.date(date)long.date(date)
date |
date in 'MM-DD' format |
long.date('01-01') long.date('08-23')long.date('01-01') long.date('08-23')
This function estimates the magnetic declination at a given location
and moment in time, using the 12th generation International
Geomagnetic Reference Field (IGRF) model. This function is a wrapper
for function magneticField of package oce.
mag.dec(loc, date)mag.dec(loc, date)
loc |
Location, can be either a skyscapeR.horizon object or, alternatively, a latitude. |
date |
Date for which to calculate magnetic declination in the format: 'YYYY/MM/DD' |
# Magnetic Declination for London on April 1st 2016: loc <- c( 51.5074, -0.1278 ) mag.dec( loc, "2016/04/01" )# Magnetic Declination for London on April 1st 2016: loc <- c( 51.5074, -0.1278 ) mag.dec( loc, "2016/04/01" )
Significance test against a null model
modelTest( pdf, model, nsims = 1000, conf = 0.95, tails = 2, normalise = F, ncores = parallel::detectCores() - 1, save.sim = F, verbose = T )modelTest( pdf, model, nsims = 1000, conf = 0.95, tails = 2, normalise = F, ncores = parallel::detectCores() - 1, save.sim = F, verbose = T )
pdf |
A skyscapeR.pdf object created with either |
model |
A data.frame or list of data.frames with equal number to the empirical observations. See example for structure |
nsims |
(Optional) Number of simulations to run. Default is 1000. |
conf |
(Optional) Confidence envelope (in percentage) of the null model to calculate. Default is .95 |
tails |
(Optional) Whether to calculate 1-tailed p-value (greater than) or 2-tailed p-value (smaller than or greater than). Default is 2. |
normalise |
(Optional) Boolean to control whether to normalize SPDs. Default is FALSE |
ncores |
(Optional) Number of CPU cores to use. Default is the number of available cores minus 1. |
verbose |
(Optional) Boolean to control whether or not to display text. Default is TRUE. |
.res |
(Optional) Resolution with which to output probability distribution(s). Default is 0.1 degrees. |
This function calculates the moon phase, in percentage of full. It is a wrapper
for function swe_pheno_ut of package swephR.
moonphase(time, timezone, calendar)moonphase(time, timezone, calendar)
time |
Either a string containing the date and time in the format "YYYY-MM-DD HH:MM:SS"
(see |
timezone |
(Optional) Timezone of input either as a known acronym (e.g. "GMT", "CET") or a string with continent followed by country capital (e.g. "Europe/London"). See timezones for details. Only needed if time is a string. Defaults to system timezone. |
calendar |
(Optional) Calendar used in parameter time. G for gregorian and J for julian. Only needed if time is a string. Defaults to Gregorian. |
# Moonphase at noon GMT on Christmas day 2018: moonphase('2018/12/25 12:00:00', 'GMT')# Moonphase at noon GMT on Christmas day 2018: moonphase('2018/12/25 12:00:00', 'GMT')
This function calculates the declination of the northern major Lunar Extreme for a given year, based upon obliquity estimation and corrected average parallax.
nMjLX( year = skyscapeR.env$cur.year, loc = FALSE, parallax = 0.952, altitude = 0, verbose = TRUE )nMjLX( year = skyscapeR.env$cur.year, loc = FALSE, parallax = 0.952, altitude = 0, verbose = TRUE )
year |
Year for which to calculate the declination. Defaults to present year as given by Sys.Date. |
loc |
(Optional) This can be either the latitude of the location, or a skyscapeR.horizon object. If missing or FALSE, function will output geocentric declination. |
parallax |
(Optional) Average parallax value for the moon Defaults to 0.952. |
altitude |
(Optional) Altitude of the sun. Defaults to 0 degrees. |
verbose |
(Optional) Boolean to control output of warnings and messages. Defaults to TRUE. |
nmnLX, smnLX, sMjLX,
parallax.corr
# Northern major Lunar Extreme geocentric declination for year 2501 BC: nMjLX(-2500) # Topocentric declination for same year and latitude of 50 degrees N: nMjLX(-2500, loc=50)# Northern major Lunar Extreme geocentric declination for year 2501 BC: nMjLX(-2500) # Topocentric declination for same year and latitude of 50 degrees N: nMjLX(-2500, loc=50)
This function calculates the declination of the northern minor Lunar Extreme for a given year, based upon obliquity estimation and corrected average parallax.
nmnLX( year = skyscapeR.env$cur.year, loc = FALSE, parallax = 0.952, altitude = 0, verbose = TRUE )nmnLX( year = skyscapeR.env$cur.year, loc = FALSE, parallax = 0.952, altitude = 0, verbose = TRUE )
year |
Year for which to calculate the declination. Defaults to present year as given by Sys.Date. |
loc |
(Optional) This can be either the latitude of the location, or a skyscapeR.horizon object. If missing or FALSE, function will output geocentric declination. |
parallax |
(Optional) Average parallax value for the moon Defaults to 0.952. |
altitude |
(Optional) Altitude of the sun. Defaults to 0 degrees. |
verbose |
(Optional) Boolean to control output of warnings and messages. Defaults to TRUE. |
smnLX, nMjLX, sMjLX,
parallax.corr
# Northern minor Lunar Extreme geocentric declination for year 2501 BC: nmnLX(-2500) # Topocentric declination for same year and latitude of 50 degrees N: nmnLX(-2500, loc=50)# Northern minor Lunar Extreme geocentric declination for year 2501 BC: nmnLX(-2500) # Topocentric declination for same year and latitude of 50 degrees N: nmnLX(-2500, loc=50)
This function calculates the obliquity for a given epoch. It is a
wrapper for function swe_calc_ut of package swephR.
obliquity(year = skyscapeR.env$cur.year)obliquity(year = skyscapeR.env$cur.year)
year |
Year for which to calculate the obliquity. Defaults to present year as given by Sys.Date |
Laskar, J. et al. (2004), A long-term numerical solution for the insolation quantities of the Earth, Astron. Astroph., 428, 261-285, doi:10.1051/0004-6361:20041335.
#' # Obliquity for year 3999 BC: obliquity(-4000)#' # Obliquity for year 3999 BC: obliquity(-4000)
This function calculates the visible path of a celestial object from any location on earth. It outputs a skyscapeR.orbit object, which includes AZ and ALT information.
orbit(dec, loc, res = 0.25, refraction, atm, temp)orbit(dec, loc, res = 0.25, refraction, atm, temp)
dec |
Declination of object. |
loc |
Location, either a skyscapeR.object or a vector containing the latitude and longitude of location, in this order. |
res |
The resolution (in degrees of RA) with which to calculate the path. |
refraction |
(Optional) Whether atmospheric refraction is to be taken into account.
If not given the value set by |
atm |
(Optional) Atmospheric pressure for refraction calculation.
If not given the value set by |
temp |
(Optional) Atmospheric temperature for refraction calculation.
If not given the value set by |
# Visible path of sun on june solstice on year 3999 BC from London: sun.dec <- jS(-4000) london.lat <- 51.5074 #N london.lon <- -0.1278 #W loc <- c( london.lat, london.lon, 0 ) path <- orbit(sun.dec, loc) plot(path$az, path$alt, ylim=c(0,90), type='l', xlab='AZ', ylab='ALT', col='red', lwd=2)# Visible path of sun on june solstice on year 3999 BC from London: sun.dec <- jS(-4000) london.lat <- 51.5074 #N london.lon <- -0.1278 #W loc <- c( london.lat, london.lon, 0 ) path <- orbit(sun.dec, loc) plot(path$az, path$alt, ylim=c(0,90), type='l', xlab='AZ', ylab='ALT', col='red', lwd=2)
Given the average parallax, this function corrects this value for a given latitude of the observer and for the altitude of the celestial object.
parallax.corr(parallax, loc, altitude = 0)parallax.corr(parallax, loc, altitude = 0)
parallax |
Average parallax to correct (e.g. 0.00224 for the Sun, or 0.952 for the Moon) |
loc |
This can be either the latitude of the location, or a skyscapeR.horizon object. |
altitude |
(Optional) Altitude of the celestial object.. Defaults to 0 degrees. |
# Parallax correction for the moon, as seen from latitude 50ºN and at 0º altitude parallax.corr(0.952, 50, 0)# Parallax correction for the moon, as seen from latitude 50ºN and at 0º altitude parallax.corr(0.952, 50, 0)
This function calculates the maximum and minimum declinations of the five visible planets for a given epoch. This is done by calculating the declination for one entire orbital period centred around the epoch.
planet.extremes(obj, epoch, loc = NULL)planet.extremes(obj, epoch, loc = NULL)
obj |
The name of the planet. |
epoch |
Epoch for which to do calculations. |
loc |
(Optional) This can be either a skyscapeR.horizon object, or a vector with the latitude, longitude and elevation of the site, in this order. |
planet.extremes('Jupiter', 2023) planet.extremes('Venus', -4000)planet.extremes('Jupiter', 2023) planet.extremes('Venus', -4000)
This function creates a plot of horizon data.
## S3 method for class 'skyscapeR.horizon' plot( x, show.az = F, xlim, ylim, obj, refraction = F, col.ground = "darkgreen", col.sky, ... )## S3 method for class 'skyscapeR.horizon' plot( x, show.az = F, xlim, ylim, obj, refraction = F, col.ground = "darkgreen", col.sky, ... )
x |
Object of skyscapeR.horizon format. |
show.az |
(Optional) Boolean that controls whether to display azimuth values or cardinal directions. Defaults to FALSE. |
xlim |
(Optional) Azimuth rage for plotting. |
ylim |
(Optional) Altitude rage for plotting. |
obj |
(Optional) A skyscapeR.object object created with |
refraction |
(Optional) Boolean switch controlling whether to take refraction into account when displaying the paths of celestial objects. |
col.ground |
(Optional) Color of the ground. Defaults to darkgreen. |
col.sky |
(Optional) Color of the sky. Defaults to white. |
... |
Additional arguments to be passed to plot. |
# Plot a horizon retrieved from HeyWhatsThat: hor <- downloadHWT('HIFVTBGK') plot(hor) # Add the paths of the solstices and equinoxes sun in the year 1999 BC: tt <- sky.objects('solar extremes', epoch=-2000, col='blue') plot(hor, obj=tt)# Plot a horizon retrieved from HeyWhatsThat: hor <- downloadHWT('HIFVTBGK') plot(hor) # Add the paths of the solstices and equinoxes sun in the year 1999 BC: tt <- sky.objects('solar extremes', epoch=-2000, col='blue') plot(hor, obj=tt)
Plot orientation probability distributions
## S3 method for class 'skyscapeR.pdf' plot( x, index, hdr = 0.954, show.az = T, xlim, col = MESS::col.alpha("blue", 0.5), ... )## S3 method for class 'skyscapeR.pdf' plot( x, index, hdr = 0.954, show.az = T, xlim, col = MESS::col.alpha("blue", 0.5), ... )
x |
A skyscapeR.pdf object created with either |
index |
(Optional) A value to indicate which distribution to plot, when only one is desired. |
hdr |
(Optional) High density region to highlight. Defaults to 0.954 |
show.az |
(Optional) Whether to show the azimuth and transformation curve (horizon) when displaying declination distributions. Defaults to TRUE. |
xlim |
(Optional) Range of x-axis to plot. |
col |
(Optional) Color of high density region to highlight. Defaults to blue with 0.5 alpha. |
... |
Additional arguments to be passed to plot. |
Plot significance test of orientations
## S3 method for class 'skyscapeR.sigTest' plot( x, xlim, title = NULL, col = "blue", show.pval = T, show.local = F, pal = brewer.pal(5, "PRGn")[c(1, 5)], ... )## S3 method for class 'skyscapeR.sigTest' plot( x, xlim, title = NULL, col = "blue", show.pval = T, show.local = F, pal = brewer.pal(5, "PRGn")[c(1, 5)], ... )
x |
A skyscapeR.sigTest object created with |
xlim |
(Optional) Range of x-axis to plot. |
title |
(Optional) Title to add to the plot. |
col |
(Optional) Color of summed probability density. Defaults to blue. |
show.pval |
(Optional) Boolean to control whether to print the global p-value. Default is TRUE. |
show.local |
(Optional) Boolean to control whether to show local regions of significance. Default is FALSE |
pal |
(Optional) Color palette for local regions of significance. Default is brewer.pal(5, 'PRGn') |
... |
Additional arguments to be passed to plot. |
Plot orientation summed probability density
## S3 method for class 'skyscapeR.spd' plot(x, xlim, ylim, title = NULL, col = "blue", shading = T, ...)## S3 method for class 'skyscapeR.spd' plot(x, xlim, ylim, title = NULL, col = "blue", shading = T, ...)
x |
A skyscapeR.spd object created with |
xlim |
(Optional) Range of x-axis to plot. |
ylim |
(Optional) Range of y-axis to plot. |
title |
(Optional) Title to add to the plot. |
col |
(Optional) Color of summed probability density. Defaults to blue. |
shading |
(Optional) Boolean to control whether to color the entire distribution. Defaults to TRUE |
... |
Additional arguments to be passed to plot. |
This function creates a plot of stellar seasonality and phases/events.
## S3 method for class 'skyscapeR.starphases' plot(x, y, show.labels = T, show.legend = T, show.grid = F, sort.by, pal, ...)## S3 method for class 'skyscapeR.starphases' plot(x, y, show.labels = T, show.legend = T, show.grid = F, sort.by, pal, ...)
x |
Object of skyscapeR.starphases format. |
y |
(Optional) A second object of skyscapeR.starphases format or a list of skyscapeR.starphases objects for plotting (see Examples). |
show.legend |
(Optional) Only used when plotting seasonality of multiple stars (see example below). Default is TRUE. |
show.grid |
(Optional) Boolean to control whether to show a grid of months. Default is FALSE |
pal |
(Optional) Colour palette for displaying phases/seasons. |
... |
Additional arguments to be passed to plot. |
# Plot the seasonality of Aldebaran for 3999 BCE: s1 <- star.phases('Aldebaran',-4000, c(35,-8, 200)) plot(s1) # Plot seasonality of several stars s2 <- star.phases('Alnilam',-4000, c(35,-8, 200)) s3 <- star.phases('Elnath',-4000, c(35,-8, 200)) plot(s1, s2) plot(s1, list(s2,s3)) plot(sl, show.legend=F, show.grid=T)# Plot the seasonality of Aldebaran for 3999 BCE: s1 <- star.phases('Aldebaran',-4000, c(35,-8, 200)) plot(s1) # Plot seasonality of several stars s2 <- star.phases('Alnilam',-4000, c(35,-8, 200)) s3 <- star.phases('Elnath',-4000, c(35,-8, 200)) plot(s1, s2) plot(s1, list(s2,s3)) plot(sl, show.legend=F, show.grid=T)
Polar plot of orientations (azimuths)
plotAzimuth(az, col = "blue", lwd = 1.5, lty = 1, obj, show.obj.labels = T)plotAzimuth(az, col = "blue", lwd = 1.5, lty = 1, obj, show.obj.labels = T)
az |
(Optional) Array of azimuths. Can be omitted is obj is given. |
col |
(Optional) Single color or color palette to use for plotting measurements. |
lwd |
(Optional) Line width to plot measurements. Defaults to 1. |
lty |
(Optional) Line type to plot measurements. Defaults to 1. |
obj |
(Optional) A skyscapeR.object object created with |
show.obj.labels |
(Optional) Boolean to control whether to display celestial objects names. Defaults to TRUE. |
# Plot some azimuth data: az <- c(120, 100, 93, 97, 88, 115, 112, 67) plotAzimuth(az) # To visualize this data against the common solar and lunar targets: tt <- sky.objects('solar extremes', epoch=-2000, loc=c(35,-8), col='red') plotAzimuth(az, obj=tt) # To display only celestial objects plotAzimuth(obj=tt)# Plot some azimuth data: az <- c(120, 100, 93, 97, 88, 115, 112, 67) plotAzimuth(az) # To visualize this data against the common solar and lunar targets: tt <- sky.objects('solar extremes', epoch=-2000, loc=c(35,-8), col='red') plotAzimuth(az, obj=tt) # To display only celestial objects plotAzimuth(obj=tt)
Bar plot of orientations (declination)
plotBars( val, unc, names, unit = "Declination", col = "blue", shade = TRUE, mark = TRUE, sort = FALSE, xrange, yrange, obj, show.obj.label = TRUE )plotBars( val, unc, names, unit = "Declination", col = "blue", shade = TRUE, mark = TRUE, sort = FALSE, xrange, yrange, obj, show.obj.label = TRUE )
val |
Array of declination or azimuth values. |
unc |
Single value or array of measurement uncertainty |
names |
(Optional) Array of names of measurements in val |
unit |
(Optional). Either 'Declination' or 'Azimuth'. Defaults to 'Declination'. |
col |
(Optional) Color to plot measurements in. Defaults to blue. |
shade |
(Optional) Boolean to control whether to shade a polygon of measurements. Defaults to TRUE |
mark |
(Optional) Boolean to control whether to mark the declination value. Defaults to TRUE |
sort |
(Optional) Boolean to control whether to sort the measurements by their declination value. Defaults to FALSE |
xrange |
(Optional) Array of limits for x-axis. |
yrange |
(Optional) Array of limits for y-axis. |
obj |
(Optional) A skyscapeR.object object created with |
show.obj.label |
(Optional) Boolean to control whether to label the celestial objects in the polar plot. Defaults to TRUE. |
# Plot some declination data: decs <- c(10, 12, -5, 4) plotBars(decs, unc=5) # To visualize this data against the common solar and lunar targets: tt <- sky.objects(c('solar extremes','lunar extremes'), epoch=-2000, lty=c(2,3)) plotBars(decs, unc=5, obj=tt)# Plot some declination data: decs <- c(10, 12, -5, 4) plotBars(decs, unc=5) # To visualize this data against the common solar and lunar targets: tt <- sky.objects(c('solar extremes','lunar extremes'), epoch=-2000, lty=c(2,3)) plotBars(decs, unc=5, obj=tt)
This function prints the results of randomTest.
## S3 method for class 'skyscapeR.sigTest' print(x, ...)## S3 method for class 'skyscapeR.sigTest' print(x, ...)
x |
Object of skyscapeR.sigTest format. |
... |
Additional arguments to be passed to print. |
Converts p-value into symbol
pval2stars(p.value)pval2stars(p.value)
p.value |
p-value |
Significance test against the null hypothesis of random orientation
randomTest( pdf, .res = 0.1, nsims = 1000, conf = 0.95, tails = 2, normalise = F, ncores = parallel::detectCores() - 1, verbose = T, hor, refraction, atm, temp )randomTest( pdf, .res = 0.1, nsims = 1000, conf = 0.95, tails = 2, normalise = F, ncores = parallel::detectCores() - 1, verbose = T, hor, refraction, atm, temp )
pdf |
A skyscapeR.pdf object created with either |
.res |
(Optional) Resolution with which to output probability distribution(s). Default is 0.1 degrees. |
nsims |
(Optional) Number of simulations to run. Default is 1000. |
conf |
(Optional) Confidence envelope (in percentage) of the null model to calculate. Default is .95 |
tails |
(Optional) Whether to calculate 1-tailed p-value (greater than) or 2-tailed p-value (smaller than or greater than). Default is 2. |
normalise |
(Optional) Boolean to control whether to normalize SPDs. Default is FALSE |
ncores |
(Optional) Number of CPU cores to use. Default is the number of available cores minus 1. |
verbose |
(Optional) Boolean to control whether or not to display text. Default is TRUE. |
hor |
(Optional) A single skyscapeR.horizon object created with |
refraction |
(Optional) Whether atmospheric refraction is to be taken into account.
If not given the value set by |
atm |
(Optional) Atmospheric pressure for refraction calculation.
If not given the value set by |
temp |
(Optional) Atmospheric temperature for refraction calculation.
If not given the value set by |
Silva, F (2020) A probabilistic framework and significance test for the analysis of structural orientations in skyscape archaeology Journal of Archaeological Science 118, 105138. <doi:10.1016/j.jas.2020.105138>
## Not run: # significance test for azimuth Az <- az.pdf(az=c(87,93,90,110), unc=3) st1 <- randomTest(Az, nsims=1000) plot(st1) # significance test for declination hor <- createHor(az=c(0,360), alt=c(0,0), loc=c(35,-8,25)) # flat horizon with 0 degrees of altitude Dec <- coordtrans(Az, hor) st2 <- randomTest(Dec, nsims=1000) plot(st2) ## End(Not run)## Not run: # significance test for azimuth Az <- az.pdf(az=c(87,93,90,110), unc=3) st1 <- randomTest(Az, nsims=1000) plot(st1) # significance test for declination hor <- createHor(az=c(0,360), alt=c(0,0), loc=c(35,-8,25)) # flat horizon with 0 degrees of altitude Dec <- coordtrans(Az, hor) st2 <- randomTest(Dec, nsims=1000) plot(st2) ## End(Not run)
This function calculates the true azimuth of a structure measured with a compass.
reduct.compass(loc, mag.az, date, magdec, alt, name, ID, HWT.ID)reduct.compass(loc, mag.az, date, magdec, alt, name, ID, HWT.ID)
loc |
Location, either a skyscapeR.object or a vector containing the latitude, longitude and elevation of location, in this order. |
mag.az |
Array of magnetic azimuth measurements. |
date |
(Optional) Date of measurements as a string in the format: 'YYYY/MM/DD'. Only necessary if magdec is not given. |
magdec |
(Optional) Magnetic declination, if known. |
alt |
(Optional) Altitude, necessary for automatic declination calculation. If missing and loc is a skyscapeR.horizon object then the altitude will be automatically read from the horizon profile. |
name |
(Optional) Names or labels to identify each measurement. |
ID |
(Optional) IDs or codes to identify each measurement. |
HWT.ID |
(Optional) HeyWhatsThat IDs relating to a previously generated horizon profile for measurement. |
loc <- c(35,-7, 100) mag.az <- c(89.5, 105, 109.5) data <- reduct.compass(loc, mag.az, "2016/04/02") # Declination will be automatically calculated if the altitude is also given: data <- reduct.compass(loc, mag.az, "2016/04/02", alt=c(1,2,0)) # Alternatively, the altitude can be automatically retrieved from a horizon profile: hor <- downloadHWT('HIFVTBGK') data <- reduct.compass(hor, mag.az, "2016/04/02")loc <- c(35,-7, 100) mag.az <- c(89.5, 105, 109.5) data <- reduct.compass(loc, mag.az, "2016/04/02") # Declination will be automatically calculated if the altitude is also given: data <- reduct.compass(loc, mag.az, "2016/04/02", alt=c(1,2,0)) # Alternatively, the altitude can be automatically retrieved from a horizon profile: hor <- downloadHWT('HIFVTBGK') data <- reduct.compass(hor, mag.az, "2016/04/02")
This function calculates the true azimuth of a structure measured with a theodolite using the sun-sight technique.
reduct.theodolite( loc, az, date, time, tz, az.sun = 0, limb, alt, name, ID, HWT.ID )reduct.theodolite( loc, az, date, time, tz, az.sun = 0, limb, alt, name, ID, HWT.ID )
loc |
Location, either a skyscapeR.object or a vector containing the latitude, longitude and elevation of location, in this order. |
az |
Array of azimuths. Use |
date |
Date of measurements as a string in the format: 'YYYY/MM/DD' |
time |
Time of sun-sight measurement in the format: 'HH:MM:SS' |
tz |
Timezone of input wither as a known acronym (e.g. "GMT", "CET") or a string with continent followed by country capital (e.g. "Europe/London"). |
az.sun |
(Optional) Measured azimuth of the sun. Defaults to zero. |
limb |
(Optional) Measured limb of the sun. Options are left, right. If missing the center of the sun will be used for calculations. |
alt |
(Optional) Altitude, necessary for automatic declination calculation. If missing and loc is a skyscapeR.horizon object then the altitude will be automatically read from the horizon profile. |
name |
(Optional) Names or labels to identify each measurement. |
ID |
(Optional) IDs or codes to identify each measurement. |
HWT.ID |
(Optional) HeyWhatsThat IDs relating to a previously generated horizon profile for measurement. |
Ruggles, C.L.N. (1999). Astronomy in Prehistoric Britain and Ireland. Yale University Press.
lat <- ten(35,50,37.8) lon <- ten(14,34,6.4) elev <- 100 az <- c( ten(298,24,10), ten(302,20,40)) az.sun <- ten(327,29,50) date <- "2016/02/20" time <- "11:07:17" data <- reduct.theodolite(c(lat,lon,elev), az, date , time, tz= "Europe/Malta", az.sun) # Declination will be automatically calculated if the altitude is also given: data <- reduct.theodolite(c(lat,lon,elev), az, date , time, tz= "Europe/Malta", az.sun, alt=c(2,5)) # Alternatively, the altitude can be automatically retrieved from a horizon profile: hor <- downloadHWT('HIFVTBGK') data <- reduct.theodolite(hor, az, date, time, tz= "Europe/Malta", az.sun)lat <- ten(35,50,37.8) lon <- ten(14,34,6.4) elev <- 100 az <- c( ten(298,24,10), ten(302,20,40)) az.sun <- ten(327,29,50) date <- "2016/02/20" time <- "11:07:17" data <- reduct.theodolite(c(lat,lon,elev), az, date , time, tz= "Europe/Malta", az.sun) # Declination will be automatically calculated if the altitude is also given: data <- reduct.theodolite(c(lat,lon,elev), az, date , time, tz= "Europe/Malta", az.sun, alt=c(2,5)) # Alternatively, the altitude can be automatically retrieved from a horizon profile: hor <- downloadHWT('HIFVTBGK') data <- reduct.theodolite(hor, az, date, time, tz= "Europe/Malta", az.sun)
Computes the rising and setting azimuth, declination and time of a Solar System object for a given location and day
riseset( obj = "sun", date, jd, alt = 0, loc, calendar, timezone, dec, refraction, atm, temp, verbose = T )riseset( obj = "sun", date, jd, alt = 0, loc, calendar, timezone, dec, refraction, atm, temp, verbose = T )
obj |
(Optional) String containing name of the solar system body of interest. Can be any of the planets (inc. Pluto), the Moon, the Sun or the Ecliptic. Defaults to 'sun'. |
date |
Either a string containing the date in the format "YYYY/MM/DD"
(see |
jd |
(Optional) A numeric containing the julian date (see |
alt |
(Optional) The altitude of the horizon to consider. Defaults to zero degrees. |
loc |
Location, either a skyscapeR.object or a vector containing the latitude, longitude and elevation of location, in this order. |
calendar |
(Optional) Calendar used in parameter date. G for gregorian and J for julian.
If not given the value set by |
timezone |
(Optional) Timezone for output of rising and setting time either as a known acronym
(e.g. "GMT", "CET") or a string with continent followed by country capital (e.g. "Europe/London"). See
timezones for details. If not given the value set by |
dec |
(Optional) Output declination: geo for the geocentric, or topo for the topocentric
frame of reference. If not given the value set by |
refraction |
(Optional) Whether atmospheric refraction is to be taken into account.
If not given the value set by |
atm |
(Optional) Atmospheric pressure for refraction calculation.
If not given the value set by |
temp |
(Optional) Atmospheric temperature for refraction calculation.
If not given the value set by |
verbose |
(Optional) Boolean to control whether or not to display text. Default is TRUE. |
# Rising and setting of the sun on june solstice 2018, from the location of London riseset('sun', '2018/06/21', loc=c(51.5, 0.11, 100)) # Rising ans setting of the moon on june solstice 2018, using a horizon profile hor <- downloadHWT('HIFVTBGK') # Liverpool cathedral riseset('moon', '2018/06/21', loc=hor) # Rising and setting of the sun throughout February 1999, from the location of London riseset('sun', '1999/02', loc=c(51.5, 0.11, 100)) ## Not run: # Rising and setting of the sun throughout 3001 BC, from the location of London riseset('sun', -3000, loc=c(51.5, 0.11, 100)) ## End(Not run)# Rising and setting of the sun on june solstice 2018, from the location of London riseset('sun', '2018/06/21', loc=c(51.5, 0.11, 100)) # Rising ans setting of the moon on june solstice 2018, using a horizon profile hor <- downloadHWT('HIFVTBGK') # Liverpool cathedral riseset('moon', '2018/06/21', loc=hor) # Rising and setting of the sun throughout February 1999, from the location of London riseset('sun', '1999/02', loc=c(51.5, 0.11, 100)) ## Not run: # Rising and setting of the sun throughout 3001 BC, from the location of London riseset('sun', -3000, loc=c(51.5, 0.11, 100)) ## End(Not run)
Data from C.L.N. Ruggles' fieldwork on the Stone Rows of Cork and Kerry.
data(RugglesCKR)data(RugglesCKR)
A data frame with 41 rows and 5 variables:
Site Ref
String indicating whether they are towards the NE or SW
Azimuth of hill towards which the Stone Rows are pointing
Altitude of hill towards which the Stone Rows are pointing
Declination of hill towards which the Stone Rows are pointing
Ruggles, C.L.N. (1999). Astronomy in Prehistoric Britain and Ireland. Yale University Press.
data(RugglesCKR) kde <- density(RugglesCKR$Dec.Hill, 2) plot(kde)data(RugglesCKR) kde <- density(RugglesCKR$Dec.Hill, 2) plot(kde)
Declination data from C.L.N. Ruggles' fieldwork on the Scottish Recumbent Stone Circles.
data(RugglesRSC)data(RugglesRSC)
A data frame with 37 rows and 2 variables:
Declination
Site ID
Ruggles, C.L.N. (1999). Astronomy in Prehistoric Britain and Ireland. Yale University Press.
data(RugglesRSC) kde <- density(RugglesRSC$Dec, 2) plot(kde)data(RugglesRSC) kde <- density(RugglesRSC$Dec, 2) plot(kde)
This function no longer works. Please use randomTest instead.
sigTest()sigTest()
This function creates an object containing all the necessary information to plot celestial objects/events unto the many plotting functions of skyscapeR package.
sky.objects(names, epoch, loc = FALSE, col = "red", lty = 1, lwd = 1)sky.objects(names, epoch, loc = FALSE, col = "red", lty = 1, lwd = 1)
names |
The name(s) of the celestial object(s) or event(s) of interest. These can be one of the following soli-lunar events: jS, dS, eq, nmnLX, nMjLX, smnLX, sMjLX, or the name of any star in the database. As shorthand, the names sun and moon can be used to represent all the above solar and lunar events, respectively. Alternatively, custom declination values can also be used. |
epoch |
The year or year range (as an array) one is interested in. |
loc |
(Optional) This can be either a vector with the latitude and longitude of the location, or a skyscapeR.horizon object. |
col |
(Optional) The color for plotting, and differentiating these objects. Defaults to red for all objects. |
lty |
(Optional) Line type (see |
lwd |
(Optional) Line width (see |
# Create a object with solar targets for epoch range 4000-2000 BC: tt <- sky.objects('solar extremes', c(-4000,-2000)) # Create an object with a few stars for same epoch: tt <- sky.objects(c('Sirius', 'Betelgeuse', 'Antares'), c(-4000,-2000), col=c('white', 'red', 'orange')) # Create an object with solstices and a custom declination value: tt <- sky.objects(c('December Solstice','June Solstice', -13), c(-4000,-2000))# Create a object with solar targets for epoch range 4000-2000 BC: tt <- sky.objects('solar extremes', c(-4000,-2000)) # Create an object with a few stars for same epoch: tt <- sky.objects(c('Sirius', 'Betelgeuse', 'Antares'), c(-4000,-2000), col=c('white', 'red', 'orange')) # Create an object with solstices and a custom declination value: tt <- sky.objects(c('December Solstice','June Solstice', -13), c(-4000,-2000))
Create a simplistic sketch of the sky at a given moment in time
sky.sketch( time, timezone, calendar, xrange = c(30, 150), yrange = c(-45, 45), sun = T, moon = T, planets = F, exagerate = T, max.mag = 6, loc, atm, temp )sky.sketch( time, timezone, calendar, xrange = c(30, 150), yrange = c(-45, 45), sun = T, moon = T, planets = F, exagerate = T, max.mag = 6, loc, atm, temp )
time |
Either a string containing the date and time in the format "YYYY-MM-DD HH:MM:SS"
(see |
timezone |
(Optional) Timezone of input either as a known acronym (e.g. "GMT", "CET") or
a string with continent followed by country capital (e.g. "Europe/London"). See
timezones for details. Only needed if time is a string. If not given the value set
by |
calendar |
(Optional) Calendar used in parameter time. G for gregorian and J for julian.
Only needed if time is a string. If not given the value set by |
xrange |
Range of azimuths to display, preferably no larger than 120 degrees. |
yrange |
Range of altitudes to display, preferably no larger than 120 degrees. |
sun |
(Optional) Boolean on whether the sun should be displayed. Defaults to TRUE. |
moon |
(Optional) Boolean on whether the moon should be displayed. Defaults to TRUE. |
planets |
(Optional) Boolean on whether the visible planets should be displayed. Defaults to FALSE. |
exagerate |
(Optional) Boolean on whether the size of the sun, moon and planets should be exaggerated, which can be useful when attempting wider viewing angles. Defaults to TRUE. |
max.mag |
(Optional) Maximum magnitude of stars to consider. Default is 6. |
loc |
Location, either a skyscapeR.object or a vector containing the latitude and longitude of location, in this order. |
atm |
(Optional) Atmospheric pressure for refraction calculation.
If not given the value set by |
temp |
(Optional) Atmospheric temperature for refraction calculation.
If not given the value set by |
sky.sketch(time='2019/01/10 18:51', loc=c(35,-8,100))sky.sketch(time='2019/01/10 18:51', loc=c(35,-8,100))
See and change the global variables used by skyscapeR
skyscapeR.vars(timezone, calendar, refraction, atm, temp, dec)skyscapeR.vars(timezone, calendar, refraction, atm, temp, dec)
timezone |
Timezone of input either as a known acronym (e.g. "GMT", "CET") or
a string with continent followed by country capital (e.g. "Europe/London"). See
|
calendar |
Calendar used in parameter time. G for gregorian and J for julian. Defaults to Gregorian. |
refraction |
Whether atmospheric refraction is to be taken into account. Default is TRUE. |
atm |
Atmospheric pressure for refraction calculation. Default is 1013.25 mbar. |
temp |
Atmospheric temperature for refraction calculation. Default is 15 degrees. |
dec |
Output declination: geo for the geocentric, or topo for the topocentric frame of reference. Defaults to topocentric. |
This function calculates the declination of the southern major Lunar Extreme for a given year, based upon obliquity estimation and corrected average parallax.
sMjLX( year = skyscapeR.env$cur.year, loc = FALSE, parallax = 0.952, altitude = 0, verbose = TRUE )sMjLX( year = skyscapeR.env$cur.year, loc = FALSE, parallax = 0.952, altitude = 0, verbose = TRUE )
year |
Year for which to calculate the declination. Defaults to present year as given by Sys.Date. |
loc |
(Optional) This can be either the latitude of the location, or a skyscapeR.horizon object. If missing or FALSE, function will output geocentric declination. |
parallax |
(Optional) Average parallax value for the moon Defaults to 0.952. |
altitude |
(Optional) Altitude of the sun. Defaults to 0 degrees. |
verbose |
(Optional) Boolean to control output of warnings and messages. Defaults to TRUE. |
nmnLX, smnLX, nMjLX,
parallax.corr
# Southern major Lunar Extreme geocentric declination for year 2501 BC: sMjLX(-2500) # Topocentric declination for same year and latitude of 50 degrees N: sMjLX(-2500, loc=50)# Southern major Lunar Extreme geocentric declination for year 2501 BC: sMjLX(-2500) # Topocentric declination for same year and latitude of 50 degrees N: sMjLX(-2500, loc=50)
This function calculates the declination of the southern minor Lunar Extreme for a given year, based upon obliquity estimation and corrected average parallax.
smnLX( year = skyscapeR.env$cur.year, loc = FALSE, parallax = 0.952, altitude = 0, verbose = TRUE )smnLX( year = skyscapeR.env$cur.year, loc = FALSE, parallax = 0.952, altitude = 0, verbose = TRUE )
year |
Year for which to calculate the declination. Defaults to present year as given by Sys.Date. |
loc |
(Optional) This can be either the latitude of the location, or a skyscapeR.horizon object. If missing or FALSE, function will output geocentric declination. |
parallax |
(Optional) Average parallax value for the moon Defaults to 0.952. |
altitude |
(Optional) Altitude of the sun. Defaults to 0 degrees. |
verbose |
(Optional) Boolean to control output of warnings and messages. Defaults to TRUE. |
nmnLX, nMjLX, sMjLX,
parallax.corr
# Southern minor Lunar Extreme geocentric declination for year 2501 BC: smnLX(-2500) # Topocentric declination for same year and latitude of 50 degrees N: smnLX(-2500, loc=50)# Southern minor Lunar Extreme geocentric declination for year 2501 BC: smnLX(-2500) # Topocentric declination for same year and latitude of 50 degrees N: smnLX(-2500, loc=50)
Returns the calendar date when the sun has the same declination as the input declination.
solar.date(dec, year, calendar, verbose = T)solar.date(dec, year, calendar, verbose = T)
dec |
Single value or array of declination values. |
year |
Year for which to do calculations. |
calendar |
(Optional) Calendar used for output. G for gregorian and J for julian. Defaults to Gregorian. |
verbose |
(Optional) Boolean to control whether or not to display text. Default is TRUE. |
solar.date(-23, 2018) solar.date(-12, 1200, calendar='G') solar.date(-12, 1200, calendar='J') solar.date(14, -2000)solar.date(-23, 2018) solar.date(-12, 1200, calendar='G') solar.date(-12, 1200, calendar='J') solar.date(14, -2000)
Azimuth and declination of the spatial equinox for a given location
spatial.equinox(hor, parallax = 0.00224)spatial.equinox(hor, parallax = 0.00224)
hor |
This should be a skyscapeR.horizon object. |
parallax |
(Optional) Average parallax value for the sun. Defaults to 0.00224. |
jS, dS, eq,
zenith, antizenith, parallax.corr
## Not run: hor <- createHWT(34.174051531543405, 110.81299818694872, name='Xipo, Lingbao') spatial.equinox(hor) ## End(Not run)## Not run: hor <- createHWT(34.174051531543405, 110.81299818694872, name='Xipo, Lingbao') spatial.equinox(hor) ## End(Not run)
Summed probability density (SPD)
spd(pdf, normalise = F, xrange, .cutoff = 1e-05, .res = 0.01)spd(pdf, normalise = F, xrange, .cutoff = 1e-05, .res = 0.01)
pdf |
A skyscapeR.pdf object created with either |
normalise |
(Optional) Boolean to control whether to normalize the SPD. Default is FALSE |
xrange |
(Optional) Array of values (min and max) for SPD if different from range of pdf. If given, it overrides .cutoff |
.cutoff |
(Optional) Value of SPD at which point it will be cutoff to save on memory. Default is 1e-5 |
.res |
(Optional) Resolution with which to output SPD. Default is 0.01 degrees. |
Silva, F (2020) A probabilistic framework and significance test for the analysis of structural orientations in skyscape archaeology Journal of Archaeological Science 118, 105138. <doi:10.1016/j.jas.2020.105138>
# SPD of azimuths Az <- az.pdf(az=c(87,93,90,110), unc=3) s1 <- spd(Az) plot(s1) # SPD of declinations hor <- createHor(az=c(0,360), alt=c(0,0), loc=c(35,-8,25)) # flat horizon with 0 degrees of altitude Dec <- coordtrans(Az, hor) s2 <- spd(Dec) plot(s2)# SPD of azimuths Az <- az.pdf(az=c(87,93,90,110), unc=3) s1 <- spd(Az) plot(s1) # SPD of declinations hor <- createHor(az=c(0,360), alt=c(0,0), loc=c(35,-8,25)) # flat horizon with 0 degrees of altitude Dec <- coordtrans(Az, hor) s2 <- spd(Dec) plot(s2)
This function retrieves information for a given star and saves it in the skyscapeR.star format ready to be used by other skyscapeR package function.
star(string, year = skyscapeR.env$cur.year)star(string, year = skyscapeR.env$cur.year)
string |
This can be either the traditional name for the star or its Bayer designation. |
year |
Year for which to calculate the coordinates. Defaults to current year. |
swe_fixstar2_ut, swe_fixstar2_mag
# Retrieve data for Aldebaran: Aldeb <- star('Aldebaran') # Retrieve data for Aldebaran on 2999 BC: ss <- star('Aldebaran', -3000)# Retrieve data for Aldebaran: Aldeb <- star('Aldebaran') # Retrieve data for Aldebaran on 2999 BC: ss <- star('Aldebaran', -3000)
Celestial object names (stars, supernovae and galaxies) database. Currently only IAU / Western common names included, but can be expanded to include names from other societies, past or present.
data(star.names)data(star.names)
A data frame with 300 rows and 2 variables:
Object identifier used for ephemeris
Western (IAU / common) name for the object
This function calculates the seasons (Rising, Setting, etc.) and phase types (Arising and Lying Hidden, Curtailed Passage) of a star for a given location and epoch. This functions uses the arcus visionis approximation of Purrington (1988) and the atmospheric extinction approximation of Schaefer (1989). For the nomenclature used, and description of star phase types, see Brady (2015).
star.phases( star, year, loc, alt.hor = 0, k = 0.2, limit = 6, alt.rs = 10, res = 1/24/6, refraction, atm, temp )star.phases( star, year, loc, alt.hor = 0, k = 0.2, limit = 6, alt.rs = 10, res = 1/24/6, refraction, atm, temp )
star |
Either the star name or a skyscapeR.star object. |
year |
The year of interest. |
loc |
Location, either a skyscapeR.object or a vector containing the latitude and longitude of location, in this order. |
alt.hor |
(Optional) The altitude of the horizon to consider. Defaults to zero degrees. |
k |
(Optional) Extinction coefficient (see Schaefer 1989). Defaults to 0.2, corresponding to a poor night on mountain top or best night at a dry sea level site. |
limit |
(Optional) The maximum magnitude of a star that can be visible with the naked eye. Defaults to 6. |
alt.rs |
(Optional) The maximum altitude of a star's first or last visibility for it to still be considered to be as rising or setting. Defaults to ten degrees. |
res |
(Optional) Resolution of calculation. The smaller this figure the slower the computation. Defaults to 1/24/6, i.e. every 10 minutes. |
refraction |
(Optional) Whether atmospheric refraction is to be taken into account.
If not given the value set by |
atm |
(Optional) Atmospheric pressure for refraction calculation.
If not given the value set by |
temp |
(Optional) Atmospheric temperature for refraction calculation.
If not given the value set by |
Purrington, Robert D. (1988) Heliacal Rising and Setting: Quantitative Aspects, Journal for the History of Astronomy (Archaeoastronomy Supplement 12) 19, S72-S84. Available online at [SAO/NASA ADS Astronomy Abstract Service](http://adsabs.harvard.edu/abs/1988JHAS...19...72P)
Brady, Bernadette (2015) Star Phases: the Naked-eye Astronomy of the Old Kingdom Pyramid Texts. In F Silva and N Campion (eds) Skyscapes: The Role and Importance of the Sky in Archaeology. Oxford: Oxbow Books, pp. 76-86.
ss1 <- star.phases('Aldebaran',-4000, c(35,-8,200)) # One can then look at the star's phase type: ss1$metadata$type # Date range of seasons: ss1$metadata$seasons # Date range of phase-type events: ss1$metadata$events # And plot them: plot(ss1) # You can play with the parameters and see how predictions change: ss1 <- star.phases('Aldebaran',-4000, c(35,-8,200), alt.hor=2, alt.rs=5) plot(ss1)ss1 <- star.phases('Aldebaran',-4000, c(35,-8,200)) # One can then look at the star's phase type: ss1$metadata$type # Date range of seasons: ss1$metadata$seasons # Date range of phase-type events: ss1$metadata$events # And plot them: plot(ss1) # You can play with the parameters and see how predictions change: ss1 <- star.phases('Aldebaran',-4000, c(35,-8,200), alt.hor=2, alt.rs=5) plot(ss1)
This function returns the azimuth of the sun at a given time and location,
useful for data reduction of theodolite measurements using the sun-sight
technique (reduct.theodolite).
sunAz(loc, time, timezone, limb, alt = F)sunAz(loc, time, timezone, limb, alt = F)
loc |
Location, either a skyscapeR.object or a vector containing the latitude, longitude and elevation of location, in this order. |
time |
String containing the date and time in the following format: "YYYY-MM-DD HH:MM:SS" |
timezone |
Timezone of input either as a known acronym (e.g. "GMT", "CET") or a string with continent followed by country capital (e.g. "Europe/London"). |
limb |
(Optional) Measured limb of the sun. Options are left, right. If missing the center of the sun will be output. |
alt |
(Optional) Boolean that triggers output of altitude of the sun at exact time. Default is FALSE. |
sunAz(c(52,-3,100), '2017-10-04 12:32:14', 'Europe/London')sunAz(c(52,-3,100), '2017-10-04 12:32:14', 'Europe/London')
Swap between swephR and skyscapeR versions of stellar ephemeris
swapStars(source = "skyscapeR")swapStars(source = "skyscapeR")
source |
Package name for the source of the stellar ephemeris data. Can be either swephR or skyscapeR. Defaults to the latter. |
Converts degree measurements in deg-min-sec (º ' ") format into decimal-point degree format.
ten(dd, mm = 0, ss = 0)ten(dd, mm = 0, ss = 0)
dd |
Degree |
mm |
(Optional) Arcminutes |
ss |
(Optional) Arcseconds |
deg <- ten(24, 52, 16)deg <- ten(24, 52, 16)
Converts date and time (in any timezone) to Julian date
time2jd(time, timezone, calendar, verbose = F)time2jd(time, timezone, calendar, verbose = F)
time |
String containing the date and time in the format "YYYY/MM/DD HH:MM:SS". BCE dates
should use negative sign. Use |
timezone |
(Optional) Timezone of input either as a known acronym (e.g. "GMT", "CET") or
a string with continent followed by country capital (e.g. "Europe/London"). See
|
calendar |
(Optional) Calendar used in parameter time. G for gregorian and J for julian. Defaults to Gregorian. |
verbose |
(Optional) Controls whether messages should be displayed. Default is FALSE. |
swe_julday, as.POSIXlt, timezones,
timestring
# Julian date at noon GMT on Christmas day 2018 time2jd('2018/12/25 12:00:00', 'GMT')# Julian date at noon GMT on Christmas day 2018 time2jd('2018/12/25 12:00:00', 'GMT')
Converts date and time numeric values to a single string
timestring(year, month, day, hour = 12, minute = 0, second = 0)timestring(year, month, day, hour = 12, minute = 0, second = 0)
year |
Year |
month |
Month |
day |
Day |
hour |
Hour |
minute |
Minute |
second |
Second |
timestring(2018, 12, 25, 2, 34)timestring(2018, 12, 25, 2, 34)
This function returns the declination of the sun when it is at the zenith for a given location with corrected average parallax. If this phenomena does not occur at given location (i.e. if location is outside the tropical band) the function returns a NULL value.
zenith(loc, parallax = 0.00224, altitude = 0)zenith(loc, parallax = 0.00224, altitude = 0)
loc |
This can be either the latitude of the location, or a skyscapeR.horizon object. |
parallax |
(Optional) Average parallax value for the sun. Defaults to 0.00224. |
altitude |
(Optional) Altitude of the sun. Defaults to 0 degrees. |
jS, dS, eq,
antizenith, spatial.equinox, parallax.corr
# Zenith sun declination for Mexico City: zenith(19.419) # There is no zenith sun phenomenon in London: zenith(51.507)# Zenith sun declination for Mexico City: zenith(19.419) # There is no zenith sun phenomenon in London: zenith(51.507)