add moon calculations (#4)

* add `getSunPosition` method

* add `getMoonPosition` method

* add `getMoonIllumination` method

* update docs

.github/workflows/CI.yaml

@@ -6,7 +6,7 @@ on:
   push:
     branches:
       - main
-      - dev
+    tags: ['*']
 jobs:
   test:
     name: Julia ${{ matrix.version }} - ${{ matrix.os }} - ${{ matrix.arch }} - ${{ github.event_name }}
@@ -34,4 +34,21 @@ jobs:
       - uses: julia-actions/julia-processcoverage@v1
       - uses: codecov/codecov-action@v3
         with:
-          token: ${{ secrets.CODECOV_TOKEN }}
+          token: ${{ secrets.CODECOV_TOKEN }}
+  docs:
+    name: Documentation
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      statuses: write
+    steps:
+      - uses: actions/checkout@v3
+      - uses: julia-actions/setup-julia@v1
+        with:
+          version: '1'
+      - name: Install dependencies
+        run: julia --project=docs/ -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate()'
+      - name: Build and deploy
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: julia --project=docs/ docs/make.jl

Project.toml

@@ -1,7 +1,7 @@
 name = "SunCalc"
 uuid = "46d852a4-2fba-44bf-a445-ee38df28a2fc"
 authors = ["Georg Rüppel <g-rppl@posteo.de>"]
-version = "1.1.0"
+version = "1.2.0"
 
 [deps]
 DataFrames = "a93c6f00-e57d-5684-b7b6-d8193f3e46c0"

README.md

@@ -9,8 +9,9 @@
 
 ## About 
 
-Julia implementation of the [SunCalc](https://github.com/mourner/suncalc/) package for calculating sun position and sunlight phases 
-(times for sunrise, sunset, dusk, etc.) for the given location and time.
+Julia implementation of the [SunCalc](https://github.com/mourner/suncalc/) package for 
+calculating sun position, sunlight phases (times for sunrise, sunset, dusk, etc.), 
+moon position, and lunar phase for the given location and time for the given location and time.
 
 Most calculations are based on the formulas given in the Astronomy Answers articles
 about [position of the sun](https://www.aa.quae.nl/en/reken/zonpositie.html)
@@ -20,7 +21,10 @@ in the [Twilight article on Wikipedia](https://en.wikipedia.org/wiki/Twilight).
 
 ## Installation
 
+The package is registered in the [General registry](https://github.com/JuliaRegistries/General) 
+and can therefore be installed with:
+
 ```julia
 using Pkg
 pkg.add("SunCalc")
-```
+```

docs/src/functions.md

@@ -6,4 +6,14 @@ SunCalc.getSunPosition
 ## Sun light times
 ```@docs
 SunCalc.getSunlightTimes
+```
+
+## Moon position
+```@docs
+SunCalc.getMoonPosition
+```
+
+## Moon illumination
+```@docs
+SunCalc.getMoonIllumination
 ```

docs/src/index.md

@@ -1,7 +1,8 @@
 ## About
 
-Julia implementation of the [SunCalc](https://github.com/mourner/suncalc/) package for calculating sun position and sunlight phases 
-(times for sunrise, sunset, dusk, etc.) for the given location and time.
+Julia implementation of the [SunCalc](https://github.com/mourner/suncalc/) package for 
+calculating sun position, sunlight phases (times for sunrise, sunset, dusk, etc.), 
+moon position, and lunar phase for the given location and time for the given location and time.
 
 Most calculations are based on the formulas given in the Astronomy Answers articles
 about [position of the sun](https://www.aa.quae.nl/en/reken/zonpositie.html)
@@ -11,6 +12,9 @@ in the [Twilight article on Wikipedia](https://en.wikipedia.org/wiki/Twilight).
 
 ## Installation
 
+The package is registered in the [General registry](https://github.com/JuliaRegistries/General)
+and can therefore be installed with:
+
 ```julia
 using Pkg
 pkg.add("SunCalc")

src/SunCalc.jl

@@ -4,11 +4,14 @@ using Dates
 using TimeZones
 using DataFrames
 
-export getSunlightTimes, getSunPosition
+export getSunPosition, getSunlightTimes
+export getMoonPosition, getMoonIllumination
 
 include("utilis.jl")
 
-include("sunlightTimes.jl")
 include("sunPosition.jl")
+include("sunlightTimes.jl")
+include("moonPosition.jl")
+include("moonIllumination.jl")
 
-end  # module
+end

src/moonIllumination.jl

@@ -0,0 +1,72 @@
+
+"""
+    getMoonIllumination(
+        time::Union{Date,DateTime,ZonedDateTime};
+        keep=[:fraction, :phase, :angle])
+
+Calculate moon illumination for the given time. Return a `NamedTuple` or `DataFrame`.
+
+Available variables:
+
+| Variable   | Description                                                                                                                                                                           |
+| :--------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `fraction` | Illuminated fraction of the moon; varies from 0.0 (new moon) to 1.0 (full moon)                                                                                                       |
+| `phase`    | Moon phase; varies from 0.0 to 1.0, described below                                                                                                                                   |
+| `angle`    | Midpoint angle in radians of the illuminated limb of the moon reckoned eastward from the north point of the disk; the moon is waxing if the angle is negative, and waning if positive |                                          |
+
+Moon phase value should be interpreted like this:
+
+- `0`: New Moon
+- *Waxing Crescent*
+- `0.25`: First Quarter
+- *Waxing Gibbous*
+- `0.5`: Full Moon
+- *Waning Gibbous*
+- `0.75`: Last Quarter
+- *Waning Crescent*
+
+# Examples
+```julia
+using Dates, SunCalc
+getMoonIllumination(Date(2000, 07, 01))
+
+getMoonIllumination(now(), keep=[:fraction])
+```
+"""
+function getMoonIllumination(
+    time::Union{Date,DateTime,ZonedDateTime};
+    keep=[:fraction, :phase, :angle])
+
+    available_var = [:fraction, :phase, :angle]
+
+    @assert all(keep .∈ [available_var]) "
+    $(keep[Not(keep .∈ [available_var])]) is not a valid variable."
+
+    if isa(time, ZonedDateTime)
+        time = DateTime(time, UTC)
+    end
+
+    data = moonIllumination(DateTime(time))
+
+    return data[keep]
+end
+
+function getMoonIllumination(
+    time::Union{Vector{Date},Vector{DateTime},Vector{ZonedDateTime}};
+    keep=[:fraction, :phase, :angle])
+
+    available_var = [:fraction, :phase, :angle]
+
+    @assert all(keep .∈ [available_var]) "
+    $(keep[Not(keep .∈ [available_var])]) is not a valid variable."
+
+    time = map(x -> isa(x, ZonedDateTime) ? DateTime(x, UTC) : x, time)
+
+    data = DataFrame(time=time)
+
+    ill = DataFrame(moonIllumination.(DateTime.(data.time)))
+
+    data = hcat(data, ill[:, keep])
+
+    return data
+end

src/moonPosition.jl

@@ -0,0 +1,70 @@
+
+"""
+    getMoonPosition(
+        time::Union{DateTime,ZonedDateTime},
+        lat::Real,
+        lon::Real;
+        keep=[:altitude, :azimuth, :distance, :parallacticAngle])
+
+Calculate the sun position for the given time and location. Return a `NamedTuple`
+    or `DataFrame`.
+
+Available variables:
+
+| Variable           | Description                                |
+| :----------------- | :----------------------------------------- |
+| `altitude`         | Moon altitude above the horizon in radians |
+| `azimuth`          | Moon azimuth in radians                    |
+| `distance`         | Distance to moon in kilometres             |
+| `parallacticAngle` | Parallactic angle of the moon in radians   |
+
+
+# Examples 
+```julia	
+using Dates, SunCalc
+getMoonPosition(DateTime(2000, 07, 01, 12, 00, 00), 54, 9)
+
+getMoonPosition(now(), 54, 9; keep=[:altitude])
+```
+"""
+function getMoonPosition(
+    time::Union{DateTime,ZonedDateTime},
+    lat::Real,
+    lon::Real;
+    keep=[:altitude, :azimuth, :distance, :parallacticAngle])
+
+  available_var  = [:altitude, :azimuth, :distance, :parallacticAngle]
+
+  @assert all(keep .∈ [available_var]) "
+  $(keep[Not(keep .∈ [available_var])]) is not a valid variable."
+
+  if isa(time, ZonedDateTime)
+      time = DateTime(time, UTC)
+  end
+
+  data = moonPosition(time, lat, lon)
+
+  return data[keep]
+end
+
+function getMoonPosition(
+    time::Union{Vector{DateTime},Vector{ZonedDateTime}},
+    lat::Real,
+    lon::Real;
+    keep=[:altitude, :azimuth, :distance, :parallacticAngle])
+
+    available_var = [:altitude, :azimuth, :distance, :parallacticAngle]
+
+    @assert all(keep .∈ [available_var]) "
+    $(keep[Not(keep .∈ [available_var])]) is not a valid variable."
+
+    time = map(x -> isa(x, ZonedDateTime) ? DateTime(x, UTC) : x, time)
+
+    data = DataFrame(time=time, lat=lat, lon=lon)
+
+    pos = DataFrame(moonPosition.(data.time, data.lat, data.lon))
+
+    data = hcat(data, pos[:, keep])
+
+    return data
+end

src/sunPosition.jl

@@ -11,19 +11,23 @@ Calculate the sun position for the given time and location. Return a `NamedTuple
     
 Available variables:
 
-| Variable  | Description                                                                                                                 |
-| :-------- | :-------------------------------------------------------------------------------------------------------------------------- |
-|`altitude` | sun altitude above the horizon in radians, e.g. 0 at the horizon and π/2 at the zenith (straight over your head).           |
-|`azimuth`  | sun azimuth in radians (direction along the horizon, measured from south to west), e.g. 0 is south and π * 3/4 is northwest.|
+| Variable   | Description                                                                                                                 |
+| :--------- | :-------------------------------------------------------------------------------------------------------------------------- |
+| `altitude` | Sun altitude above the horizon in radians, e.g. 0 at the horizon and π/2 at the zenith (straight over your head)            |
+| `azimuth`  | Sun azimuth in radians (direction along the horizon, measured from south to west), e.g. 0 is south and π * 3/4 is northwest |
 
 # Examples
-```jldoctest
-julia> using Dates, SunCalc
-julia> getSunPosition(DateTime(2000, 07, 01, 12, 00, 00), 54, 9.0)
-(altitude = 1.021444013872015, azimuth = 0.23904867335099955)
+```julia
+using Dates, SunCalc
+getSunPosition(DateTime(2000, 07, 01, 12, 00, 00), 54, 9)
+
+getSunPosition(now(), 54, 9; keep=[:altitude])
 ```	
 """
-function getSunPosition(time::Union{DateTime,ZonedDateTime}, lat::Real, lon::Real;
+function getSunPosition(
+    time::Union{DateTime,ZonedDateTime},
+    lat::Real,
+    lon::Real;
     keep=[:altitude, :azimuth])
 
     available_var = [:altitude, :azimuth]
@@ -35,13 +39,16 @@ function getSunPosition(time::Union{DateTime,ZonedDateTime}, lat::Real, lon::Rea
         time = DateTime(time, UTC)
     end
 
-    data = getPosition(time, lat, lon)
+    data = sunPosition(time, lat, lon)
 
     return data[keep]
 end
 
-function getSunPosition(time::Union{Vector{DateTime},Vector{ZonedDateTime}},
-    lat::Real, lon::Real; keep=[:altitude, :azimuth])
+function getSunPosition(
+    time::Union{Vector{DateTime},Vector{ZonedDateTime}},
+    lat::Real,
+    lon::Real;
+    keep=[:altitude, :azimuth])
 
     available_var = [:altitude, :azimuth]
 
@@ -52,7 +59,7 @@ function getSunPosition(time::Union{Vector{DateTime},Vector{ZonedDateTime}},
 
     data = DataFrame(time=time, lat=lat, lon=lon)
 
-    pos = DataFrame(getPosition.(data.time, data.lat, data.lon))
+    pos = DataFrame(sunPosition.(data.time, data.lat, data.lon))
 
     data = hcat(data, pos[:, keep])