Merge pull request #133 from drbergman-lab/development

v0.0.29

Author: drbergman

Project.toml

@@ -1,7 +1,7 @@
 name = "pcvct"
 uuid = "3c374bc7-7384-4f83-8ca0-87b8c727e6ff"
 authors = ["Daniel Bergman <[email protected]> and contributors"]
-version = "0.0.28"
+version = "0.0.29"
 
 [deps]
 AutoHashEquals = "15f4f7f2-30c1-5605-9d31-71845cf9641f"

docs/make.jl

@@ -26,6 +26,7 @@ makedocs(;
             "Sensitivity analysis" => "man/sensitivity_analysis.md",
             "Analyzing output" => "man/analyzing_output.md",
             "Developer guide" => "man/developer_guide.md",
+            "Project configuration" => "man/project_configuration.md",
             "Index" => "man/index.md",
         ],
         "Documentation" => map(

docs/src/lib/configuration.md

@@ -65,8 +65,8 @@ The following can be passed in as the third argument to `configPath(<substrate_n
 
 The following tokens work with a `cell_type` from your model:
 ```julia
-- `configPath(<cell_type>, "cycle_rate", "0")` (`cyclePath`)
-- `configPath(<cell_type>, "cycle_duration", "0")` (`cyclePath`)
+- `configPath(<cell_type>, "cycle_rate", <start_index>)` (`cyclePath`)
+- `configPath(<cell_type>, "cycle_duration", <index>)` (`cyclePath`)
 - `configPath(<cell_type>, "apoptosis", <parameter>)` (`apoptosisPath`)
 - `configPath(<cell_type>, "necrosis", <parameter>)` (`necrosisPath`)
 - `configPath(<cell_type>, "adhesion", <cell_type>)` (`mechanicsPath`)

docs/src/lib/ic_cell.md

@@ -4,7 +4,7 @@ CollapsedDocStrings = true
 
 # Cell Initial Conditions
 
-Functionality for the using [PhysiCellCellCreator.jl](https://github.com/drbergman/PhysiCellCellCreator.jl) to create and use PhysiCell IC cell XML files.
+Functionality for the using [PhysiCellCellCreator.jl](https://github.com/drbergman-lab/PhysiCellCellCreator.jl) to create and use PhysiCell IC cell XML files.
 
 ## Public API
 ```@autodocs

docs/src/lib/ic_ecm.md

@@ -4,7 +4,7 @@ CollapsedDocStrings = true
 
 # ECM Initial Conditions
 
-Functionality for the using [PhysiCellECMCreator.jl](https://github.com/drbergman/PhysiCellECMCreator.jl) to create and use PhysiCell ECM XML files.
+Functionality for the using [PhysiCellECMCreator.jl](https://github.com/drbergman-lab/PhysiCellECMCreator.jl) to create and use PhysiCell ECM XML files.
 
 ## Public API
 ```@autodocs

docs/src/man/data_directory.md

@@ -37,7 +37,7 @@ Add within `data/inputs/custom_codes/default/` the following, each exactly as is
 Add a single file within `data/inputs/rulesets_collections/default/` called `base_rulesets.csv` with the base ruleset collection for your PhysiCell project.
 If your project does not use rules, you can skip this step.
 
-You may also place an XML file here. Use [PhysiCellXMLRules.jl](https://github.com/drbergman/PhysiCellXMLRules.jl) to create one from a standard CSV version of the rules.
+You may also place an XML file here. Use [PhysiCellXMLRules.jl](https://github.com/drbergman-lab/PhysiCellXMLRules.jl) to create one from a standard CSV version of the rules.
 
 **Important**: In either case, the variations you define *must* be on the XML version.
 After calling `initializeModelManager()`, any folder with `base_rulesets.csv` will now be populated with a `base_rulesets.xml` file that can be reference to set the XML paths.
@@ -67,12 +67,12 @@ Proceed similarly for `dcs/`, `ecms/`, and `substrates/`, renaming those files t
 
 ### IC cells
 
-pcvct uses [PhysiCellCellCreator.jl](https://github.com/drbergman/PhysiCellCellCreator.jl) to allow for creation of `cells.csv` files based on geometries defined in a `cells.xml` file.
-To use this, first create such an XML document (see [PhysiCellCellCreator.jl](https://github.com/drbergman/PhysiCellCellCreator.jl) for details) and place this in place of the `cells.csv` file.
+pcvct uses [PhysiCellCellCreator.jl](https://github.com/drbergman-lab/PhysiCellCellCreator.jl) to allow for creation of `cells.csv` files based on geometries defined in a `cells.xml` file.
+To use this, first create such an XML document (see [PhysiCellCellCreator.jl](https://github.com/drbergman-lab/PhysiCellCellCreator.jl) for details) and place this in place of the `cells.csv` file.
 You may make variations on this in the same way as for `config` and `rulesets_collection`.
 
 ### IC ecm
 
-pcvct uses [PhysiCellECMCreator.jl](https://github.com/drbergman/PhysiCellECMCreator.jl) to allow for creation of `ecm.csv` files based on the structure defined in a `ecm.xml` file.
-To use this, first create such an XML document (see [PhysiCellECMCreator.jl](https://github.com/drbergman/PhysiCellECMCreator.jl) for details) and place this in place of the `ecm.csv` file.
+pcvct uses [PhysiCellECMCreator.jl](https://github.com/drbergman-lab/PhysiCellECMCreator.jl) to allow for creation of `ecm.csv` files based on the structure defined in a `ecm.xml` file.
+To use this, first create such an XML document (see [PhysiCellECMCreator.jl](https://github.com/drbergman-lab/PhysiCellECMCreator.jl) for details) and place this in place of the `ecm.csv` file.
 You may make variations on this in the same way as for `config` and `rulesets_collection`.

docs/src/man/project_configuration.md

@@ -0,0 +1,40 @@
+# Project configuration
+
+The `inputs.toml` file is used to configure the inputs for the project.
+It is located in the `inputs` directory within the project data directory.
+
+## TOML-defined structure
+Each section of the `inputs.toml` file defines one of the input "locations" in the project.
+An example of the structure is as follows:
+
+```toml
+[config]
+required = true
+varied = true
+basename = "PhysiCell_settings.xml"
+```
+
+Upon initialization of the model manager, i.e., calling `initializeModelManager()`, the `inputs.toml` file is parsed and each entry (`config` is shown above) has four features stored:
+- `required`: A boolean indicating if the location is required for the model to run.
+- `basename`: The base name of the file to be used for the location.
+- `varied`: A boolean indicating if the location can vary between different model runs.
+- `path_from_inputs`: The path to the location relative to the `inputs` directory.
+
+### `required`
+This field is necessary and must either be `true` or `false`.
+If `true`, an `InputsFolder` object cannot be created without this location.
+
+### `basename`
+This field enforces the name of the file to be used for the location.
+A vector can be supplied of names in the order to look for the files in cases when multiple files are acceptable.
+This field is necessary if `varied` is `true`, but can be omitted if `varied` is `false`.
+
+### `varied`
+This field is necessary and must either be `true`, `false`, or a vector of Booleans matching the length of the `basename` vector.
+If `true`, the location can be varied and the necessary databases and folders are created to support this.
+
+### `path_from_inputs`
+This optional field sets the path to the location relative to the `inputs` directory.
+If not provided, the path is assumed to be `inputs/<dict_name>s`.
+For example, the `config` section above would be located at `inputs/configs` (note the pluralization of the section name).
+To provide this path, use a vector of strings, e.g., `["ics", "cells"]` to define the path to the `[ic_cell]` location as `inputs/ics/cells`.

docs/src/man/xml_path_helpers.md

@@ -33,7 +33,7 @@ rulePath(<cell_type>, <behavior>, "decreasing_signals", "signal:name:<signal_nam
 ```
 
 ## Varying initial cell parameters
-pcvct supports an XML-based initialization of cell locations using [PhysiCellCellCreator.jl](https://github.com/drbergman/PhysiCellCellCreator.jl).
+pcvct supports an XML-based initialization of cell locations using [PhysiCellCellCreator.jl](https://github.com/drbergman-lab/PhysiCellCellCreator.jl).
 See the documentation of that package for details on how to create the XML file.
 Use [`pcvct.createICCellXMLTemplate`](@ref) to create a template XML file and automatically add it to the database.
 From there, you can edit it directly (though as per [Best practices](@ref) do not edit after simulations are created that rely on it).
@@ -45,15 +45,15 @@ The signature is as follows:
 icCellsPath(<cell_type>, <patch_type>, <patch_id>, <tag>)
 ```
 
-[PhysiCellCellCreator.jl](https://github.com/drbergman/PhysiCellCellCreator.jl) supports carveouts that can be used to not place cells within the given patches.
+[PhysiCellCellCreator.jl](https://github.com/drbergman-lab/PhysiCellCellCreator.jl) supports carveouts that can be used to not place cells within the given patches.
 These are contained in a child element of the patch element and their parameters can be varied using the following signature:
 
 ```julia
 icCellsPath(<cell_type>, <patch_type>, <patch_id>, <carveout_type>, <carveout_id>, <tag>)
 ```
 
 ## Varying initial ECM parameters
-pcvct supports an XML-based initialization of ECMs using [PhysiCellECMCreator.jl](https://github.com/drbergman/PhysiCellECMCreator.jl).
+pcvct supports an XML-based initialization of ECMs using [PhysiCellECMCreator.jl](https://github.com/drbergman-lab/PhysiCellECMCreator.jl).
 See the documentation of that package for details on how to create the XML file.
 Use [`pcvct.createICECMXMLTemplate`](@ref) to create a template XML file and automatically add it to the database.
 From there, you can edit it directly (though as per [Best practices](@ref) do not edit after simulations are created that rely on it).

docs/src/misc/database_upgrades.md

@@ -4,6 +4,9 @@ Not every release will change the database structure, but when one does in a way
 The warning will link to this page and the function will wait for user input to proceed.
 Changes are listed in reverse chronological order.
 
+## to v0.0.29
+The `inputs.toml` file has been moved from `data/` to `data/inputs/`.
+
 ## to v0.0.15
 Introduce XML-based ECM initial conditions. This introduces `ic_ecm_variations`.
 Also, introduce Dirichlet initial conditions from file, which introduces the `ic_dc_id` in the database.

src/classes.jl

@@ -57,13 +57,13 @@ Hold the information for a single input folder.
 Users should use the `InputFolders` to create and access individual `InputFolder` objects.
 
 # Fields
-- `location::Symbol`: The location of the input folder, e.g. `:config`, `:custom_code`, etc. Options are defined in `data/inputs.toml`.
+- `location::Symbol`: The location of the input folder, e.g. `:config`, `:custom_code`, etc. Options are defined in `data/inputs/inputs.toml`.
 - `id::Int`: The ID of the input folder in the database.
 - `folder::String`: The name of the input folder. It will be in `data/inputs/<path_from_inputs>`.
 - `basename::Union{String,Missing}`: The basename of the input file. This can be used to determine if the input file is varied.
-- `required::Bool`: Whether the input folder is required. This is defined in `data/inputs.toml`.
+- `required::Bool`: Whether the input folder is required. This is defined in `data/inputs/inputs.toml`.
 - `varied::Bool`: Whether the input folder is varied. This is determined by the presence of a varied basename in the input folder.
-- `path_from_inputs::String`: The path from the `data/inputs` directory to the input folder. This is defined in `data/inputs.toml`.
+- `path_from_inputs::String`: The path from the `data/inputs` directory to the input folder. This is defined in `data/inputs/inputs.toml`.
 """
 struct InputFolder
     location::Symbol
@@ -124,7 +124,7 @@ end
 Consolidate the folder information for a simulation/monad/sampling.
 
 Pass the folder names within the `inputs/<path_from_inputs>` directory to create an `InputFolders` object.
-The `path_from_inputs` is defined in the `data/inputs.toml` file for each.
+The `path_from_inputs` is defined in the `data/inputs/inputs.toml` file for each.
 It is possible to acces the [`InputFolder`](@ref) values using index notation, e.g. `input_folders[:config]`.
 
 Several constructors exist:
@@ -133,7 +133,7 @@ Several constructors exist:
 InputFolders(; config="default", custom_codes="default", rulesets_collection="default")
 ```
 2. Pass in the required inputs as arguments and the optional inputs as keyword arguments. The required folders must be passed in alphabetical order.
-Refer to the names defined in `data/inputs.toml` to see this order. Omitted optional folders are assumed to be \"\", i.e. those inputs are unused.
+Refer to the names defined in `data/inputs/inputs.toml` to see this order. Omitted optional folders are assumed to be \"\", i.e. those inputs are unused.
 ```julia
 config_folder = "default"
 custom_code_folder = "default"
@@ -142,7 +142,7 @@ InputFolders(config_folder, custom_code_folder; ic_cell=ic_cell_folder)
 ```
 
 # Fields
-- `input_folders::NamedTuple`: The input locations defined in `data/inputs.toml` define the keys. The values are [`InputFolder`](@ref)s.
+- `input_folders::NamedTuple`: The input locations defined in `data/inputs/inputs.toml` define the keys. The values are [`InputFolder`](@ref)s.
 """
 struct InputFolders
     input_folders::NamedTuple
@@ -169,7 +169,7 @@ function InputFolders(args...; kwargs...) end
 """
     createSimpleInputFolders()
 
-Creates a simple method for creating `InputFolders` objects at module initialization based on `data/inputs.toml`.
+Creates a simple method for creating `InputFolders` objects at module initialization based on `data/inputs/inputs.toml`.
 
 The required inputs are sorted alphabetically and used as the positional arguments.
 The optional inputs are used as keyword arguments with a default value of `\"\"`, indicating they are unused.