grammar and structure (#6)

docs/src/index.md

@@ -4,43 +4,43 @@ CurrentModule = RateTables
 
 # RateTables
 
-The [RateTables.jl](https://github.com/JuliaSurv/RateTables.jl) Julia package provides daily rate table objects from census datasets targeted at person-year computations, alike [R's `ratetable` class](https://www.rdocumentation.org/packages/survival/versions/3.2-3/topics/ratetable). 
+The [RateTables.jl](https://github.com/JuliaSurv/RateTables.jl) Julia package provides daily rate table objects extracted from census datasets, tailored for person-year computations. This functionality is similar to [R's `ratetable` class](https://www.rdocumentation.org/packages/survival/versions/3.2-3/topics/ratetable). 
 
-You can install it through: 
+You can install it using the command below: 
 
 ```julia
 using Pkg
 Pkg.add("https://github.com/JuliaSurv/RateTables.jl")
 ```
 
-Loading this package exports a few constant `RateTable` objects. See the bottom of this page for the available rate tables. For the sake of the example, we'll use the `hmd_rates` dictionary, which stores rates tables extracted from the [Human Mortality Database (HMD)](https://mortality.org).
+Loading this package exports constant `RateTable` objects. The index refering to all the available rate tables can be found at the bottom of this page. For the sake of this example, we'll use the `hmd_rates` dictionary which stores rates tables extracted from the [Human Mortality Database (HMD)](https://mortality.org).
 
 ```@example 1
 using RateTables
 hmd_rates
 ```
 
-The output of the REPL show that we have a `RateTable` object with two covariates `:country` and `:sex`. You can query the availiable covariates of a given RateTable: 
+The output of the REPL shows that we have a `RateTable` object with two covariates `:country` and `:sex`. You can query the available covariates of a given RateTable as such: 
 
 ```@example 1
 availlable_covariates(hmd_rates, :sex)
 ```
 
-For this specific dataset, the number of countries is huge and calling `availlable_covariates(hmd_rates, :country)` wont be very usefull. For convenience, we provided details on the country codes separately in an other constant object `hmd_countries`:
+For this specific dataset, the number of countries is huge and calling `availlable_covariates(hmd_rates, :country)` won't be very useful. Thus, for convenience, we provided details on the country codes separately in another constant object called `hmd_countries`:
 
 ```@example 1
 hmd_countries
 ```
 
-Recall that a daily hazard rate of mortality is defined as $-\log(1 - q_x)/365.241$ for an annual death rate $q_x$. This is an alternative form of presenting mortality tables that is particularly convenient for person-year computations. To obtain daily rates from the tables, you have to use the `daily_hazard` function. It needs to be called with arguments in a specific format: 
+Recall that the daily hazard rate of mortality is defined as $-\log(1 - q_x)/365.241$ for an annual death rate $q_x$. We present an alternative approach to displaying mortality tables that is particularly convenient for person-year computations. To obtain daily rates from the tables, you can use the `daily_hazard` function. Its arguments need to be in the following specific format: 
 
-- The `age` needs to be given in days, and the converting factor is 1 year = 365.241 days.
-- The `date` also needs to be given in days, same converting factor. 
-- Other covariates formats vary from rate tables to rate tables, but their order matters.
+- The `age` parameter should be provided in days, with the conversion factor being 1 year = 365.241 days.
+- The `date` parameter should be provided in days as well, with the same conversion factor. 
+- The format of other covariates may vary between rate tables, but it's essential to consider that their order is significant.
 
-Usually, the `sex` covariates has values `:male`, `:female`, sometimes `:total`. For `hmd_rates`, we already saw that there was two additional covariates: `country` and `sex`. 
+The `sex` covariate typically has values such as `:male` and `:female`, and sometimes `:total`. For the `hmd_rates` table, we have previously observed two additional covariates: `country` and `sex`. 
 
-Depending on the querying syntax, the order of the passed argument can matter. For example, the daily hazard rate for a slovene male, on its 20th birthday the first of january 2010 can be queried with one of the following syntaxes:  
+Depending on the querying syntax, the order of the passed arguments can be significant. For instance, the daily hazard rate for a Slovene male, on his 20th birthday, which happens to fall on the first of january 2010, can be queried using one of the following syntaxes:  
 
 ```@example 1
 c = :svn # slovenia. 
@@ -49,20 +49,21 @@ d = 2010*365.241
 s = :male
 v1 = daily_hazard(hmd_rates, a, d, c, s)
 v2 = daily_hazard(hmd_rates, a, d; country=c, sex=s)
-v3 = daily_hazard(hmd_rates, a, d; sex=s, country=c) # when using kwargs syntax, order of additional covariates does not matter. 
-v4 = daily_hazard(hmd_rates[c, s], a, d) # here the order of arguments (c,s) also matter. 
-(v1,v2,v3, v4)
+v3 = daily_hazard(hmd_rates, a, d; sex=s, country=c) # when using kwargs syntax, the order of additional covariates does not matter. 
+v4 = daily_hazard(hmd_rates[c, s], a, d) # here, the order of the arguments (c,s) matters. 
+(v1,v2,v3,v4)
 ```
 
-For completeness, this package also include datasets commonly used in R for census datas, in particular the `relsurv::slopop` dataset for slovenia: 
+For completeness, this package also includes datasets commonly used in R for census data, particularly, the `relsurv::slopop` dataset pertaining to Slovenia: 
 
 ```@example 1
 daily_hazard(slopop, a, d; sex=s)
 ```
 
-Note the discrepency with HMD data. 
+Note the discrepency with the HMD data. 
+
+Another example with additional covariates would be the `survival::survexp.usr` dataset which includes `race` as a covariate. In this case, the calling structure remains similar: 
 
-Another example with additional covariates is the `survival::survexp.usr` dataset that includes a race covariate from us census data. In this case, the calling structure is very similar: 
 ```@example 1
 r = :white
 v1 = daily_hazard(survexp_usr, a, d, s, r)
@@ -72,9 +73,9 @@ v4 = daily_hazard(survexp_usr[s, r], a, d)
 (v1,v2,v3,v4)
 ```
 
-Note that fetching these daily hazard is a very sensitive operation that should be as fast as possible since it is usually used in the middle of very-hot loops. Therefore, we take care of the performance of our fetching algorithms.
+Please note that retrieving these daily hazards is a highly sensitive operation that should be optimized for speed, especially considering it's often used within critical loops. As such, we prioritize the performance of our fetching algorithms.
 
-Check out the following index for a list of availiable ratetables:
+For a list of the available rate tables, kindly refer to the following index:
 
 ```@index
 ```