To see if the program is operationnal, just type:
php run-observe.phpIf a message starting with
INVALID CALL: run-observe.php needs at least two arguments Usage: php run-observe.php <study> <commmand> [args] or: php run-observe.php prepare planetsis displayed, the program is ready to work.
Except for command prepare, the first parameter is always the slug of the study, the second is the name of the command, and some commands need supplementary arguments.
Generate planet database
The first step, when working on studies containing dates without time, is to build the sqlite database with planetary coordinates, for example:php run-observe.php prepare planets 1800-2040This generates a sqlite database located in a file specified in
config.yml, in section one-day-ephemeris, key sqlite-planets.
Work on a study
The complete list of steps to go from original data to distributions and html pages is listed on page Studies.In terms of commands, using the example of Deaths in France 1970 - 2025, this gives:
php run-observe.php death-fr init php run-observe.php death-fr import php run-observe.php death-fr observed php run-observe.php death-fr control php run-observe.php death-fr expected php run-observe.php death-fr stats php run-observe.php death-fr dim2 php run-observe.php death-fr output img all php run-observe.php death-fr output csv all php run-observe.php death-fr output page allDepending on the size of the dataset, some steps can be long to execute, in particular
import, control and dim2.
For example, on an old machine (2014) with Intel Core i7, 2.30GHz × 4:
| step | time (hours) |
|---|---|
| import | 04:15 |
| control | 04:30 per control |
| dim2 | 01:57 |
init
Depending on the study, this step can be ignored. It was useful for the Deaths in France study (to initialize an intermediate sqlite database), but useless for the Births in France in 2000 study.import
This step converts the raw dataset to a normalized file,data.csv.bz2, which is used by following steps.
It can be avoided if a file
data.csv.bz2 is built by a human or another program, and copied at the root of the study's working directory.
But it must respect the format of
data.csv.bz2: this file must contain only dates, the order of the dates must correspond to the order of the entry dates defined in the study config file, and the csv separator must be ";".
control
To save up space, the dates randomly generated during this step are not saved on disk, the program only stores the resulting distributions.This step can't be generic (common to all studies) because when a random row is computed, some tests depending on the data must be done. For example, test that birth is anterior to death, or that the wedding date is posterior to mother and father birth.
output
The program handles the generation of the html pages of the studies, but not the home page (like observe.tig12.net/output/index.html) and the css. That's a lack that sould be fixed.Adding a new study
If a new study can be handled by existing code, it can be handled by the program without coding anything, adding a new configuration file and providing adata.csv.bz2 file will be enough.
At this draft stage, configuration files are versioned with the program, but if other users want to use the program to work on their own studies, this can change.