Enable a configuration variable for pre_gen, enhance documentation

[knaegle]

**Feature request for pregeneration experiments **
After working with the pregeneration for a bit, we discovered a few things we would like to work differently.
Current behavior:

• When running with pregeneration and save_new pregeneration, KSTAR will only look into the global Network directory for pregeneration, not any place a user has generated data.

Increase places where pregen data is saved and looked for
Behavior changes:

• Add a new configuration variable, my_directory_for_pregen data. Add configuration instructions for users on how to set this. Create documentation that shows directory_for_save_precompute default is set to this configuration.
• Add a new flag in randomized_analysis that takes use_my_pregen_data. Change the flag use_pregen_data to use_global_pregen_data. Indicate in the documentation how these flags will work (if use_global_pregen_data is True, that global config directory will be checked first, then use_my_pregen_data will be checked).
• A third directory can be set using directory_for_save_precompute = "another_directory/". Indicate to users in documentation how if you only want to use this directory, you must set the other flags to False.
• Increase clarity on pregen versus precompute (maybe changing the name to be clear that precompute is for direct random datasets, not the results), also as we update the documetation, this is likely not a flag most people will set, to save the random datasets.
• Clarify in the documentation and behavior the difference between each of the modes.
• Clarify in documentation various user modes (e.g. the default user mode would have minimal information explicitly written such as num_random_experiments or the configuration directories if there's no intent to override them. Include comments for each of the flags/variables directly in the code.

[knaegle]

Current block of code in tutorial looks like this:

use_pregen_data = True
save_new_precompute = True
pregenerated_experiments_path = None
directory_for_save_precompute = "~/GIT/Data/KSTAR_2025/NETWORKS/NetworKIN/"
network_hash = None
save_random_experiments = False

#Set the number of random experiments
num_random_experiments=5 #let's make sure this is a default in randomized_analysis or make it a config variable so it doesn't have to be set. 

#Generate random experiments or use pregenerated random experiments
calculate.randomized_analysis(
    kinact_dict,
    activity_log,
    num_random_experiments, 
    use_pregen_data,
    save_new_precompute,
    pregenerated_experiments_path,
    directory_for_save_precompute,
    network_hash,
    save_random_experiments,
    PROCESSES=1)

Ideally the following block of code would work (this is moving some of these to default variables:

use_global_pregen_data = True #This will use config.PREGENERATED_EXPERIMENTS_PATH (setup during your configuration). Any matching random here will be used first. 
use_local_pregen_data = True #This will use config.PREGENERATED_LOCAL_EXPERIMENTS_PATH as the second place to look for and if you do not override pregenerated_experiments_path with a new directory, and you set save_new_pregenerated, then new experiments will be saved here as well. 
pregenerated_experiments_path = None # Default is this will point to  config.PREGENERATED_LOCAL_EXPERIMENTS_PATH if that is configured, or config.PREGENERATED_EXPERIMENTS_PATH if not. If you set this to a path, this will become the third location for checking pregenerated experiments and the location of any new pregenerated to be saved. 

#Generate random experiments or use pregenerated random experiments
calculate.randomized_analysis(
    kinact_dict,
    activity_log,
    num_random_experiments, 
    use_pregen_data,
    save_new_precompute,
    pregenerated_experiments_path)

[knaegle]

A note update - I'm running into an issue on the current if I set a new path, pregeneration is apparently unable to make one of the new subdirectories if it doesn't exist. Either Y or Y/hash or Y/hash/compendia_bias. This is an issue that should be corrected more immediately @levicuster

Also, it doesn't precheck that it will be able to write, so it first uses compute time during calculation before erroring out... We will want to move that up before starting the computation time and report an error robustly instead of a Python run time error.

[srcrowl]

Here are some of the changes that have been implemented in the dev branch to this point:

• For variable name, we always use pregenerated rather than precomputed to avoid confusion
• There is a new configuration parameter called 'CUSTOM_RANDOM_ACTIVITIES_DIR' which can be updated to indicate where newly generated random activities can be saved for future use.
• KSTAR will automatically look in both the default (within the package folder) or in the custom activities directory for appropriate pregenerated activities, selecting the one that is closest between the two. This is only relevant if a custom random activities directory is provided in the function or in the configuration. In conjuction, there is a new parameter in the get_random_activities() function called default_pregen_only which can be set to true if you don't want to use any custom random activities.
• Random experiment files and directories are checked before performing activity calculation
• As of now, we still do not allow a way to ignore the default random activities present in the NETWORKS directory

I think most of the code comments have been addressed, so now we mainly need to update the documentation to explain these differences.